@yadsh/dsh-kv-persist 0.1.0

package/lib/logging/plugin-logger.js

@@ -0,0 +1,397 @@
+/**
+ * Plugin file logger — the seed of the future `@yadsh/dsh-plugin-log` package.
+ *
+ * Every plugin currently carries its own verbatim copy of `src/logging/`
+ * (guidelines §5.2); the exported API below is frozen so that switching to
+ * the extracted package later is a one-line import change. The wrapper:
+ *
+ * - wraps `pino` for severity levels and NDJSON serialization;
+ * - writes daily files `<dir>/<YYYY-MM-DD>.log`, by default under
+ *   `<$DSH_HOME>/logs/<pluginId>`;
+ * - mirrors selected records to an injectable console sink (default level
+ *   `warn`) so operators still see problems live;
+ * - never throws at runtime: file-system failures degrade to console-only
+ *   logging (fail-open), and closed loggers silently drop records;
+ * - disables file output when `DSH_LOG_DISABLED=1`, and under `NODE_ENV=test`
+ *   unless `dir` is set explicitly (unit tests never touch a real home).
+ *
+ * Record shape (one JSON object per line): pino's `level` (numeric),
+ * `time` (epoch ms) and `msg` (= the event code), plus `plugin` and the
+ * caller's fields; `child(module)` adds `module`. Reserved pino keys
+ * (`level`, `time`, `msg`, `plugin`, `module`) must not be used as field
+ * names.
+ */
+import { mkdirSync } from "node:fs";
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+import pino from "pino";
+import { resolveDshHome } from "./dsh-home.js";
+/** Ordered severity levels; `silent` disables the logger entirely. */
+export const PLUGIN_LOG_LEVELS = [
+    "trace",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "fatal",
+    "silent",
+];
+/** Default console mirror threshold. */
+export const DEFAULT_CONSOLE_LEVEL = "warn";
+/** Daily log files kept per plugin by default (0 = keep forever). */
+export const DEFAULT_LOG_RETENTION_DAYS = 14;
+const LEVEL_WEIGHT = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+};
+const DAY_MS = 86_400_000;
+const LOG_FILE_PATTERN = /^(\d{4}-\d{2}-\d{2})\.log$/;
+function weightOf(level) {
+    return level === "silent" ? Number.POSITIVE_INFINITY : LEVEL_WEIGHT[level];
+}
+/** Type guard for level strings (config parsing, env overrides). */
+export function isPluginLogLevel(value) {
+    return typeof value === "string" && PLUGIN_LOG_LEVELS.includes(value);
+}
+function formatConsole(event, fields) {
+    if (fields === undefined)
+        return event;
+    const parts = Object.entries(fields).map(([key, value]) => {
+        const rendered = typeof value === "string" ? value : JSON.stringify(value);
+        return `${key}=${rendered}`;
+    });
+    return parts.length === 0 ? event : `${event} ${parts.join(" ")}`;
+}
+/** Local-calendar date stamp used in file names (sorts lexically). */
+function dayStamp(ms) {
+    const date = new Date(ms);
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${date.getFullYear()}-${month}-${day}`;
+}
+function envLevelOverride(pluginId) {
+    const env = process.env;
+    const specific = env[`DSH_LOG_LEVEL_${pluginId.replaceAll("-", "_").toUpperCase()}`];
+    if (isPluginLogLevel(specific))
+        return specific;
+    return isPluginLogLevel(env.DSH_LOG_LEVEL) ? env.DSH_LOG_LEVEL : undefined;
+}
+function envFileDisabled(explicitDir) {
+    const flag = process.env.DSH_LOG_DISABLED ?? process.env.DSH_PLUGIN_LOG_DISABLED;
+    if (flag === "1" || flag === "true")
+        return true;
+    // Unit tests must never write into a real DSH home unless a dir is explicit.
+    return process.env.NODE_ENV === "test" && !explicitDir;
+}
+async function sweepOldLogFiles(dir, retentionDays, nowMs) {
+    if (retentionDays <= 0)
+        return;
+    const cutoff = nowMs - retentionDays * DAY_MS;
+    const entries = await readdir(dir).catch(() => []);
+    for (const entry of entries) {
+        const match = LOG_FILE_PATTERN.exec(entry);
+        if (match === null || match[1] === undefined)
+            continue;
+        const stampMs = Date.parse(`${match[1]}T00:00:00`);
+        if (!Number.isFinite(stampMs) || stampMs >= cutoff)
+            continue;
+        await unlink(join(dir, entry)).catch(() => undefined);
+    }
+}
+let sharedDevNull;
+function devNull() {
+    sharedDevNull ??= new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    return sharedDevNull;
+}
+function closeQuietly(destination) {
+    try {
+        destination.end?.();
+    }
+    catch {
+        // Fail-open: closing must never surface.
+    }
+}
+/**
+ * SonicBoom's `end()` takes no callback — completion is signaled by the
+ * `close` event. A bounded guard keeps a wedged stream from hanging plugin
+ * disposal forever.
+ */
+function closeDestination(destination) {
+    return new Promise((resolve) => {
+        if (destination.destroyed === true) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(guard);
+            resolve();
+        };
+        const guard = setTimeout(done, 1000);
+        guard.unref();
+        try {
+            destination.once?.("close", done);
+            destination.end?.();
+        }
+        catch {
+            done();
+        }
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const defaultSink = (level, message) => {
+    if (level === "warn")
+        console.warn(message);
+    else if (level === "error" || level === "fatal")
+        console.error(message);
+    else if (level === "trace" || level === "debug")
+        console.log(message);
+    else
+        console.info(message);
+};
+/** Mutable state shared by a root logger and all of its `child()` views. */
+class LoggerCore {
+    pluginId;
+    dir;
+    levelName;
+    consoleLevel;
+    sink;
+    retentionDays;
+    redact;
+    clock;
+    fileEnabled;
+    closed = false;
+    destination;
+    destinationDay = "";
+    root;
+    children = new Map();
+    retention;
+    constructor(options) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(options.pluginId)) {
+            throw new TypeError(`pluginId must match [A-Za-z0-9][A-Za-z0-9._-]*, got ${JSON.stringify(options.pluginId)}`);
+        }
+        this.pluginId = options.pluginId;
+        const home = options.dshHome ?? resolveDshHome();
+        this.dir = options.dir ?? join(home, "logs", options.pluginId);
+        this.levelName = options.level ?? envLevelOverride(options.pluginId) ?? "info";
+        this.consoleLevel = options.console ?? DEFAULT_CONSOLE_LEVEL;
+        this.sink = options.consoleSink ?? defaultSink;
+        this.retentionDays = Math.max(0, Math.floor(options.retentionDays ?? DEFAULT_LOG_RETENTION_DAYS));
+        this.redact = options.redact ?? [];
+        this.clock = options.now ?? Date.now;
+        this.fileEnabled = (options.file ?? true) && !envFileDisabled(options.dir !== undefined);
+    }
+    isClosed() {
+        return this.closed;
+    }
+    key() {
+        return `${this.pluginId}\u0000${this.dir}`;
+    }
+    get level() {
+        return this.levelName;
+    }
+    setLevel(level) {
+        if (!isPluginLogLevel(level)) {
+            throw new TypeError(`unknown plugin log level: ${JSON.stringify(level)}`);
+        }
+        if (level === this.levelName)
+            return;
+        this.levelName = level;
+        // Rebuild the destination on the next write so the new threshold takes
+        // effect without touching the file handle while silent.
+        this.destinationDay = "";
+    }
+    write(moduleField, level, event, fields) {
+        if (this.closed || this.levelName === "silent")
+            return;
+        if (weightOf(level) < weightOf(this.levelName)) {
+            this.mirror(moduleField, level, event, fields);
+            return;
+        }
+        this.open();
+        const target = this.targetFor(moduleField);
+        if (target !== undefined) {
+            try {
+                target[level](fields ?? {}, event);
+            }
+            catch {
+                // Fail-open: serialization problems must never break the plugin.
+            }
+        }
+        this.mirror(moduleField, level, event, fields);
+    }
+    flush() {
+        try {
+            this.destination?.flushSync?.();
+        }
+        catch {
+            // Fail-open.
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        registry.delete(this.key());
+        const destination = this.destination;
+        this.destination = undefined;
+        this.root = undefined;
+        this.children.clear();
+        this.destinationDay = "";
+        await this.retention;
+        if (destination !== undefined)
+            await closeDestination(destination);
+    }
+    /** Open (or roll over to) the destination file for the current day. */
+    open() {
+        const stamp = dayStamp(this.clock());
+        if (this.root !== undefined && stamp === this.destinationDay)
+            return;
+        this.rollover(stamp);
+    }
+    rollover(stamp) {
+        this.destinationDay = stamp;
+        let next;
+        if (this.fileEnabled) {
+            try {
+                mkdirSync(this.dir, { recursive: true });
+                next = pino.destination({
+                    dest: join(this.dir, `${stamp}.log`),
+                    append: true,
+                    mkdir: true,
+                    sync: false,
+                    minLength: 0,
+                });
+            }
+            catch (error) {
+                // Fail-open: an unusable log directory degrades to console-only.
+                this.fileEnabled = false;
+                next = undefined;
+                this.mirror(undefined, "warn", "logging.file_disabled", { reason: errorMessage(error) });
+            }
+        }
+        const previous = this.destination;
+        this.destination = next;
+        this.children.clear();
+        this.root = pino({
+            level: this.levelName,
+            base: { plugin: this.pluginId },
+            ...(this.redact.length > 0 ? { redact: [...this.redact] } : {}),
+        }, next ?? devNull());
+        if (previous !== undefined && previous !== next)
+            closeQuietly(previous);
+        if (this.fileEnabled)
+            this.scheduleRetentionSweep();
+    }
+    targetFor(moduleField) {
+        const root = this.root;
+        if (root === undefined)
+            return undefined;
+        if (moduleField === undefined)
+            return root;
+        const cached = this.children.get(moduleField);
+        if (cached !== undefined)
+            return cached;
+        const created = root.child({ module: moduleField });
+        this.children.set(moduleField, created);
+        return created;
+    }
+    mirror(moduleField, level, event, fields) {
+        if (this.consoleLevel === "silent")
+            return;
+        if (weightOf(level) < weightOf(this.consoleLevel))
+            return;
+        const scope = moduleField === undefined ? "" : `/${moduleField}`;
+        try {
+            this.sink(level, `[${this.pluginId}${scope}] ${formatConsole(event, fields)}`);
+        }
+        catch {
+            // Fail-open.
+        }
+    }
+    scheduleRetentionSweep() {
+        if (this.retentionDays <= 0 || this.retention !== undefined)
+            return;
+        this.retention = sweepOldLogFiles(this.dir, this.retentionDays, this.clock()).then(() => undefined, () => undefined);
+    }
+}
+const registry = new Map();
+class PluginLoggerImpl {
+    core;
+    moduleField;
+    constructor(core, moduleField) {
+        this.core = core;
+        this.moduleField = moduleField;
+    }
+    trace(event, fields) {
+        this.core.write(this.moduleField, "trace", event, fields);
+    }
+    debug(event, fields) {
+        this.core.write(this.moduleField, "debug", event, fields);
+    }
+    info(event, fields) {
+        this.core.write(this.moduleField, "info", event, fields);
+    }
+    warn(event, fields) {
+        this.core.write(this.moduleField, "warn", event, fields);
+    }
+    error(event, fields) {
+        this.core.write(this.moduleField, "error", event, fields);
+    }
+    fatal(event, fields) {
+        this.core.write(this.moduleField, "fatal", event, fields);
+    }
+    child(module) {
+        return new PluginLoggerImpl(this.core, module);
+    }
+    get level() {
+        return this.core.level;
+    }
+    setLevel(level) {
+        this.core.setLevel(level);
+    }
+    flush() {
+        this.core.flush();
+    }
+    close() {
+        return this.core.close();
+    }
+}
+/** Create a standalone logger instance (no caching). */
+export function createPluginLogger(options) {
+    return new PluginLoggerImpl(new LoggerCore(options));
+}
+/**
+ * Create or return the cached logger for `pluginId` + resolved `dir`. A later
+ * call with an explicit `level` updates the cached instance's threshold, so
+ * plugin config reloads take effect. `close()` evicts the cache entry; the
+ * next call creates a fresh instance.
+ */
+export function getPluginLogger(options) {
+    const candidate = new LoggerCore(options);
+    const key = candidate.key();
+    const existing = registry.get(key);
+    if (existing === undefined || existing.core.isClosed()) {
+        const entry = { core: candidate, root: new PluginLoggerImpl(candidate) };
+        registry.set(key, entry);
+        return entry.root;
+    }
+    if (options.level !== undefined)
+        existing.core.setLevel(options.level);
+    return existing.root;
+}
+//# sourceMappingURL=plugin-logger.js.map

package/lib/logging/plugin-logger.js.map

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

package/lib/observability/diagnostics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Structured logging events (SPEC §45).
+ *
+ * Events use stable dotted names (`kv.session.restore.success`); session
+ * identifiers are abbreviated hashes at normal verbosity. The management
+ * API key never passes through here. Records land in
+ * `<$DSH_HOME>/logs/dsh-kv-persist/<YYYY-MM-DD>.log` (NDJSON); `warn` and
+ * above are additionally mirrored to the host context logger.
+ */
+export interface KvPersistLogger {
+    debug(event: string, fields?: Record<string, unknown>): void;
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+    /** Best-effort synchronous flush of buffered file output. */
+    flush?(): void;
+    /** Flush and close the underlying destination (idempotent). */
+    close?(): Promise<void>;
+}
+export type KvPersistLogLevel = "debug" | "info" | "off";
+/** Abbreviated session hash for logs (SPEC §45: avoid full ids). */
+export declare function abbreviateSessionId(sessionId: string): string;
+interface HostLoggerLike {
+    info(message: string, ...values: unknown[]): unknown;
+    warn(message: string, ...values: unknown[]): unknown;
+    error(message: string, ...values: unknown[]): unknown;
+    debug?(message: string, ...values: unknown[]): unknown;
+}
+/**
+ * Build the plugin logger on top of the shared pino-backed file logger
+ * (`<$DSH_HOME>/logs/dsh-kv-persist/<YYYY-MM-DD>.log`) with the host context
+ * logger as the console mirror for `warn`+ records. Sensitive fields are
+ * abbreviated here, before any record leaves the plugin (SPEC §45).
+ */
+export declare function createKvPersistLogger(host: HostLoggerLike, level: KvPersistLogLevel): KvPersistLogger;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/observability/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/observability/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,6DAA6D;IAC7D,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAeD,UAAU,cAAc;IACtB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACrD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACrD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtD,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,iBAAiB,GAAG,eAAe,CAkCrG"}

package/lib/observability/diagnostics.js

@@ -0,0 +1,75 @@
+/**
+ * Structured logging events (SPEC §45).
+ *
+ * Events use stable dotted names (`kv.session.restore.success`); session
+ * identifiers are abbreviated hashes at normal verbosity. The management
+ * API key never passes through here. Records land in
+ * `<$DSH_HOME>/logs/dsh-kv-persist/<YYYY-MM-DD>.log` (NDJSON); `warn` and
+ * above are additionally mirrored to the host context logger.
+ */
+import { getPluginLogger } from "../logging/index.js";
+import { sha256Hex } from "../snapshots/fingerprint.js";
+/** Abbreviated session hash for logs (SPEC §45: avoid full ids). */
+export function abbreviateSessionId(sessionId) {
+    return sha256Hex(sessionId).slice(0, 6);
+}
+/** Fields that must be abbreviated before formatting. */
+const SENSITIVE_FIELDS = new Set(["sessionId"]);
+function prepareFields(fields) {
+    if (fields === undefined)
+        return {};
+    const prepared = {};
+    for (const [key, value] of Object.entries(fields)) {
+        prepared[key] =
+            SENSITIVE_FIELDS.has(key) && typeof value === "string" ? abbreviateSessionId(value) : value;
+    }
+    return prepared;
+}
+/**
+ * Build the plugin logger on top of the shared pino-backed file logger
+ * (`<$DSH_HOME>/logs/dsh-kv-persist/<YYYY-MM-DD>.log`) with the host context
+ * logger as the console mirror for `warn`+ records. Sensitive fields are
+ * abbreviated here, before any record leaves the plugin (SPEC §45).
+ */
+export function createKvPersistLogger(host, level) {
+    const shared = getPluginLogger({
+        pluginId: "dsh-kv-persist",
+        level: level === "off" ? "silent" : level,
+        console: level === "off" ? "silent" : "warn",
+        consoleSink: (logLevel, message) => {
+            if (logLevel === "trace" || logLevel === "debug") {
+                if (typeof host.debug === "function")
+                    host.debug(message);
+                else
+                    host.info(message);
+            }
+            else if (logLevel === "info")
+                host.info(message);
+            else if (logLevel === "warn")
+                host.warn(message);
+            else
+                host.error(message);
+        },
+    });
+    return {
+        debug(event, fields) {
+            shared.debug(event, prepareFields(fields));
+        },
+        info(event, fields) {
+            shared.info(event, prepareFields(fields));
+        },
+        warn(event, fields) {
+            shared.warn(event, prepareFields(fields));
+        },
+        error(event, fields) {
+            shared.error(event, prepareFields(fields));
+        },
+        flush() {
+            shared.flush();
+        },
+        close() {
+            return shared.close();
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/observability/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/observability/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAexD,oEAAoE;AACpE,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,yDAAyD;AACzD,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAEhD,SAAS,aAAa,CAAC,MAA2C;IAChE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,QAAQ,CAAC,GAAG,CAAC;YACX,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChG,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAoB,EAAE,KAAwB;IAClF,MAAM,MAAM,GAAG,eAAe,CAAC;QAC7B,QAAQ,EAAE,gBAAgB;QAC1B,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK;QACzC,OAAO,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;QAC5C,WAAW,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE;YACjC,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACjD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,UAAU;oBAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;oBACrD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;iBAAM,IAAI,QAAQ,KAAK,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;iBAC9C,IAAI,QAAQ,KAAK,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;gBAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC,CAAC;IACH,OAAO;QACL,KAAK,CAAC,KAAK,EAAE,MAAM;YACjB,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,MAAM;YAChB,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,MAAM;YAChB,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,MAAM;YACjB,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK;YACH,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,KAAK;YACH,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/observability/metrics.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Persistence metrics counters (SPEC §46, MVP subset).
+ *
+ * Counters are in-memory only in v0.1; they surface through
+ * `ctx.kvPersist.status()` and later optional Prometheus integration.
+ */
+export interface KvPersistCounters {
+    /** Restore attempts that ended successfully (§46 dsh_kv_restore_total). */
+    restores: number;
+    /** Successful restores of an existing snapshot (§46 restore_hit_total). */
+    restoreHits: number;
+    /** Failed restores (§46 restore_failure_total). */
+    restoreFailures: number;
+    /** Requests served without any snapshot (§46 cold_prefill_total). */
+    coldPrefills: number;
+    /** Successful saves (§46 save_total). */
+    saves: number;
+    /** Failed saves (§46 save_failure_total). */
+    saveFailures: number;
+    /** Successful slot erases. */
+    erases: number;
+    /** Slot owner switches (§46 slot_switch_total). */
+    slotSwitches: number;
+    /** Auxiliary requests that went through coordination. */
+    auxiliaryRequests: number;
+    /** Requests skipped because the circuit was open. */
+    circuitSkips: number;
+    /** Cumulative restore duration in milliseconds. */
+    restoreDurationMs: number;
+    /** Cumulative save duration in milliseconds. */
+    saveDurationMs: number;
+}
+export declare class KvPersistMetrics {
+    #private;
+    get counters(): KvPersistCounters;
+    snapshot(): KvPersistCounters;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/lib/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;CACxB;AAID,qBAAa,gBAAgB;;IAgB3B,IAAI,QAAQ,IAAI,iBAAiB,CAEhC;IAED,QAAQ,IAAI,iBAAiB;CAG9B"}

package/lib/observability/metrics.js

@@ -0,0 +1,29 @@
+/**
+ * Persistence metrics counters (SPEC §46, MVP subset).
+ *
+ * Counters are in-memory only in v0.1; they surface through
+ * `ctx.kvPersist.status()` and later optional Prometheus integration.
+ */
+export class KvPersistMetrics {
+    #counters = {
+        restores: 0,
+        restoreHits: 0,
+        restoreFailures: 0,
+        coldPrefills: 0,
+        saves: 0,
+        saveFailures: 0,
+        erases: 0,
+        slotSwitches: 0,
+        auxiliaryRequests: 0,
+        circuitSkips: 0,
+        restoreDurationMs: 0,
+        saveDurationMs: 0,
+    };
+    get counters() {
+        return this.#counters;
+    }
+    snapshot() {
+        return { ...this.#counters };
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/lib/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+BH,MAAM,OAAO,gBAAgB;IAClB,SAAS,GAAoB;QACpC,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE,CAAC;QACd,eAAe,EAAE,CAAC;QAClB,YAAY,EAAE,CAAC;QACf,KAAK,EAAE,CAAC;QACR,YAAY,EAAE,CAAC;QACf,MAAM,EAAE,CAAC;QACT,YAAY,EAAE,CAAC;QACf,iBAAiB,EAAE,CAAC;QACpB,YAAY,EAAE,CAAC;QACf,iBAAiB,EAAE,CAAC;QACpB,cAAc,EAAE,CAAC;KAClB,CAAC;IAEF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,QAAQ;QACN,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAC/B,CAAC;CACF"}