dsh-tdai-memory 0.2.13 → 0.3.0

package/vendor/tdai/utils/managed-timer.js

@@ -1,127 +1,127 @@
-/**
- * ManagedTimer: a named, lifecycle-managed wrapper around setTimeout.
- *
- * Eliminates repetitive clear→set→fire→clean patterns by providing:
- * - `schedule(delayMs, cb)` — cancel any pending timer, set a new one
- * - `scheduleAt(epochMs, cb)` — schedule by absolute time point
- * - `tryAdvanceTo(epochMs, cb)` — only reschedule if new time is *earlier*
- * - `cancel()` — cancel without triggering
- * - `flush()` — trigger immediately (for graceful shutdown)
- * - `pending` — whether a timer is waiting
- *
- * The optional `isDestroyed` guard prevents firing after the owner is torn down.
- */
-export class ManagedTimer {
-    name;
-    isDestroyed;
-    handle = null;
-    callback = null;
-    /** Absolute epoch-ms when the current timer is scheduled to fire. */
-    scheduledAt = 0;
-    constructor(
-    /** Human-readable name for logging. */
-    name, 
-    /** If provided, checked before firing — skips callback when true. */
-    isDestroyed) {
-        this.name = name;
-        this.isDestroyed = isDestroyed;
-    }
-    // ── Core operations ──────────────────────────────────
-    /**
-     * Cancel any pending timer and schedule a new one after `delayMs`.
-     * The callback fires once; the timer auto-clears after firing.
-     */
-    schedule(delayMs, callback) {
-        this.cancelInternal();
-        this.callback = callback;
-        this.scheduledAt = Date.now() + delayMs;
-        this.handle = setTimeout(() => this.fire(), delayMs);
-        // Don't let pipeline timers keep the process alive in CLI mode.
-        // In gateway mode the server listener holds the event loop anyway.
-        this.handle.unref();
-    }
-    /**
-     * Cancel any pending timer and schedule to fire at an absolute epoch-ms.
-     * If `epochMs` is in the past, fires on next tick (delay = 0).
-     */
-    scheduleAt(epochMs, callback) {
-        this.cancelInternal();
-        this.callback = callback;
-        this.scheduledAt = epochMs;
-        const delay = Math.max(0, epochMs - Date.now());
-        this.handle = setTimeout(() => this.fire(), delay);
-        this.handle.unref();
-    }
-    /**
-     * Only reschedule if `epochMs` is *earlier* than the current scheduled time.
-     * This implements the "downward-only" timer pattern (L2 scheduling).
-     * If no timer is pending, behaves like `scheduleAt()`.
-     *
-     * @returns true if the timer was actually advanced (or newly set).
-     */
-    tryAdvanceTo(epochMs, callback) {
-        if (this.handle === null) {
-            // No pending timer → set it
-            this.scheduleAt(epochMs, callback);
-            return true;
-        }
-        if (epochMs < this.scheduledAt) {
-            // New time is earlier → reschedule
-            this.scheduleAt(epochMs, callback);
-            return true;
-        }
-        // Current timer is already earlier or equal → keep it
-        return false;
-    }
-    /**
-     * Cancel the pending timer without triggering the callback.
-     */
-    cancel() {
-        this.cancelInternal();
-    }
-    /**
-     * Immediately trigger the callback (if pending) and clear the timer.
-     * Used for graceful shutdown to flush pending work.
-     *
-     * Note: Unlike `fire()`, this method intentionally does NOT check `isDestroyed`.
-     * This is by design — during shutdown, `destroy()` sets `destroyed = true` first,
-     * then calls `flush()` to drain pending work. The `isDestroyed` guard only applies
-     * to natural timer expiration via `fire()`, not to explicit shutdown flushes.
-     */
-    flush() {
-        if (this.handle === null)
-            return;
-        const cb = this.callback;
-        this.cancelInternal();
-        if (cb)
-            cb();
-    }
-    // ── Accessors ────────────────────────────────────────
-    /** Whether a timer is currently pending. */
-    get pending() {
-        return this.handle !== null;
-    }
-    /** The epoch-ms when the current timer is scheduled to fire (0 if none). */
-    get scheduledTime() {
-        return this.handle !== null ? this.scheduledAt : 0;
-    }
-    // ── Internals ────────────────────────────────────────
-    fire() {
-        const cb = this.callback;
-        this.handle = null;
-        this.callback = null;
-        this.scheduledAt = 0;
-        if (this.isDestroyed?.())
-            return;
-        if (cb)
-            cb();
-    }
-    cancelInternal() {
-        if (this.handle !== null) {
-            clearTimeout(this.handle);
-            this.handle = null;
-        }
-        this.callback = null;
-        this.scheduledAt = 0;
-    }
-}
+/**
+ * ManagedTimer: a named, lifecycle-managed wrapper around setTimeout.
+ *
+ * Eliminates repetitive clear→set→fire→clean patterns by providing:
+ * - `schedule(delayMs, cb)` — cancel any pending timer, set a new one
+ * - `scheduleAt(epochMs, cb)` — schedule by absolute time point
+ * - `tryAdvanceTo(epochMs, cb)` — only reschedule if new time is *earlier*
+ * - `cancel()` — cancel without triggering
+ * - `flush()` — trigger immediately (for graceful shutdown)
+ * - `pending` — whether a timer is waiting
+ *
+ * The optional `isDestroyed` guard prevents firing after the owner is torn down.
+ */
+export class ManagedTimer {
+    name;
+    isDestroyed;
+    handle = null;
+    callback = null;
+    /** Absolute epoch-ms when the current timer is scheduled to fire. */
+    scheduledAt = 0;
+    constructor(
+    /** Human-readable name for logging. */
+    name, 
+    /** If provided, checked before firing — skips callback when true. */
+    isDestroyed) {
+        this.name = name;
+        this.isDestroyed = isDestroyed;
+    }
+    // ── Core operations ──────────────────────────────────
+    /**
+     * Cancel any pending timer and schedule a new one after `delayMs`.
+     * The callback fires once; the timer auto-clears after firing.
+     */
+    schedule(delayMs, callback) {
+        this.cancelInternal();
+        this.callback = callback;
+        this.scheduledAt = Date.now() + delayMs;
+        this.handle = setTimeout(() => this.fire(), delayMs);
+        // Don't let pipeline timers keep the process alive in CLI mode.
+        // In gateway mode the server listener holds the event loop anyway.
+        this.handle.unref();
+    }
+    /**
+     * Cancel any pending timer and schedule to fire at an absolute epoch-ms.
+     * If `epochMs` is in the past, fires on next tick (delay = 0).
+     */
+    scheduleAt(epochMs, callback) {
+        this.cancelInternal();
+        this.callback = callback;
+        this.scheduledAt = epochMs;
+        const delay = Math.max(0, epochMs - Date.now());
+        this.handle = setTimeout(() => this.fire(), delay);
+        this.handle.unref();
+    }
+    /**
+     * Only reschedule if `epochMs` is *earlier* than the current scheduled time.
+     * This implements the "downward-only" timer pattern (L2 scheduling).
+     * If no timer is pending, behaves like `scheduleAt()`.
+     *
+     * @returns true if the timer was actually advanced (or newly set).
+     */
+    tryAdvanceTo(epochMs, callback) {
+        if (this.handle === null) {
+            // No pending timer → set it
+            this.scheduleAt(epochMs, callback);
+            return true;
+        }
+        if (epochMs < this.scheduledAt) {
+            // New time is earlier → reschedule
+            this.scheduleAt(epochMs, callback);
+            return true;
+        }
+        // Current timer is already earlier or equal → keep it
+        return false;
+    }
+    /**
+     * Cancel the pending timer without triggering the callback.
+     */
+    cancel() {
+        this.cancelInternal();
+    }
+    /**
+     * Immediately trigger the callback (if pending) and clear the timer.
+     * Used for graceful shutdown to flush pending work.
+     *
+     * Note: Unlike `fire()`, this method intentionally does NOT check `isDestroyed`.
+     * This is by design — during shutdown, `destroy()` sets `destroyed = true` first,
+     * then calls `flush()` to drain pending work. The `isDestroyed` guard only applies
+     * to natural timer expiration via `fire()`, not to explicit shutdown flushes.
+     */
+    flush() {
+        if (this.handle === null)
+            return;
+        const cb = this.callback;
+        this.cancelInternal();
+        if (cb)
+            cb();
+    }
+    // ── Accessors ────────────────────────────────────────
+    /** Whether a timer is currently pending. */
+    get pending() {
+        return this.handle !== null;
+    }
+    /** The epoch-ms when the current timer is scheduled to fire (0 if none). */
+    get scheduledTime() {
+        return this.handle !== null ? this.scheduledAt : 0;
+    }
+    // ── Internals ────────────────────────────────────────
+    fire() {
+        const cb = this.callback;
+        this.handle = null;
+        this.callback = null;
+        this.scheduledAt = 0;
+        if (this.isDestroyed?.())
+            return;
+        if (cb)
+            cb();
+    }
+    cancelInternal() {
+        if (this.handle !== null) {
+            clearTimeout(this.handle);
+            this.handle = null;
+        }
+        this.callback = null;
+        this.scheduledAt = 0;
+    }
+}

