@legioncodeinc/nectar 0.0.1

package/dist/telemetry/db.js

@@ -0,0 +1,122 @@
+/**
+ * Shared `node:sqlite` plumbing for nectar's local telemetry database
+ * (PRD-017, doctor ADR-0001 / ADR-0002).
+ *
+ * ONE physical file (`~/.honeycomb/telemetry/nectar.sqlite` by default),
+ * three tables, per the pinned Contract B shared with doctor:
+ *   - `service_status`  single row (id=1, latest-wins): binding time, last-seen,
+ *     health, and Deep Lake connectivity (PRD-017a).
+ *   - `service_metrics` single row (id=1, latest-wins): the 5 since-restart
+ *     pipeline counters (PRD-017b).
+ *   - `service_logs`    append-only, bounded/rotated by `logs.ts` (PRD-017c).
+ *
+ * Mirrors honeycomb's `daemon/runtime/logs/log-store.ts` precedent: `node:sqlite`
+ * is loaded via a DYNAMIC `require` (never a top-level import), so a Node that
+ * lacks the module (older than 22.5, or missing `--experimental-sqlite`) throws
+ * HERE and is caught by the fail-soft facade in `index.ts` (AC-7 / AC-017a's
+ * "never blocks boot or the pipeline"), rather than crashing at module load.
+ *
+ * WAL mode is set on open so doctor's read-only poller (~1s cadence, per
+ * ADR-0001) never contends with nectar's own writes. doctor is the ONLY
+ * external reader, and it opens read-only; this module is nectar's write
+ * side only.
+ */
+import { chmodSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { RUNTIME_DIR_NAME } from "../config.js";
+/** The subdirectory of the runtime dir the telemetry database lives under. */
+export const TELEMETRY_DIR_NAME = "telemetry";
+/** The telemetry database's filename, matching doctor's per-service naming (`<name>.sqlite`). */
+export const TELEMETRY_DB_FILE_NAME = "nectar.sqlite";
+/** Derive the telemetry DB path from a resolved runtime dir (keeps it alongside the pid/lock files). */
+export function telemetryDbPathForRuntimeDir(runtimeDir) {
+    return join(runtimeDir, TELEMETRY_DIR_NAME, TELEMETRY_DB_FILE_NAME);
+}
+/** The default telemetry DB path: `~/.honeycomb/telemetry/nectar.sqlite`. */
+export function defaultTelemetryDbPath(home = homedir()) {
+    return telemetryDbPathForRuntimeDir(join(home, RUNTIME_DIR_NAME));
+}
+/**
+ * Load `node:sqlite` via a dynamic `require` (via `module.createRequire`, so it
+ * works under ESM) rather than a top-level import: a Node build without the
+ * module/flag throws HERE, inside the caller's try/catch, instead of crashing
+ * the whole daemon bundle at load time.
+ */
+function loadSqlite() {
+    const req = createRequire(import.meta.url);
+    return req("node:sqlite");
+}
+/**
+ * Open (or create) the telemetry database at `dbPath` in WAL mode, creating all
+ * three tables (idempotent, additive) if absent. Throws on any failure (missing
+ * `node:sqlite`, an unwritable directory, a corrupt file, ...); the caller
+ * (`index.ts`'s `createTelemetry`) catches and degrades to a no-op rather than
+ * ever propagating into daemon boot or the nectar pipeline.
+ */
+export function openTelemetryDb(dbPath) {
+    const dbDir = dirname(dbPath);
+    // SECURITY (security-review finding, medium): owner-only mode, matching honeycomb's
+    // fleet-store.ts precedent. Without it, the default umask on a multi-user host often
+    // yields a world-readable/traversable directory, letting another local user read
+    // service_logs (paths, errors, partially-redacted text) and operational metrics.
+    mkdirSync(dbDir, { recursive: true, mode: 0o700 });
+    // mkdirSync's mode only applies to directories it CREATES; a telemetry dir
+    // left behind by a pre-fix install keeps its broader bits, so enforce
+    // owner-only explicitly too. POSIX mode bits are meaningless on Windows.
+    if (process.platform !== "win32")
+        chmodSync(dbDir, 0o700);
+    const sqlite = loadSqlite();
+    const db = new sqlite.DatabaseSync(dbPath);
+    try {
+        db.exec("PRAGMA journal_mode = WAL");
+        migrateSchema(db);
+        return db;
+    }
+    catch (err) {
+        // Close the native handle before rethrowing into the fail-soft fallback,
+        // so a half-initialized open never leaks a descriptor/lock on the db path.
+        try {
+            db.close();
+        }
+        catch {
+            // ignore cleanup failures on the fail-soft path
+        }
+        throw err;
+    }
+}
+/**
+ * Create the three telemetry tables + the log index if absent. Column/table
+ * names are fixed literal constants under our own control (never interpolated
+ * user input), matching the pinned Contract B schema doctor's poller reads
+ * verbatim - schema drift here is a cross-repo break, not a local style choice.
+ */
+function migrateSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS service_status (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      name TEXT NOT NULL,
+      binding_time TEXT NOT NULL,
+      last_seen TEXT NOT NULL,
+      health TEXT NOT NULL,
+      deeplake_connected INTEGER,
+      deeplake_last_comm TEXT
+    )`);
+    db.exec(`CREATE TABLE IF NOT EXISTS service_metrics (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      files_registered INTEGER NOT NULL DEFAULT 0,
+      nectars_minted INTEGER NOT NULL DEFAULT 0,
+      descriptions_generated INTEGER NOT NULL DEFAULT 0,
+      hive_graph_versions INTEGER NOT NULL DEFAULT 0,
+      embeddings_computed INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL
+    )`);
+    db.exec(`CREATE TABLE IF NOT EXISTS service_logs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts TEXT NOT NULL,
+      level TEXT NOT NULL CHECK (level IN ('error','warn','info','debug')),
+      message TEXT NOT NULL
+    )`);
+    db.exec("CREATE INDEX IF NOT EXISTS idx_service_logs_ts ON service_logs(ts DESC)");
+}
+//# sourceMappingURL=db.js.map

package/dist/telemetry/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/telemetry/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC;AAC9C,iGAAiG;AACjG,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAEtD,wGAAwG;AACxG,MAAM,UAAU,4BAA4B,CAAC,UAAkB;IAC7D,OAAO,IAAI,CAAC,UAAU,EAAE,kBAAkB,EAAE,sBAAsB,CAAC,CAAC;AACtE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CAAC,OAAe,OAAO,EAAE;IAC7D,OAAO,4BAA4B,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;AACpE,CAAC;AAuBD;;;;;GAKG;AACH,SAAS,UAAU;IACjB,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,OAAO,GAAG,CAAC,aAAa,CAAiB,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,oFAAoF;IACpF,qFAAqF;IACrF,iFAAiF;IACjF,iFAAiF;IACjF,SAAS,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,2EAA2E;IAC3E,sEAAsE;IACtE,yEAAyE;IACzE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QACrC,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,CAAC;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,gDAAgD;QAClD,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,EAAsB;IAC3C,EAAE,CAAC,IAAI,CACL;;;;;;;;MAQE,CACH,CAAC;IACF,EAAE,CAAC,IAAI,CACL;;;;;;;;MAQE,CACH,CAAC;IACF,EAAE,CAAC,IAAI,CACL;;;;;MAKE,CACH,CAAC;IACF,EAAE,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;AACrF,CAAC"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The fail-soft telemetry facade (PRD-017), composing the check-in, metrics,
+ * and log writers behind ONE object `daemon.ts` (and, later, the registration
+ * pipeline) depends on.
+ *
+ * `createTelemetry()` NEVER throws (AC-7): opening the local SQLite database
+ * (`node:sqlite`, WAL mode, `db.ts`) is wrapped in a try/catch, and a failure
+ * degrades to {@link NULL_TELEMETRY} - a no-op that keeps the daemon boot and
+ * the nectar pipeline completely unaffected. Every method on the real,
+ * DB-backed implementation is individually fail-soft too (see `checkin.ts`,
+ * `metrics.ts`, `logs.ts`), so a write failure MID-LIFE (a locked file, a full
+ * disk) degrades the same way a failed OPEN does.
+ */
+import type { PipelineStatus } from "../health.js";
+import type { Timer } from "../poll-loop.js";
+import type { AsyncHiveGraphStore, HiveGraphStore } from "../hive-graph/store.js";
+import { type LogLevel } from "./logs.js";
+import { type MetricsSnapshot, type PipelineMetricsSink } from "./metrics.js";
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, CheckinService, CheckinWriter, } from "./checkin.js";
+export { defaultTelemetryDbPath, telemetryDbPathForRuntimeDir, TELEMETRY_DIR_NAME, TELEMETRY_DB_FILE_NAME, type SqliteDatabaseLike, } from "./db.js";
+export { DEFAULT_LOG_MAX_AGE_MS, MAX_LOG_MESSAGE_LENGTH, LOG_LEVELS, LogWriter, createLogTap, redactLogMessage, levelFromLine, messageFromLine, type LogLevel, type LogSink, } from "./logs.js";
+export { MetricsWriter, wrapStoreWithMetrics, wrapAsyncStoreWithMetrics, type MetricsSnapshot, type PipelineMetricsSink, } from "./metrics.js";
+export interface StopHeartbeat {
+    (): void;
+}
+export interface StartCheckinOptions {
+    readonly intervalMs?: number;
+    readonly timer?: Timer;
+}
+export interface Telemetry {
+    /** False when the local SQLite telemetry store could not be opened (AC-7); every method below is then a no-op. */
+    readonly enabled: boolean;
+    /** The database path this instance was opened against (or would have been). */
+    readonly dbPath: string;
+    /** The 5-counter since-restart metrics sink (PRD-017b). A no-op sink when `enabled` is false. */
+    readonly metrics: PipelineMetricsSink;
+    /** Read back the current metrics snapshot (test/introspection convenience). */
+    metricsSnapshot(): MetricsSnapshot;
+    /** Check in once, then heartbeat on an interval until the returned stop function is called (PRD-017a). */
+    startCheckin(health: () => PipelineStatus, opts?: StartCheckinOptions): StopHeartbeat;
+    /** Mirror one log line into `service_logs` (PRD-017c). Prefer `createLogTap` to wrap an existing sink. */
+    log(level: LogLevel, message: string): void;
+    /** Wrap a `HiveGraphStore` so nectar mints and version writes increment their counters at the real write (PRD-017b). */
+    wrapStore<T extends HiveGraphStore>(store: T): T;
+    /**
+     * Wrap an `AsyncHiveGraphStore` (the durable Deep Lake substrate) so the same
+     * counters increment on the LIVE brood path (PRD-017b). This is what moves the
+     * `descriptionsGenerated` / `hiveGraphVersions` / `embeddingsComputed` counters
+     * off 0 once a real daemon broods against Deep Lake.
+     */
+    wrapAsyncStore<T extends AsyncHiveGraphStore>(store: T): T;
+    /** Close the backing SQLite handle (idempotent, never throws). */
+    close(): void;
+}
+export interface CreateTelemetryOptions {
+    /** Override the database path (default: {@link defaultTelemetryDbPath}). */
+    readonly dbPath?: string;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    now?(): string;
+    /** A one-time failure sink for the open failure (defaults to a single stderr write). Never called per-write. */
+    onceFailure?(message: string): void;
+}
+/**
+ * The no-op telemetry the daemon falls back to when the local SQLite store is
+ * unavailable (AC-7), and the placeholder `daemon.ts` holds before the first
+ * `start()` (constructing/importing the daemon must never touch disk).
+ */
+export declare function createNullTelemetry(dbPath: string): Telemetry;
+/**
+ * Open nectar's telemetry store and return the composed facade. NEVER
+ * throws: an open failure is reported ONCE (never per-write) and this returns
+ * {@link nullTelemetry} so the caller's boot sequence is completely unaffected
+ * (AC-7).
+ */
+export declare function createTelemetry(opts?: CreateTelemetryOptions): Telemetry;
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGlF,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,6BAA6B,EAC7B,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,UAAU,EACV,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,KAAK,QAAQ,EACb,KAAK,OAAO,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,CAAC;CACV;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,kHAAkH;IAClH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,+EAA+E;IAC/E,eAAe,IAAI,eAAe,CAAC;IACnC,0GAA0G;IAC1G,YAAY,CAAC,MAAM,EAAE,MAAM,cAAc,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAAC;IACtF,0GAA0G;IAC1G,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,wHAAwH;IACxH,SAAS,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IACjD;;;;;OAKG;IACH,cAAc,CAAC,CAAC,SAAS,mBAAmB,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3D,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,GAAG,CAAC,IAAI,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAWD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAyB7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,sBAA2B,GAAG,SAAS,CA2C5E"}

package/dist/telemetry/index.js

@@ -0,0 +1,98 @@
+import { CheckinService, CheckinWriter } from "./checkin.js";
+import { defaultTelemetryDbPath, openTelemetryDb } from "./db.js";
+import { LogWriter } from "./logs.js";
+import { MetricsWriter, wrapAsyncStoreWithMetrics, wrapStoreWithMetrics, } from "./metrics.js";
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, CheckinService, CheckinWriter, } from "./checkin.js";
+export { defaultTelemetryDbPath, telemetryDbPathForRuntimeDir, TELEMETRY_DIR_NAME, TELEMETRY_DB_FILE_NAME, } from "./db.js";
+export { DEFAULT_LOG_MAX_AGE_MS, MAX_LOG_MESSAGE_LENGTH, LOG_LEVELS, LogWriter, createLogTap, redactLogMessage, levelFromLine, messageFromLine, } from "./logs.js";
+export { MetricsWriter, wrapStoreWithMetrics, wrapAsyncStoreWithMetrics, } from "./metrics.js";
+function defaultOnceFailure() {
+    let fired = false;
+    return (message) => {
+        if (fired)
+            return;
+        fired = true;
+        process.stderr.write(`${message}\n`);
+    };
+}
+/**
+ * The no-op telemetry the daemon falls back to when the local SQLite store is
+ * unavailable (AC-7), and the placeholder `daemon.ts` holds before the first
+ * `start()` (constructing/importing the daemon must never touch disk).
+ */
+export function createNullTelemetry(dbPath) {
+    const noopMetrics = {
+        incrementFilesRegistered() { },
+        incrementNectarsMinted() { },
+        incrementDescriptionsGenerated() { },
+        incrementHiveGraphVersions() { },
+        incrementEmbeddingsComputed() { },
+    };
+    return {
+        enabled: false,
+        dbPath,
+        metrics: noopMetrics,
+        metricsSnapshot: () => ({
+            filesRegistered: 0,
+            nectarsMinted: 0,
+            descriptionsGenerated: 0,
+            hiveGraphVersions: 0,
+            embeddingsComputed: 0,
+        }),
+        startCheckin: () => () => { },
+        log: () => { },
+        wrapStore: (store) => store,
+        wrapAsyncStore: (store) => store,
+        close: () => { },
+    };
+}
+/**
+ * Open nectar's telemetry store and return the composed facade. NEVER
+ * throws: an open failure is reported ONCE (never per-write) and this returns
+ * {@link nullTelemetry} so the caller's boot sequence is completely unaffected
+ * (AC-7).
+ */
+export function createTelemetry(opts = {}) {
+    const dbPath = opts.dbPath ?? defaultTelemetryDbPath();
+    const onceFailure = opts.onceFailure ?? defaultOnceFailure();
+    let db;
+    try {
+        db = openTelemetryDb(dbPath);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        onceFailure(`nectar: telemetry unavailable (non-fatal), continuing without it: ${reason}`);
+        return createNullTelemetry(dbPath);
+    }
+    const checkinWriter = new CheckinWriter({ db, now: opts.now });
+    const metricsWriter = new MetricsWriter({ db, now: opts.now });
+    const logWriter = new LogWriter({ db, now: opts.now });
+    return {
+        enabled: true,
+        dbPath,
+        metrics: metricsWriter,
+        metricsSnapshot: () => metricsWriter.snapshot(),
+        startCheckin: (health, startOpts = {}) => {
+            const service = new CheckinService({
+                writer: checkinWriter,
+                health,
+                intervalMs: startOpts.intervalMs,
+                timer: startOpts.timer,
+            });
+            service.start();
+            return () => service.stop();
+        },
+        log: (level, message) => logWriter.write(level, message),
+        wrapStore: (store) => wrapStoreWithMetrics(store, metricsWriter),
+        wrapAsyncStore: (store) => wrapAsyncStoreWithMetrics(store, metricsWriter),
+        close: () => {
+            try {
+                db.close();
+            }
+            catch {
+                // Closing an already-closed/errored handle must never throw out of shutdown.
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

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

package/dist/telemetry/logs.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Bounded, rotated log emission to local SQLite (PRD-017c), per doctor's
+ * `ADR-0001-hive-telemetry-transport-and-single-source-of-truth.md`.
+ *
+ * `service_logs` is append-only but bounded: every write opportunistically
+ * rotates out rows older than {@link DEFAULT_LOG_MAX_AGE_MS} (AC-017c.2), so
+ * the store never grows without limit and stays cheap for doctor's ~1s
+ * poll cycle. The retention policy is an AGE bound (decision #33, 2026-07-02,
+ * `PRD-DECISIONS-AND-DEFAULTS.md`), superseding the original 5,000-row cap:
+ * a quiet daemon keeps at most a day of history instead of an unbounded-age
+ * tail of stale lines. Consumers are unaffected (doctor reads whatever
+ * rows exist).
+ *
+ * `createLogTap` mirrors nectar's EXISTING structured daemon log sink
+ * (`daemon.ts`'s `(line: Record<string, unknown>) => void`) into this table,
+ * rather than introducing a second logging framework: every line the daemon
+ * already logs to stderr is ALSO redacted and written here, unchanged in its
+ * original stderr behavior. nectar's structured log lines only ever carry
+ * scope/message/error-string/path fields (see `daemon.ts`, `registration/
+ * service.ts`) - never raw file content or an LLM description body - so the
+ * redaction pass below is defense-in-depth, not the sole guarantee.
+ */
+import type { SqliteDatabaseLike } from "./db.js";
+export type LogLevel = "error" | "warn" | "info" | "debug";
+export declare const LOG_LEVELS: readonly LogLevel[];
+/** The maximum age a log row is retained (decision #33: 24h age bound, superseding Contract B's 5,000-row cap). */
+export declare const DEFAULT_LOG_MAX_AGE_MS: number;
+/**
+ * A message longer than this is dropped rather than written (PRD-017c: "if a
+ * line cannot be safely redacted it is dropped"). A nectar structured log
+ * line (scope + a short message + maybe a path/error string) is always well
+ * under this; anything longer is far more likely to be an accidentally-passed
+ * file body or LLM description than a real operational log line, so length
+ * alone is a cheap, effective backstop against exactly the two payloads
+ * AC-017c.3.2 forbids.
+ */
+export declare const MAX_LOG_MESSAGE_LENGTH = 2000;
+/**
+ * Redact secret-shaped substrings from `message`. Returns null (drop the line
+ * entirely) when the message is too long to plausibly be a normal operational
+ * log line (AC-017c.3.2's "cannot be safely redacted" case).
+ */
+export declare function redactLogMessage(message: string): string | null;
+export interface LogWriterOptions {
+    readonly db: SqliteDatabaseLike;
+    /** Retention age bound in milliseconds (default: {@link DEFAULT_LOG_MAX_AGE_MS}). */
+    readonly maxAgeMs?: number;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    now?(): string;
+}
+export declare class LogWriter {
+    private readonly db;
+    private readonly maxAgeMs;
+    private readonly nowFn;
+    constructor(opts: LogWriterOptions);
+    /** Append one log row (AC-017c.1.1/3.1) and rotate. Fail-soft (AC-7 / AC-017c). */
+    write(level: LogLevel, message: string): void;
+    /**
+     * Delete rows older than the `maxAgeMs` bound (AC-017c.2.1/2.2). ISO-8601 UTC
+     * timestamps compare correctly as strings, so the cutoff is a plain `<`.
+     * Fail-soft, including against a non-parseable injected "now" (no cutoff can
+     * be computed, so nothing is deleted rather than everything).
+     */
+    private rotate;
+}
+/** Map a structured log line's `level` field to a declared verbosity, defaulting to "info". */
+export declare function levelFromLine(line: Record<string, unknown>): LogLevel;
+/** Render a structured log line (minus its `level`, stored in its own column) as the row's message text. */
+export declare function messageFromLine(line: Record<string, unknown>): string;
+/** The minimal sink `createLogTap` mirrors lines into (satisfied by the `Telemetry` facade in `index.ts`). */
+export interface LogSink {
+    log(level: LogLevel, message: string): void;
+}
+/**
+ * Wrap nectar's existing structured log sink so every line is ALSO
+ * mirrored into the telemetry log table, unchanged in its original behavior
+ * (the wrapped sink is always called first, with the exact original line).
+ * A telemetry-mirror failure is swallowed here too, on top of `LogWriter`'s
+ * own fail-soft `write()`, so a telemetry hiccup can never affect the
+ * caller's real log sink.
+ */
+export declare function createLogTap(baseLog: (line: Record<string, unknown>) => void, sink: LogSink): (line: Record<string, unknown>) => void;
+//# sourceMappingURL=logs.d.ts.map

package/dist/telemetry/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/telemetry/logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAuC,CAAC;AAElF,mHAAmH;AACnH,eAAO,MAAM,sBAAsB,QAAuB,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAQ5C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,GAAG,CAAC,IAAI,MAAM,CAAC;CAChB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,IAAI,EAAE,gBAAgB;IAMlC,mFAAmF;IACnF,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAW7C;;;;;OAKG;IACH,OAAO,CAAC,MAAM;CAUf;AAOD,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAErE;AAED,4GAA4G;AAC5G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAOrE;AAED,8GAA8G;AAC9G,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAChD,IAAI,EAAE,OAAO,GACZ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CASzC"}

package/dist/telemetry/logs.js

@@ -0,0 +1,110 @@
+export const LOG_LEVELS = ["error", "warn", "info", "debug"];
+/** The maximum age a log row is retained (decision #33: 24h age bound, superseding Contract B's 5,000-row cap). */
+export const DEFAULT_LOG_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+/**
+ * A message longer than this is dropped rather than written (PRD-017c: "if a
+ * line cannot be safely redacted it is dropped"). A nectar structured log
+ * line (scope + a short message + maybe a path/error string) is always well
+ * under this; anything longer is far more likely to be an accidentally-passed
+ * file body or LLM description than a real operational log line, so length
+ * alone is a cheap, effective backstop against exactly the two payloads
+ * AC-017c.3.2 forbids.
+ */
+export const MAX_LOG_MESSAGE_LENGTH = 2_000;
+/** Secret-shaped substrings redacted before a line is written (defense-in-depth; see module doc). */
+const SENSITIVE_PATTERNS = [
+    /\bBearer\s+[^\s"',}\]]+/gi,
+    /"?(authorization|api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|secret|password|client[_-]?secret)"?\s*[:=]\s*"?[^",}\s]+"?/gi,
+];
+/**
+ * Redact secret-shaped substrings from `message`. Returns null (drop the line
+ * entirely) when the message is too long to plausibly be a normal operational
+ * log line (AC-017c.3.2's "cannot be safely redacted" case).
+ */
+export function redactLogMessage(message) {
+    if (message.length > MAX_LOG_MESSAGE_LENGTH)
+        return null;
+    let out = message;
+    for (const pattern of SENSITIVE_PATTERNS)
+        out = out.replace(pattern, "[REDACTED]");
+    return out;
+}
+export class LogWriter {
+    db;
+    maxAgeMs;
+    nowFn;
+    constructor(opts) {
+        this.db = opts.db;
+        this.maxAgeMs = Math.max(1, opts.maxAgeMs ?? DEFAULT_LOG_MAX_AGE_MS);
+        this.nowFn = opts.now ?? (() => new Date().toISOString());
+    }
+    /** Append one log row (AC-017c.1.1/3.1) and rotate. Fail-soft (AC-7 / AC-017c). */
+    write(level, message) {
+        const safeMessage = redactLogMessage(message);
+        if (safeMessage === null)
+            return; // unredactable/oversized: dropped, never written (AC-017c.3.2).
+        try {
+            this.db.prepare("INSERT INTO service_logs (ts, level, message) VALUES (?, ?, ?)").run(this.nowFn(), level, safeMessage);
+            this.rotate();
+        }
+        catch {
+            // fail-soft: a log write error never surfaces into the pipeline.
+        }
+    }
+    /**
+     * Delete rows older than the `maxAgeMs` bound (AC-017c.2.1/2.2). ISO-8601 UTC
+     * timestamps compare correctly as strings, so the cutoff is a plain `<`.
+     * Fail-soft, including against a non-parseable injected "now" (no cutoff can
+     * be computed, so nothing is deleted rather than everything).
+     */
+    rotate() {
+        try {
+            const nowMs = Date.parse(this.nowFn());
+            if (!Number.isFinite(nowMs))
+                return;
+            const cutoff = new Date(nowMs - this.maxAgeMs).toISOString();
+            this.db.prepare("DELETE FROM service_logs WHERE ts < ?").run(cutoff);
+        }
+        catch {
+            // fail-soft: a rotation error never surfaces into the pipeline.
+        }
+    }
+}
+/** True iff `value` is one of the four declared verbosity levels. */
+function isLogLevel(value) {
+    return typeof value === "string" && LOG_LEVELS.includes(value);
+}
+/** Map a structured log line's `level` field to a declared verbosity, defaulting to "info". */
+export function levelFromLine(line) {
+    return isLogLevel(line["level"]) ? line["level"] : "info";
+}
+/** Render a structured log line (minus its `level`, stored in its own column) as the row's message text. */
+export function messageFromLine(line) {
+    const { level: _level, ...rest } = line;
+    try {
+        return JSON.stringify(rest);
+    }
+    catch {
+        return String(rest);
+    }
+}
+/**
+ * Wrap nectar's existing structured log sink so every line is ALSO
+ * mirrored into the telemetry log table, unchanged in its original behavior
+ * (the wrapped sink is always called first, with the exact original line).
+ * A telemetry-mirror failure is swallowed here too, on top of `LogWriter`'s
+ * own fail-soft `write()`, so a telemetry hiccup can never affect the
+ * caller's real log sink.
+ */
+export function createLogTap(baseLog, sink) {
+    return (line) => {
+        baseLog(line);
+        try {
+            sink.log(levelFromLine(line), messageFromLine(line));
+        }
+        catch {
+            // fail-soft: never let the telemetry mirror affect the real log sink above.
+        }
+    };
+}
+//# sourceMappingURL=logs.js.map

package/dist/telemetry/logs.js.map

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

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,82 @@
+import type { AsyncHiveGraphStore, HiveGraphStore } from "../hive-graph/store.js";
+import type { SqliteDatabaseLike } from "./db.js";
+export interface MetricsSnapshot {
+    readonly filesRegistered: number;
+    readonly nectarsMinted: number;
+    readonly descriptionsGenerated: number;
+    readonly hiveGraphVersions: number;
+    readonly embeddingsComputed: number;
+}
+/** The counter-increment surface pipeline touchpoints depend on (never the writer's SQLite internals). */
+export interface PipelineMetricsSink {
+    /** One file processed through the re-association ladder (PRD-006), any outcome. */
+    incrementFilesRegistered(): void;
+    /** One fresh nectar minted (ladder step 5). */
+    incrementNectarsMinted(): void;
+    /** One LLM description produced (the enricher/brooding loop, PRD-007/PRD-016). */
+    incrementDescriptionsGenerated(): void;
+    /** One `hive_graph_versions` row written (PRD-005). */
+    incrementHiveGraphVersions(): void;
+    /** One embedding computed (PRD-014). */
+    incrementEmbeddingsComputed(): void;
+}
+export interface MetricsWriterOptions {
+    readonly db: SqliteDatabaseLike;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    now?(): string;
+}
+export declare class MetricsWriter implements PipelineMetricsSink {
+    private readonly db;
+    private readonly nowFn;
+    private counts;
+    constructor(opts: MetricsWriterOptions);
+    snapshot(): MetricsSnapshot;
+    incrementFilesRegistered(): void;
+    incrementNectarsMinted(): void;
+    incrementDescriptionsGenerated(): void;
+    incrementHiveGraphVersions(): void;
+    incrementEmbeddingsComputed(): void;
+    private flush;
+}
+/**
+ * Wrap a {@link HiveGraphStore} so the two counters with a precise 1:1
+ * store-level definition increment at their REAL completion point, with ZERO
+ * changes to the ladder (`registration/ladder.ts`) or the store adapters:
+ *
+ *   - `nectarsMinted`: one `insertIdentity()` call = one freshly minted nectar
+ *     (the ladder's step-5 `mintOrCopy` is the only caller in this repo). A
+ *     THROWING insert (duplicate nectar, the store's own dedup guard) never
+ *     increments, because the throw happens before the increment line below -
+ *     no double counting across a rejected mint.
+ *   - `hiveGraphVersions`: one `appendVersion()` call = one
+ *     `hive_graph_versions` row written (ladder steps 2/3/4/5), the exact
+ *     PRD-005 catalog write.
+ *
+ * `descriptionsGenerated` and `embeddingsComputed` are wired to the CLOSEST
+ * REAL signal available in this repo today rather than a fabricated hook: a
+ * version row only ever carries `describeStatus === "described"` or a
+ * non-null `embedding` once the enricher (PRD-007/PRD-016) and the embeddings
+ * provider (PRD-014) actually populate those fields on the row they pass to
+ * `appendVersion`. Neither pipeline exists in this repo yet - `ladder.ts`'s
+ * `baseVersion()` always writes `title/description: ""`, `describeStatus:
+ * "pending"`, and `embedding: null` - so both counters correctly read 0 until
+ * those PRDs land. This is a documented, intentional approximation (see the
+ * PRD-017 ledger evidence): the day a future PRD starts writing a "described"
+ * row or a non-null embedding through this same `appendVersion` call, the
+ * counter starts moving with no further wiring required.
+ */
+export declare function wrapStoreWithMetrics<T extends HiveGraphStore>(store: T, sink: PipelineMetricsSink): T;
+/**
+ * The async twin of {@link wrapStoreWithMetrics}: wrap an
+ * {@link AsyncHiveGraphStore} so the same four store-level counters increment at
+ * their REAL completion point on the LIVE (durable) brood path, with ZERO
+ * changes to `runBroodAsync` or the Deep Lake adapter. The increment fires only
+ * AFTER the awaited write resolves - a rejected `insertIdentity` (the mint dedup
+ * guard) or `appendVersion` never increments, because the `await` throws before
+ * the increment line. This is what makes the PRD-017b `descriptionsGenerated` /
+ * `hiveGraphVersions` / `embeddingsComputed` / `nectarsMinted` counters move in
+ * production once the daemon actually broods against Deep Lake (the counters that
+ * previously stayed 0 because the pipeline never ran on the live boot path).
+ */
+export declare function wrapAsyncStoreWithMetrics<T extends AsyncHiveGraphStore>(store: T, sink: PipelineMetricsSink): T;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,0GAA0G;AAC1G,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,wBAAwB,IAAI,IAAI,CAAC;IACjC,+CAA+C;IAC/C,sBAAsB,IAAI,IAAI,CAAC;IAC/B,kFAAkF;IAClF,8BAA8B,IAAI,IAAI,CAAC;IACvC,uDAAuD;IACvD,0BAA0B,IAAI,IAAI,CAAC;IACnC,wCAAwC;IACxC,2BAA2B,IAAI,IAAI,CAAC;CACrC;AAoBD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,0DAA0D;IAC1D,GAAG,CAAC,IAAI,MAAM,CAAC;CAChB;AAED,qBAAa,aAAc,YAAW,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,MAAM,CAA+B;gBAEjC,IAAI,EAAE,oBAAoB;IAQtC,QAAQ,IAAI,eAAe;IAI3B,wBAAwB,IAAI,IAAI;IAKhC,sBAAsB,IAAI,IAAI;IAK9B,8BAA8B,IAAI,IAAI;IAKtC,0BAA0B,IAAI,IAAI;IAKlC,2BAA2B,IAAI,IAAI;IAKnC,OAAO,CAAC,KAAK;CA0Bd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,CAAC,CAoBrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,CAAC,CAoB/G"}