@remnic/core 1.1.2 → 1.1.4

package/dist/framework-CyHYDcri.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @remnic/core — Live Connectors Framework (issue #683 PR 1/N)
+ *
+ * Defines the contract that every "live" connector (Drive, Notion, Gmail,
+ * GitHub, ...) must satisfy. A live connector is **continuous**: it runs on a
+ * schedule, persists a cursor to disk, and ingests *new* documents since the
+ * last sync. This is distinct from one-shot importers in
+ * `packages/remnic-core/src/importers/` which transform an entire export file
+ * in a single pass.
+ *
+ * This module is intentionally pure types + interfaces. No I/O. No schedule
+ * wiring. Concrete connectors (PRs 2–5), the maintenance scheduler hookup
+ * (separate PR), and the CLI surface (PR 6) are deferred.
+ *
+ * Naming caveat: `packages/remnic-core/src/connectors/` is already scoped to
+ * the Codex marketplace integration. The live-connector framework lives under
+ * the `live/` subdirectory to avoid collision. Do not import Codex symbols
+ * from here, and do not import live-connector symbols from the Codex code.
+ */
+/**
+ * Free-form connector configuration. Validated by each connector's
+ * `validateConfig` implementation. Stored alongside the cursor in the state
+ * store. MUST be JSON-serializable: no functions, no class instances, no
+ * circular references.
+ *
+ * Connectors MUST NOT persist secrets here — credentials belong in OS keychain
+ * / OAuth token storage (PR 2 design).
+ */
+type ConnectorConfig = Record<string, unknown>;
+/**
+ * Opaque cursor describing "where the last sync left off". Each connector
+ * defines what `kind` and `value` mean (e.g. Drive: `{kind: "pageToken",
+ * value: "..."}`, Gmail: `{kind: "historyId", value: "..."}`). The orchestrator
+ * treats it as opaque and only round-trips it through the state store.
+ *
+ * `updatedAt` is an ISO 8601 timestamp set by the framework when the cursor is
+ * written. It is informational — connectors MUST NOT use it to decide
+ * monotonicity. They own the `value` semantics.
+ */
+interface ConnectorCursor {
+    /** Connector-defined cursor kind (e.g. `"pageToken"`, `"historyId"`, `"sinceTs"`). */
+    readonly kind: string;
+    /** Connector-defined opaque cursor value. */
+    readonly value: string;
+    /** ISO 8601 timestamp of when this cursor was last written. */
+    readonly updatedAt: string;
+}
+/**
+ * Provenance for a connector-ingested document. Required so downstream recall
+ * can attribute facts back to their origin and avoid re-ingesting on the next
+ * incremental pass.
+ */
+interface ConnectorDocumentSource {
+    /** Stable connector id (matches `LiveConnector.id`). */
+    readonly connector: string;
+    /** Source-system identifier (Drive file id, Notion page id, Gmail msg id, ...). */
+    readonly externalId: string;
+    /** Optional source-system revision/version (etag, page version, history id). */
+    readonly externalRevision?: string;
+    /** Optional canonical URL pointing back at the source document. */
+    readonly externalUrl?: string;
+    /** ISO 8601 timestamp of when the connector fetched this document. */
+    readonly fetchedAt: string;
+}
+/**
+ * A single document yielded by an incremental sync. Connectors are responsible
+ * for chunking large source documents themselves if needed; the orchestrator
+ * ingests `content` as a unit.
+ */
+interface ConnectorDocument {
+    /** Connector-local stable id for this document. SHOULD match `source.externalId`. */
+    readonly id: string;
+    /** Optional human-readable title. */
+    readonly title?: string;
+    /** Body content. Plaintext or Markdown — connectors document their format. */
+    readonly content: string;
+    /** Provenance. Required. */
+    readonly source: ConnectorDocumentSource;
+}
+/**
+ * Arguments passed to `syncIncremental`. The framework owns cursor/config
+ * lifecycle; connectors only read these and return the next cursor.
+ */
+interface SyncIncrementalArgs {
+    /** Last persisted cursor, or `null` on the first ever sync. */
+    readonly cursor: ConnectorCursor | null;
+    /** Validated connector config (already passed through `validateConfig`). */
+    readonly config: ConnectorConfig;
+    /** Optional abort signal. Connectors SHOULD honor it for cooperative cancellation. */
+    readonly abortSignal?: AbortSignal;
+}
+/**
+ * Result of a single incremental sync pass.
+ *
+ * `newDocs` MAY be empty (no new documents since the last cursor). `nextCursor`
+ * MUST always be returned — even on no-op syncs the framework persists it so
+ * `updatedAt` reflects the most recent attempt.
+ */
+interface SyncIncrementalResult {
+    readonly newDocs: ConnectorDocument[];
+    readonly nextCursor: ConnectorCursor;
+}
+/**
+ * The contract every live connector implements.
+ *
+ * Connectors MUST be:
+ *   - **Idempotent**: re-running with the same cursor MUST NOT duplicate
+ *     documents. The `source.externalId` + `source.externalRevision` pair is
+ *     used downstream for dedup.
+ *   - **Read-only on the source**: live connectors never mutate the upstream
+ *     system (no marking emails read, no editing Notion pages).
+ *   - **Cancellable**: long-running syncs SHOULD periodically check
+ *     `abortSignal.aborted` and bail cleanly.
+ *   - **Privacy-aware**: connectors MUST NOT log document content. Logging
+ *     metadata (counts, ids, timings) is fine.
+ */
+interface LiveConnector {
+    /**
+     * Stable connector id. MUST match `CONNECTOR_ID_PATTERN` — lowercase
+     * alphanumeric plus dash, 1–64 chars, must start AND end with alphanumeric
+     * (no leading or trailing dash). The registry enforces this.
+     */
+    readonly id: string;
+    /** Short human-readable name shown in CLI / status output. */
+    readonly displayName: string;
+    /** Optional longer description. */
+    readonly description?: string;
+    /**
+     * Validate raw user-supplied config. MUST throw on malformed input — never
+     * silently default. The returned object is what gets persisted and passed
+     * back to `syncIncremental`. Connectors SHOULD strip unknown fields.
+     */
+    validateConfig(raw: unknown): ConnectorConfig;
+    /**
+     * Run one incremental sync pass. See `SyncIncrementalArgs` /
+     * `SyncIncrementalResult` for the contract.
+     */
+    syncIncremental(args: SyncIncrementalArgs): Promise<SyncIncrementalResult>;
+}
+/**
+ * Regex enforcing the connector-id naming rule. Exported so connectors and
+ * tests can validate ids consistently with the registry.
+ *
+ * Rule: lowercase alphanumeric + dash, 1..64 chars, must start AND end with
+ * alphanumeric (no leading or trailing dash). Single-char ids are allowed.
+ */
+declare const CONNECTOR_ID_PATTERN: RegExp;
+/**
+ * Returns `true` if `id` is a syntactically valid connector id.
+ */
+declare function isValidConnectorId(id: unknown): id is string;
+
+export { type ConnectorConfig as C, type LiveConnector as L, type SyncIncrementalResult as S, type ConnectorDocument as a, type ConnectorCursor as b, CONNECTOR_ID_PATTERN as c, type ConnectorDocumentSource as d, type SyncIncrementalArgs as e, isValidConnectorId as i };

package/dist/fs-utils-IRVUFB6G.js

@@ -0,0 +1,30 @@
+import {
+  assertIsDirectoryNotSymlink,
+  assertRealpathInsideRoot,
+  ensureDirExists,
+  fileExists,
+  fromPosixRelPath,
+  isPathInsideRoot,
+  listFilesRecursive,
+  readJsonFile,
+  sha256File,
+  sha256String,
+  toPosixRelPath,
+  writeJsonFile
+} from "./chunk-457A4P3L.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  assertIsDirectoryNotSymlink,
+  assertRealpathInsideRoot,
+  ensureDirExists,
+  fileExists,
+  fromPosixRelPath,
+  isPathInsideRoot,
+  listFilesRecursive,
+  readJsonFile,
+  sha256File,
+  sha256String,
+  toPosixRelPath,
+  writeJsonFile
+};
+//# sourceMappingURL=fs-utils-IRVUFB6G.js.map