package/vendor/tdai/utils/manifest.js

@@ -1,91 +1,91 @@
-/**
- * Manifest — self-describing metadata for a memory-tdai data directory.
- *
- * Lives at `<dataDir>/.metadata/manifest.json`.
- *
- * - **store**: written once on first successful store init; never overwritten.
- *   On subsequent starts the current config is compared against the persisted
- *   store binding — mismatches are logged at debug level (informational only).
- * - **seed**: written once when a seed run completes; null for live-runtime dirs.
- *
- * This file is informational / read-only from the user's perspective.
- * The plugin reads it on startup for consistency checks.
- */
-import fs from "node:fs";
-import path from "node:path";
-// ============================
-// Paths
-// ============================
-const METADATA_DIR = ".metadata";
-const MANIFEST_FILE = "manifest.json";
-export function manifestPath(dataDir) {
-    return path.join(dataDir, METADATA_DIR, MANIFEST_FILE);
-}
-// ============================
-// Read / Write
-// ============================
-/**
- * Read an existing manifest from disk. Returns `null` if not found or unparseable.
- */
-export function readManifest(dataDir) {
-    const p = manifestPath(dataDir);
-    try {
-        if (!fs.existsSync(p))
-            return null;
-        const raw = fs.readFileSync(p, "utf-8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Write a manifest to disk (creates `.metadata/` if needed).
- */
-export function writeManifest(dataDir, manifest) {
-    const dir = path.join(dataDir, METADATA_DIR);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(manifestPath(dataDir), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
-}
-/**
- * Build a ManifestStoreInfo from the current store config snapshot.
- */
-export function buildStoreInfo(snapshot) {
-    const info = { type: snapshot.type };
-    if (snapshot.type === "sqlite") {
-        info.sqlite = { path: snapshot.sqlitePath ?? "vectors.db" };
-    }
-    else {
-        info.tcvdb = {
-            url: snapshot.tcvdbUrl,
-            database: snapshot.tcvdbDatabase,
-            alias: snapshot.tcvdbAlias || undefined,
-        };
-    }
-    return info;
-}
-/**
- * Compare the persisted store binding against the current config.
- * Returns a list of human-readable mismatch descriptions (empty = all good).
- */
-export function diffStoreBinding(persisted, current) {
-    const diffs = [];
-    if (persisted.type !== current.type) {
-        diffs.push(`store type changed: ${persisted.type} → ${current.type}`);
-        return diffs; // no point comparing fields across different types
-    }
-    if (persisted.type === "sqlite" && current.type === "sqlite") {
-        if (persisted.sqlite?.path !== current.sqlite?.path) {
-            diffs.push(`sqlite path changed: ${persisted.sqlite?.path} → ${current.sqlite?.path}`);
-        }
-    }
-    if (persisted.type === "tcvdb" && current.type === "tcvdb") {
-        if (persisted.tcvdb?.url !== current.tcvdb?.url) {
-            diffs.push(`tcvdb url changed: ${persisted.tcvdb?.url} → ${current.tcvdb?.url}`);
-        }
-        if (persisted.tcvdb?.database !== current.tcvdb?.database) {
-            diffs.push(`tcvdb database changed: ${persisted.tcvdb?.database} → ${current.tcvdb?.database}`);
-        }
-    }
-    return diffs;
-}
+/**
+ * Manifest — self-describing metadata for a memory-tdai data directory.
+ *
+ * Lives at `<dataDir>/.metadata/manifest.json`.
+ *
+ * - **store**: written once on first successful store init; never overwritten.
+ *   On subsequent starts the current config is compared against the persisted
+ *   store binding — mismatches are logged at debug level (informational only).
+ * - **seed**: written once when a seed run completes; null for live-runtime dirs.
+ *
+ * This file is informational / read-only from the user's perspective.
+ * The plugin reads it on startup for consistency checks.
+ */
+import fs from "node:fs";
+import path from "node:path";
+// ============================
+// Paths
+// ============================
+const METADATA_DIR = ".metadata";
+const MANIFEST_FILE = "manifest.json";
+export function manifestPath(dataDir) {
+    return path.join(dataDir, METADATA_DIR, MANIFEST_FILE);
+}
+// ============================
+// Read / Write
+// ============================
+/**
+ * Read an existing manifest from disk. Returns `null` if not found or unparseable.
+ */
+export function readManifest(dataDir) {
+    const p = manifestPath(dataDir);
+    try {
+        if (!fs.existsSync(p))
+            return null;
+        const raw = fs.readFileSync(p, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a manifest to disk (creates `.metadata/` if needed).
+ */
+export function writeManifest(dataDir, manifest) {
+    const dir = path.join(dataDir, METADATA_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(manifestPath(dataDir), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+/**
+ * Build a ManifestStoreInfo from the current store config snapshot.
+ */
+export function buildStoreInfo(snapshot) {
+    const info = { type: snapshot.type };
+    if (snapshot.type === "sqlite") {
+        info.sqlite = { path: snapshot.sqlitePath ?? "vectors.db" };
+    }
+    else {
+        info.tcvdb = {
+            url: snapshot.tcvdbUrl,
+            database: snapshot.tcvdbDatabase,
+            alias: snapshot.tcvdbAlias || undefined,
+        };
+    }
+    return info;
+}
+/**
+ * Compare the persisted store binding against the current config.
+ * Returns a list of human-readable mismatch descriptions (empty = all good).
+ */
+export function diffStoreBinding(persisted, current) {
+    const diffs = [];
+    if (persisted.type !== current.type) {
+        diffs.push(`store type changed: ${persisted.type} → ${current.type}`);
+        return diffs; // no point comparing fields across different types
+    }
+    if (persisted.type === "sqlite" && current.type === "sqlite") {
+        if (persisted.sqlite?.path !== current.sqlite?.path) {
+            diffs.push(`sqlite path changed: ${persisted.sqlite?.path} → ${current.sqlite?.path}`);
+        }
+    }
+    if (persisted.type === "tcvdb" && current.type === "tcvdb") {
+        if (persisted.tcvdb?.url !== current.tcvdb?.url) {
+            diffs.push(`tcvdb url changed: ${persisted.tcvdb?.url} → ${current.tcvdb?.url}`);
+        }
+        if (persisted.tcvdb?.database !== current.tcvdb?.database) {
+            diffs.push(`tcvdb database changed: ${persisted.tcvdb?.database} → ${current.tcvdb?.database}`);
+        }
+    }
+    return diffs;
+}