package/dist/fs-utils-IRVUFB6G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/graph-dashboard-diff.js

@@ -2,6 +2,7 @@ import {
   diffGraphSnapshots
 } from "./chunk-3SLRNYNG.js";
 import "./chunk-Y4Z4I6WK.js";
+import "./chunk-PZ5AY32C.js";
 export {
   diffGraphSnapshots
 };

package/dist/graph-dashboard-key.js

@@ -1,6 +1,7 @@
 import {
   graphEdgeKey
 } from "./chunk-Y4Z4I6WK.js";
+import "./chunk-PZ5AY32C.js";
 export {
   graphEdgeKey
 };

package/dist/graph-dashboard-parser.js

@@ -2,6 +2,7 @@ import {
   graphSnapshotFromMemoryDir
 } from "./chunk-LIRZNNUP.js";
 import "./chunk-Y4Z4I6WK.js";
+import "./chunk-PZ5AY32C.js";
 export {
   graphSnapshotFromMemoryDir
 };

package/dist/graph-edge-decay-PWB63GRE.js

@@ -0,0 +1,207 @@
+import {
+  isSafeRouteNamespace
+} from "./chunk-2LGMW3DJ.js";
+import {
+  graphFilePath,
+  graphsDir,
+  readEdgesStrict,
+  withGraphWriteLock
+} from "./chunk-RK2Y4XOM.js";
+import {
+  DEFAULT_DECAY_FLOOR,
+  DEFAULT_DECAY_PER_WINDOW,
+  DEFAULT_DECAY_WINDOW_MS,
+  decayEdgeConfidence,
+  readEdgeConfidence
+} from "./chunk-2LSZVONP.js";
+import "./chunk-WIICJPET.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/maintenance/graph-edge-decay.ts
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  writeFile
+} from "fs/promises";
+import path from "path";
+var DEFAULT_VISIBILITY_THRESHOLD = 0.2;
+var GRAPH_TYPES = ["entity", "time", "causal"];
+function graphEdgeDecayStatusPath(memoryDir) {
+  return path.join(memoryDir, "state", "graph-edge-decay-status.json");
+}
+async function writeJsonlAtomic(filePath, edges) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const body = edges.length === 0 ? "" : edges.map((e) => JSON.stringify(e)).join("\n") + "\n";
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile(tempPath, body, "utf-8");
+  await rename(tempPath, filePath);
+}
+async function runGraphEdgeDecayMaintenance(memoryDir, options = {}) {
+  const startedAt = Date.now();
+  const ranAt = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const windowMs = options.windowMs ?? DEFAULT_DECAY_WINDOW_MS;
+  const perWindow = options.perWindow ?? DEFAULT_DECAY_PER_WINDOW;
+  const floor = options.floor ?? DEFAULT_DECAY_FLOOR;
+  const visibilityThreshold = typeof options.visibilityThreshold === "number" && Number.isFinite(options.visibilityThreshold) ? Math.max(0, Math.min(1, options.visibilityThreshold)) : DEFAULT_VISIBILITY_THRESHOLD;
+  const dryRun = options.dryRun === true;
+  await mkdir(graphsDir(memoryDir), { recursive: true });
+  const perType = [];
+  const dropByLabel = /* @__PURE__ */ new Map();
+  let edgesTotal = 0;
+  let edgesDecayed = 0;
+  let edgesBelowVisibilityThreshold = 0;
+  for (const type of GRAPH_TYPES) {
+    const filePath = graphFilePath(memoryDir, type);
+    const {
+      typeDecayed,
+      typeBelow,
+      typeTotal
+    } = await withGraphWriteLock(filePath, async () => {
+      const edges = await readEdgesStrict(memoryDir, type);
+      const updated = new Array(edges.length);
+      let localDecayed = 0;
+      let localBelow = 0;
+      let localChangedAny = false;
+      for (let i = 0; i < edges.length; i += 1) {
+        const edge = edges[i];
+        const before = readEdgeConfidence(edge);
+        const decayed = decayEdgeConfidence(edge, ranAt, { windowMs, perWindow, floor });
+        const after = readEdgeConfidence(decayed);
+        if (after < before) {
+          localDecayed += 1;
+          const drop = before - after;
+          const label = typeof edge.label === "string" ? edge.label : "";
+          if (label.length > 0) {
+            const prev = dropByLabel.get(label);
+            if (prev) {
+              prev.totalDrop += drop;
+              prev.edgeCount += 1;
+            } else {
+              dropByLabel.set(label, { totalDrop: drop, edgeCount: 1 });
+            }
+          }
+        }
+        if (after < visibilityThreshold) {
+          localBelow += 1;
+        }
+        updated[i] = decayed;
+        if (decayed.confidence !== edge.confidence || decayed.lastReinforcedAt !== edge.lastReinforcedAt) {
+          localChangedAny = true;
+        }
+      }
+      if (!dryRun && localChangedAny && edges.length > 0) {
+        await writeJsonlAtomic(filePath, updated);
+      }
+      return {
+        typeDecayed: localDecayed,
+        typeBelow: localBelow,
+        typeTotal: edges.length
+      };
+    });
+    edgesDecayed += typeDecayed;
+    edgesBelowVisibilityThreshold += typeBelow;
+    edgesTotal += typeTotal;
+    perType.push({
+      type,
+      edgesTotal: typeTotal,
+      edgesDecayed: typeDecayed,
+      edgesBelowVisibilityThreshold: typeBelow
+    });
+  }
+  const topDecayedEntities = [...dropByLabel.entries()].map(([label, agg]) => ({ label, totalDrop: agg.totalDrop, edgeCount: agg.edgeCount })).sort((a, b) => {
+    if (b.totalDrop !== a.totalDrop) return b.totalDrop - a.totalDrop;
+    return a.label.localeCompare(b.label);
+  }).slice(0, 5);
+  const telemetry = {
+    ranAt,
+    durationMs: Date.now() - startedAt,
+    edgesTotal,
+    edgesDecayed,
+    edgesBelowVisibilityThreshold,
+    topDecayedEntities,
+    perType,
+    windowMs,
+    perWindow,
+    floor,
+    visibilityThreshold
+  };
+  if (!dryRun) {
+    await persistTelemetry(memoryDir, telemetry);
+  }
+  return telemetry;
+}
+async function persistTelemetry(memoryDir, telemetry) {
+  const statusPath = graphEdgeDecayStatusPath(memoryDir);
+  await mkdir(path.dirname(statusPath), { recursive: true });
+  const tempPath = `${statusPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(telemetry, null, 2) + "\n", "utf-8");
+    await rename(tempPath, statusPath);
+  } catch {
+  }
+}
+async function readGraphEdgeDecayStatus(memoryDir) {
+  try {
+    const raw = await readFile(graphEdgeDecayStatusPath(memoryDir), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function discoverGraphNamespaceRoots(memoryDir, options) {
+  const seen = /* @__PURE__ */ new Map();
+  seen.set(options.defaultNamespace, memoryDir);
+  if (!options.namespacesEnabled) {
+    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+  }
+  const namespacesDir = path.join(memoryDir, "namespaces");
+  let entries;
+  try {
+    entries = await readdir(namespacesDir, { withFileTypes: true });
+  } catch {
+    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!isSafeRouteNamespace(entry.name)) continue;
+    const root = path.join(namespacesDir, entry.name);
+    seen.set(entry.name, root);
+  }
+  return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));
+}
+async function runGraphEdgeDecayMaintenanceAcrossNamespaces(memoryDir, options) {
+  const { namespacesEnabled, defaultNamespace, ...decayOptions } = options;
+  const roots = await discoverGraphNamespaceRoots(memoryDir, {
+    namespacesEnabled,
+    defaultNamespace
+  });
+  const results = [];
+  for (const { namespace, storageRoot } of roots) {
+    try {
+      const telemetry = await runGraphEdgeDecayMaintenance(storageRoot, decayOptions);
+      results.push({ namespace, storageRoot, telemetry });
+    } catch (err) {
+      results.push({
+        namespace,
+        storageRoot,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return results;
+}
+export {
+  DEFAULT_VISIBILITY_THRESHOLD,
+  discoverGraphNamespaceRoots,
+  graphEdgeDecayStatusPath,
+  readGraphEdgeDecayStatus,
+  runGraphEdgeDecayMaintenance,
+  runGraphEdgeDecayMaintenanceAcrossNamespaces
+};
+//# sourceMappingURL=graph-edge-decay-PWB63GRE.js.map

package/dist/graph-edge-decay-PWB63GRE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/maintenance/graph-edge-decay.ts"],"sourcesContent":["/**\n * Graph-edge decay maintenance job (issue #681 PR 2/3).\n *\n * For each edge in the on-disk JSONL graph stores\n * (`<memoryDir>/state/graphs/{entity,time,causal}.jsonl`) call\n * {@link decayEdgeConfidence} from PR 1/3 and write the decayed edge\n * back to disk via the temp+rename atomic-replace pattern (CLAUDE.md\n * gotcha #54: never delete-before-write).\n *\n * Emits a structured telemetry record per run that the doctor surface\n * (`remnic doctor`) and a tail of the maintenance ledger can consume.\n *\n * Pure-helper-style API (the function takes a `memoryDir` + opts and\n * returns a record); callers wire the cron / MCP tool / CLI surfaces.\n */\n\nimport {\n  mkdir,\n  readdir,\n  readFile,\n  rename,\n  writeFile,\n} from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport {\n  decayEdgeConfidence,\n  DEFAULT_DECAY_FLOOR,\n  DEFAULT_DECAY_PER_WINDOW,\n  DEFAULT_DECAY_WINDOW_MS,\n  readEdgeConfidence,\n  type DecayOptions,\n} from \"../graph-edge-reinforcement.js\";\nimport {\n  graphFilePath,\n  graphsDir,\n  readEdgesStrict,\n  withGraphWriteLock,\n  type GraphEdge,\n  type GraphType,\n} from \"../graph.js\";\nimport { isSafeRouteNamespace } from \"../routing/engine.js\";\n\n/** Default visibility threshold for the \"below visibility\" telemetry counter. */\nexport const DEFAULT_VISIBILITY_THRESHOLD = 0.2;\n\nconst GRAPH_TYPES: readonly GraphType[] = [\"entity\", \"time\", \"causal\"] as const;\n\n/** Per-edge-type breakdown emitted by {@link runGraphEdgeDecayMaintenance}. */\nexport interface GraphEdgeDecayPerTypeStats {\n  type: GraphType;\n  edgesTotal: number;\n  edgesDecayed: number;\n  edgesBelowVisibilityThreshold: number;\n}\n\n/** Top-decayed-entity entry (label + total confidence drop summed across edges). */\nexport interface GraphEdgeDecayTopEntity {\n  label: string;\n  totalDrop: number;\n  edgeCount: number;\n}\n\n/**\n * Telemetry record emitted by every run of the decay job. Persisted to\n * `<memoryDir>/state/graph-edge-decay-status.json` for doctor consumption\n * and (optionally) appended to the maintenance ledger by callers.\n */\nexport interface GraphEdgeDecayTelemetry {\n  ranAt: string;\n  durationMs: number;\n  edgesTotal: number;\n  edgesDecayed: number;\n  edgesBelowVisibilityThreshold: number;\n  topDecayedEntities: GraphEdgeDecayTopEntity[];\n  perType: GraphEdgeDecayPerTypeStats[];\n  windowMs: number;\n  perWindow: number;\n  floor: number;\n  visibilityThreshold: number;\n}\n\nexport interface GraphEdgeDecayOptions extends DecayOptions {\n  /** Confidence threshold below which an edge counts as \"low visibility\". */\n  visibilityThreshold?: number;\n  /** Override \"now\" for deterministic testing. Defaults to `new Date().toISOString()`. */\n  now?: string;\n  /** When `true`, do not write decayed edges back — just compute telemetry. */\n  dryRun?: boolean;\n}\n\n/** Path of the latest-run status file. */\nexport function graphEdgeDecayStatusPath(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", \"graph-edge-decay-status.json\");\n}\n\n/** Write a JSONL file atomically using temp+rename (CLAUDE.md gotcha #54). */\nasync function writeJsonlAtomic(filePath: string, edges: GraphEdge[]): Promise<void> {\n  await mkdir(path.dirname(filePath), { recursive: true });\n  const body = edges.length === 0 ? \"\" : edges.map((e) => JSON.stringify(e)).join(\"\\n\") + \"\\n\";\n  // Codex P2 / gotcha #54: write to temp then rename. Never rmSync(target)\n  // before the rename succeeds; rename is atomic on the same filesystem.\n  // Include pid + monotonic-ish suffix so concurrent runs cannot collide.\n  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;\n  await writeFile(tempPath, body, \"utf-8\");\n  await rename(tempPath, filePath);\n}\n\n/**\n * Run a single decay pass over every edge type.\n *\n * Idempotency: PR 1/3's `decayEdgeConfidence` advances `lastReinforcedAt`\n * by exactly the windows it just charged for, so a second run with the\n * same `now` (or any `now` inside the new grace window) is a no-op.\n *\n * Returns the telemetry record. The record is also persisted to\n * {@link graphEdgeDecayStatusPath} so doctor / CLI can read the last run\n * without re-scanning the graphs.\n */\nexport async function runGraphEdgeDecayMaintenance(\n  memoryDir: string,\n  options: GraphEdgeDecayOptions = {},\n): Promise<GraphEdgeDecayTelemetry> {\n  const startedAt = Date.now();\n  const ranAt = options.now ?? new Date().toISOString();\n  const windowMs = options.windowMs ?? DEFAULT_DECAY_WINDOW_MS;\n  const perWindow = options.perWindow ?? DEFAULT_DECAY_PER_WINDOW;\n  const floor = options.floor ?? DEFAULT_DECAY_FLOOR;\n  const visibilityThreshold =\n    typeof options.visibilityThreshold === \"number\" && Number.isFinite(options.visibilityThreshold)\n      ? Math.max(0, Math.min(1, options.visibilityThreshold))\n      : DEFAULT_VISIBILITY_THRESHOLD;\n  const dryRun = options.dryRun === true;\n\n  await mkdir(graphsDir(memoryDir), { recursive: true });\n\n  const perType: GraphEdgeDecayPerTypeStats[] = [];\n  // Aggregate per-label decay drops across ALL graph types so the\n  // \"top decayed entities\" list reflects whichever label dominated\n  // each edge (entity name, threadId, or causal phrase). Sorting by\n  // total confidence drop highlights the edges decay actually moved\n  // most in this pass.\n  const dropByLabel = new Map<string, { totalDrop: number; edgeCount: number }>();\n\n  let edgesTotal = 0;\n  let edgesDecayed = 0;\n  let edgesBelowVisibilityThreshold = 0;\n\n  for (const type of GRAPH_TYPES) {\n    const filePath = graphFilePath(memoryDir, type);\n\n    // Hold the per-graph-file write lock across BOTH the read-snapshot\n    // and the atomic rewrite so concurrent `appendEdge()` calls cannot\n    // sneak in between (issue #729 / Codex P1, line 224). Without this\n    // lock the snapshot rewrite would silently drop any edge appended\n    // by extraction during the same window. Read failures other than\n    // ENOENT are surfaced via `readEdgesStrict` so I/O outages cannot\n    // be reported as \"no edges to decay\" (Codex P1, line 120).\n    const {\n      typeDecayed,\n      typeBelow,\n      typeTotal,\n    } = await withGraphWriteLock(filePath, async () => {\n      const edges = await readEdgesStrict(memoryDir, type);\n      const updated: GraphEdge[] = new Array(edges.length);\n\n      let localDecayed = 0;\n      let localBelow = 0;\n      let localChangedAny = false;\n\n      for (let i = 0; i < edges.length; i += 1) {\n        const edge = edges[i];\n        const before = readEdgeConfidence(edge);\n        const decayed = decayEdgeConfidence(edge, ranAt, { windowMs, perWindow, floor });\n        const after = readEdgeConfidence(decayed);\n\n        // Only count as \"decayed\" when the confidence actually dropped.\n        // `decayEdgeConfidence` may return an unchanged copy (still inside\n        // the grace window, or already at/below the floor) — those are\n        // visited but not decayed.\n        if (after < before) {\n          localDecayed += 1;\n          const drop = before - after;\n          const label = typeof edge.label === \"string\" ? edge.label : \"\";\n          // Skip empty labels in the top list — surfacing them produces\n          // a meaningless \"\" entry that crowds the report.\n          if (label.length > 0) {\n            const prev = dropByLabel.get(label);\n            if (prev) {\n              prev.totalDrop += drop;\n              prev.edgeCount += 1;\n            } else {\n              dropByLabel.set(label, { totalDrop: drop, edgeCount: 1 });\n            }\n          }\n        }\n        if (after < visibilityThreshold) {\n          localBelow += 1;\n        }\n        updated[i] = decayed;\n        // Detect any structural change (confidence OR lastReinforcedAt anchor advance)\n        // so we only rewrite the JSONL when there's something to persist.\n        if (\n          decayed.confidence !== edge.confidence ||\n          decayed.lastReinforcedAt !== edge.lastReinforcedAt\n        ) {\n          localChangedAny = true;\n        }\n      }\n\n      if (!dryRun && localChangedAny && edges.length > 0) {\n        await writeJsonlAtomic(filePath, updated);\n      }\n\n      return {\n        typeDecayed: localDecayed,\n        typeBelow: localBelow,\n        typeTotal: edges.length,\n      };\n    });\n\n    edgesDecayed += typeDecayed;\n    edgesBelowVisibilityThreshold += typeBelow;\n    edgesTotal += typeTotal;\n    perType.push({\n      type,\n      edgesTotal: typeTotal,\n      edgesDecayed: typeDecayed,\n      edgesBelowVisibilityThreshold: typeBelow,\n    });\n  }\n\n  // Stable secondary key on label keeps ordering deterministic when two\n  // labels happen to have exactly the same totalDrop (gotcha #19).\n  const topDecayedEntities: GraphEdgeDecayTopEntity[] = [...dropByLabel.entries()]\n    .map(([label, agg]) => ({ label, totalDrop: agg.totalDrop, edgeCount: agg.edgeCount }))\n    .sort((a, b) => {\n      if (b.totalDrop !== a.totalDrop) return b.totalDrop - a.totalDrop;\n      return a.label.localeCompare(b.label);\n    })\n    .slice(0, 5);\n\n  const telemetry: GraphEdgeDecayTelemetry = {\n    ranAt,\n    durationMs: Date.now() - startedAt,\n    edgesTotal,\n    edgesDecayed,\n    edgesBelowVisibilityThreshold,\n    topDecayedEntities,\n    perType,\n    windowMs,\n    perWindow,\n    floor,\n    visibilityThreshold,\n  };\n\n  if (!dryRun) {\n    await persistTelemetry(memoryDir, telemetry);\n  }\n\n  return telemetry;\n}\n\nasync function persistTelemetry(\n  memoryDir: string,\n  telemetry: GraphEdgeDecayTelemetry,\n): Promise<void> {\n  const statusPath = graphEdgeDecayStatusPath(memoryDir);\n  await mkdir(path.dirname(statusPath), { recursive: true });\n  const tempPath = `${statusPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;\n  // Wrap I/O in try/catch (gotcha #13) — failing to persist telemetry must\n  // not blow up the maintenance run; the in-memory record is still returned.\n  try {\n    await writeFile(tempPath, JSON.stringify(telemetry, null, 2) + \"\\n\", \"utf-8\");\n    await rename(tempPath, statusPath);\n  } catch {\n    // Best-effort: callers still receive the in-memory telemetry record.\n  }\n}\n\n/** Read the last persisted decay-run telemetry, if any. */\nexport async function readGraphEdgeDecayStatus(\n  memoryDir: string,\n): Promise<GraphEdgeDecayTelemetry | null> {\n  try {\n    const raw = await readFile(graphEdgeDecayStatusPath(memoryDir), \"utf-8\");\n    const parsed = JSON.parse(raw);\n    // Validate the parsed payload is a plain object (gotcha #18: JSON.parse('null') is valid).\n    if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n      return null;\n    }\n    return parsed as GraphEdgeDecayTelemetry;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Per-namespace telemetry record returned by\n * {@link runGraphEdgeDecayMaintenanceAcrossNamespaces}. Each entry\n * pairs the namespace name with its decay telemetry (or an error\n * string if that namespace's run failed). Allows operators to spot\n * I/O outages on a single namespace without masking the rest.\n */\nexport interface GraphEdgeDecayNamespaceResult {\n  namespace: string;\n  storageRoot: string;\n  telemetry?: GraphEdgeDecayTelemetry;\n  error?: string;\n}\n\n/**\n * Discover every namespace storage root that may contain graph files.\n *\n * Returns a list of `{ namespace, storageRoot }` entries:\n *   - The default namespace at `memoryDir` (always present).\n *   - Each subdirectory under `memoryDir/namespaces/` that passes\n *     `isSafeRouteNamespace`.\n *\n * Per gotcha #42: read paths must enumerate the same namespace layer\n * as write paths so non-default namespaces don't get skipped during\n * maintenance. Issue #729 / Codex P2.\n */\nexport async function discoverGraphNamespaceRoots(\n  memoryDir: string,\n  options: { namespacesEnabled: boolean; defaultNamespace: string },\n): Promise<{ namespace: string; storageRoot: string }[]> {\n  const seen = new Map<string, string>();\n  // Default namespace always lives at memoryDir (NamespaceStorageRouter\n  // falls back to memoryDir when memoryDir/namespaces/<default> does\n  // not exist).\n  seen.set(options.defaultNamespace, memoryDir);\n\n  if (!options.namespacesEnabled) {\n    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));\n  }\n\n  const namespacesDir = path.join(memoryDir, \"namespaces\");\n  let entries: import(\"node:fs\").Dirent[];\n  try {\n    entries = await readdir(namespacesDir, { withFileTypes: true });\n  } catch {\n    // No namespaces dir yet — only the default namespace exists.\n    return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));\n  }\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    if (!isSafeRouteNamespace(entry.name)) continue;\n    const root = path.join(namespacesDir, entry.name);\n    seen.set(entry.name, root);\n  }\n\n  return [...seen.entries()].map(([namespace, storageRoot]) => ({ namespace, storageRoot }));\n}\n\n/**\n * Run the decay maintenance pass against every namespace storage root.\n *\n * In namespaces-enabled deployments, non-default namespaces store\n * their graph JSONLs under `memoryDir/namespaces/<ns>/state/graphs/`,\n * so a single-root run only updates the default namespace and silently\n * skips the rest (issue #729 / Codex P2).\n *\n * Failures in one namespace do not block other namespaces; per-root\n * errors are surfaced in the `error` field of each result.\n */\nexport async function runGraphEdgeDecayMaintenanceAcrossNamespaces(\n  memoryDir: string,\n  options: GraphEdgeDecayOptions & {\n    namespacesEnabled: boolean;\n    defaultNamespace: string;\n  },\n): Promise<GraphEdgeDecayNamespaceResult[]> {\n  const { namespacesEnabled, defaultNamespace, ...decayOptions } = options;\n  const roots = await discoverGraphNamespaceRoots(memoryDir, {\n    namespacesEnabled,\n    defaultNamespace,\n  });\n\n  const results: GraphEdgeDecayNamespaceResult[] = [];\n  for (const { namespace, storageRoot } of roots) {\n    try {\n      const telemetry = await runGraphEdgeDecayMaintenance(storageRoot, decayOptions);\n      results.push({ namespace, storageRoot, telemetry });\n    } catch (err) {\n      results.push({\n        namespace,\n        storageRoot,\n        error: err instanceof Error ? err.message : String(err),\n      });\n    }\n  }\n  return results;\n}\n"],"mappings":"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","names":[]}

package/dist/graph-edge-reinforcement.d.ts

@@ -0,0 +1,81 @@
+import { GraphEdge } from './graph.js';
+
+/**
+ * Graph edge confidence + reinforcement primitives (issue #681, PR 1/3).
+ *
+ * Pure functions only — no I/O, no global state. The maintenance job (PR 2/3)
+ * and PageRank weighting (PR 3/3) compose these helpers.
+ *
+ * Schema:
+ *   - `confidence`   ∈ [0, 1]; missing on legacy edges, treated as 1.0.
+ *   - `lastReinforcedAt` — ISO timestamp of most recent reinforcement; missing
+ *     on legacy edges, treated as the original edge `ts`.
+ *
+ * Defaults documented here are the agreed-on starting points and may be
+ * tuned later via config. They live as named constants so call sites and
+ * tests share the same values.
+ */
+
+/** Default confidence bump per reinforcement event. */
+declare const DEFAULT_REINFORCE_DELTA = 0.05;
+/** Maximum edge confidence — confidence is capped at this on reinforcement. */
+declare const CONFIDENCE_CEILING = 1;
+/** Default decay window in milliseconds (90 days). */
+declare const DEFAULT_DECAY_WINDOW_MS: number;
+/** Default decay floor — confidence will not drop below this purely from age. */
+declare const DEFAULT_DECAY_FLOOR = 0.1;
+/** Default per-window decay amount (linear). */
+declare const DEFAULT_DECAY_PER_WINDOW = 0.1;
+/**
+ * Treat a missing `confidence` on a legacy edge as 1.0.
+ * Clamps to `[0, CONFIDENCE_CEILING]` so downstream math is well-behaved.
+ */
+declare function readEdgeConfidence(edge: Pick<GraphEdge, "confidence">): number;
+/**
+ * Resolve the reference timestamp for decay calculations.
+ * Falls back to the edge's creation `ts` when `lastReinforcedAt` is absent
+ * (legacy edges have never been reinforced).
+ */
+declare function readLastReinforcedAt(edge: Pick<GraphEdge, "lastReinforcedAt" | "ts">): string;
+/**
+ * Reinforce an edge: bump confidence by `delta` (capped at 1.0) and stamp
+ * `lastReinforcedAt = now`. Pure — returns a new edge, never mutates input.
+ *
+ * Idempotency note: calling reinforceEdge twice with the same `now` and a
+ * delta of 0 returns an edge equal to the input (modulo timestamp).
+ *
+ * @param edge  the edge to reinforce
+ * @param now   ISO timestamp of the reinforcement event
+ * @param delta confidence bump; defaults to DEFAULT_REINFORCE_DELTA
+ */
+declare function reinforceEdge(edge: GraphEdge, now: string, delta?: number): GraphEdge;
+/** Options for {@link decayEdgeConfidence}. */
+interface DecayOptions {
+    /** Decay window in milliseconds. Defaults to 90 days. */
+    windowMs?: number;
+    /** Per-window decay amount. Defaults to 0.1. */
+    perWindow?: number;
+    /** Floor confidence will not decay below. Defaults to 0.1. */
+    floor?: number;
+}
+/**
+ * Apply linear decay to an edge's confidence based on time since last
+ * reinforcement (or creation, for legacy edges). Pure — returns a new edge.
+ *
+ * Decay model:
+ *   age = now - lastReinforcedAt
+ *   if age <= windowMs:           confidence unchanged
+ *   else:                          confidence -= perWindow * floor((age - windowMs) / windowMs + 1)
+ *   confidence is clamped to [floor, 1.0]
+ *
+ * Boundary semantics: `age === windowMs` is INSIDE the no-decay grace period
+ * (`<=`). Decay only kicks in once age strictly exceeds the window. This
+ * keeps the boundary deterministic and easy to test.
+ *
+ * @param edge edge to decay (confidence and lastReinforcedAt may be absent)
+ * @param now  ISO timestamp representing "now"
+ * @param opts override window / per-window / floor; otherwise defaults are used
+ */
+declare function decayEdgeConfidence(edge: GraphEdge, now: string, opts?: DecayOptions): GraphEdge;
+
+export { CONFIDENCE_CEILING, DEFAULT_DECAY_FLOOR, DEFAULT_DECAY_PER_WINDOW, DEFAULT_DECAY_WINDOW_MS, DEFAULT_REINFORCE_DELTA, type DecayOptions, decayEdgeConfidence, readEdgeConfidence, readLastReinforcedAt, reinforceEdge };

package/dist/graph-edge-reinforcement.js

@@ -0,0 +1,24 @@
+import {
+  CONFIDENCE_CEILING,
+  DEFAULT_DECAY_FLOOR,
+  DEFAULT_DECAY_PER_WINDOW,
+  DEFAULT_DECAY_WINDOW_MS,
+  DEFAULT_REINFORCE_DELTA,
+  decayEdgeConfidence,
+  readEdgeConfidence,
+  readLastReinforcedAt,
+  reinforceEdge
+} from "./chunk-2LSZVONP.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  CONFIDENCE_CEILING,
+  DEFAULT_DECAY_FLOOR,
+  DEFAULT_DECAY_PER_WINDOW,
+  DEFAULT_DECAY_WINDOW_MS,
+  DEFAULT_REINFORCE_DELTA,
+  decayEdgeConfidence,
+  readEdgeConfidence,
+  readLastReinforcedAt,
+  reinforceEdge
+};
+//# sourceMappingURL=graph-edge-reinforcement.js.map

package/dist/graph-edge-reinforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/graph-events.d.ts

@@ -0,0 +1,87 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * In-process EventEmitter for graph mutation events (issue #691 PR 5/5).
+ *
+ * The singleton is keyed by memoryDir so multiple orchestrator instances in
+ * the same process get distinct event buses (CLAUDE.md rule 11: scope globals
+ * per service).  The SSE handler in access-http.ts subscribes to the bus for
+ * the resolved namespace and fans out to connected clients.
+ *
+ * Event types mirror the five mutations the graph layer can produce:
+ *   node-added    — a memory file was referenced for the first time
+ *   node-updated  — a memory file's metadata changed
+ *   edge-added    — a new edge was appended
+ *   edge-updated  — an existing edge's confidence/weight was modified
+ *   edge-removed  — an edge was pruned (e.g. by decay maintenance)
+ *
+ * The `GraphEventBus` interface is intentionally narrow so nothing outside
+ * this module needs to import Node.js EventEmitter directly.
+ */
+
+type GraphEventType = "node-added" | "node-updated" | "edge-added" | "edge-updated" | "edge-removed";
+interface GraphEvent {
+    type: GraphEventType;
+    /** Memory dir that owns this event (absolute path). */
+    memoryDir: string;
+    /** ISO timestamp of the event. */
+    ts: string;
+    /** Payload depends on event type — always serialisable to JSON. */
+    payload: Record<string, unknown>;
+}
+interface NodeAddedPayload {
+    nodeId: string;
+    kind: string;
+    label: string;
+    lastUpdated: string;
+}
+interface NodeUpdatedPayload {
+    nodeId: string;
+    kind: string;
+    label: string;
+    lastUpdated: string;
+}
+interface EdgeAddedPayload {
+    source: string;
+    target: string;
+    kind: string;
+    weight: number;
+    label: string;
+    confidence: number;
+}
+interface EdgeUpdatedPayload {
+    source: string;
+    target: string;
+    kind: string;
+    weight: number;
+    confidence: number;
+}
+interface EdgeRemovedPayload {
+    source: string;
+    target: string;
+    kind: string;
+}
+/**
+ * Return (or lazily create) the event bus for the given memoryDir.
+ * The same bus is shared by the write side (graph.ts → appendEdge hooks) and
+ * the read side (EngramAccessHttpServer SSE handler).
+ */
+declare function getGraphEventBus(memoryDir: string): EventEmitter;
+/**
+ * Emit a single graph event onto the bus for memoryDir.
+ * Fails open: any listener that throws is caught so one bad client can't
+ * crash the extraction pipeline.
+ */
+declare function emitGraphEvent(memoryDir: string, type: GraphEventType, payload: Record<string, unknown>): void;
+/**
+ * Subscribe to graph events for a given memoryDir.
+ * Returns an unsubscribe function.
+ */
+declare function subscribeGraphEvents(memoryDir: string, listener: (event: GraphEvent) => void): () => void;
+/**
+ * Remove all listeners and the bus entry for a memoryDir.
+ * Useful for tests that spin up isolated memory dirs.
+ */
+declare function destroyGraphEventBus(memoryDir: string): void;
+
+export { type EdgeAddedPayload, type EdgeRemovedPayload, type EdgeUpdatedPayload, type GraphEvent, type GraphEventType, type NodeAddedPayload, type NodeUpdatedPayload, destroyGraphEventBus, emitGraphEvent, getGraphEventBus, subscribeGraphEvents };