@remnic/core 1.1.12 → 1.1.13

package/src/procedural/procedure-stats.ts

@@ -0,0 +1,213 @@
+/**
+ * Procedural memory stats surface (issue #567 PR 5/5).
+ *
+ * Pure helper that tallies procedure memories by status and summarizes the
+ * current `procedural.*` config so operators (and the dashboard) can see,
+ * in one call, how procedural memory is behaving in a namespace.
+ *
+ * Consumed by:
+ *   - CLI `remnic procedural stats`
+ *   - HTTP `GET /engram/v1/procedural/stats`
+ *   - MCP `remnic.procedural_stats` (+ `engram.procedural_stats` alias)
+ */
+import type { MemoryFile, MemoryStatus, PluginConfig } from "../types.js";
+import type { StorageManager } from "../storage.js";
+
+export interface ProcedureStatusCounts {
+  total: number;
+  active: number;
+  pending_review: number;
+  rejected: number;
+  quarantined: number;
+  superseded: number;
+  archived: number;
+  /** Any status the enum doesn't yet cover. */
+  other: number;
+}
+
+export interface ProcedureStatsConfigSnapshot {
+  enabled: boolean;
+  minOccurrences: number;
+  successFloor: number;
+  autoPromoteOccurrences: number;
+  autoPromoteEnabled: boolean;
+  lookbackDays: number;
+  recallMaxProcedures: number;
+}
+
+export interface ProcedureStatsRecent {
+  /** ISO 8601 timestamp of the most recent procedure write, or null. */
+  lastWriteAt: string | null;
+  /** Count of procedure files with `created` (or `updated`) in the last 7 days. */
+  writesLast7Days: number;
+  /** Count of procedures whose `source` is the procedure miner. */
+  minerSourced: number;
+}
+
+export interface ProcedureStatsReport {
+  schemaVersion: 1;
+  generatedAt: string;
+  counts: ProcedureStatusCounts;
+  recent: ProcedureStatsRecent;
+  config: ProcedureStatsConfigSnapshot;
+}
+
+function snapshotConfig(config: PluginConfig): ProcedureStatsConfigSnapshot {
+  const p = config.procedural;
+  return {
+    enabled: p?.enabled === true,
+    minOccurrences: typeof p?.minOccurrences === "number" ? p.minOccurrences : 0,
+    successFloor: typeof p?.successFloor === "number" ? p.successFloor : 0,
+    autoPromoteOccurrences:
+      typeof p?.autoPromoteOccurrences === "number"
+        ? p.autoPromoteOccurrences
+        : 0,
+    autoPromoteEnabled: p?.autoPromoteEnabled === true,
+    lookbackDays: typeof p?.lookbackDays === "number" ? p.lookbackDays : 0,
+    recallMaxProcedures:
+      typeof p?.recallMaxProcedures === "number" ? p.recallMaxProcedures : 0,
+  };
+}
+
+function tsMs(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Read all memories from storage and tally procedures by status + recency.
+ * `nowMs` is injectable so tests can pin the "last 7 days" window.
+ */
+export async function computeProcedureStats(options: {
+  storage: StorageManager;
+  config: PluginConfig;
+  nowMs?: number;
+}): Promise<ProcedureStatsReport> {
+  const { storage, config } = options;
+  const nowMs = options.nowMs ?? Date.now();
+  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+
+  const counts: ProcedureStatusCounts = {
+    total: 0,
+    active: 0,
+    pending_review: 0,
+    rejected: 0,
+    quarantined: 0,
+    superseded: 0,
+    archived: 0,
+    other: 0,
+  };
+
+  let lastWriteMs: number | null = null;
+  let writesLast7Days = 0;
+  let minerSourced = 0;
+
+  const known: MemoryStatus[] = [
+    "active",
+    "pending_review",
+    "rejected",
+    "quarantined",
+    "superseded",
+    "archived",
+  ];
+
+  // Iterate both live and archived memories so the counts surface matches
+  // what operators expect when procedures have been archived via
+  // `archiveMemory` (Codex P2 on #611). `readAllMemories` alone skips
+  // `archive/`, which would otherwise underreport `counts.archived` and
+  // `counts.total`.
+  const seen = new Set<string>();
+  const live = await storage.readAllMemories();
+  const archived = await storage.readArchivedMemories();
+  const pool: MemoryFile[] = [...live, ...archived];
+  for (const m of pool) {
+    if (m.frontmatter.category !== "procedure") continue;
+    // Dedupe by id so a procedure appearing in both live + archive (mid-
+    // archive race) isn't counted twice.
+    if (seen.has(m.frontmatter.id)) continue;
+    seen.add(m.frontmatter.id);
+    counts.total += 1;
+    const status = m.frontmatter.status ?? "active";
+    if ((known as string[]).includes(status)) {
+      // Safe index: the status enum values are the counts keys.
+      (counts as unknown as Record<string, number>)[status] += 1;
+    } else {
+      counts.other += 1;
+    }
+
+    // Recency semantics (Codex P2 on #611): use the latest of `updated` and
+    // `created`, not a fallback chain, so recently-edited procedures are
+    // reflected in `lastWriteAt` and `writesLast7Days`. Missing timestamps
+    // skip the row.
+    const createdMs = tsMs(m.frontmatter.created);
+    const updatedMs = tsMs(m.frontmatter.updated);
+    const latestMs =
+      createdMs !== null && updatedMs !== null
+        ? Math.max(createdMs, updatedMs)
+        : (updatedMs ?? createdMs);
+    if (latestMs !== null) {
+      if (lastWriteMs === null || latestMs > lastWriteMs) {
+        lastWriteMs = latestMs;
+      }
+      // Exclusive upper bound per CLAUDE.md rule 35 — use half-open window.
+      if (latestMs >= nowMs - sevenDaysMs && latestMs < nowMs) {
+        writesLast7Days += 1;
+      }
+    }
+
+    if (m.frontmatter.source === "procedure-miner") {
+      minerSourced += 1;
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date(nowMs).toISOString(),
+    counts,
+    recent: {
+      lastWriteAt: lastWriteMs !== null ? new Date(lastWriteMs).toISOString() : null,
+      writesLast7Days,
+      minerSourced,
+    },
+    config: snapshotConfig(config),
+  };
+}
+
+/**
+ * Render `ProcedureStatsReport` as a human-friendly plain-text block for CLI
+ * operators. Keep it deterministic — no colors, no ANSI. Used by `--format text`.
+ */
+export function formatProcedureStatsText(report: ProcedureStatsReport): string {
+  const { counts, recent, config } = report;
+  const lines: string[] = [];
+  lines.push(`Procedural memory stats (schema v${report.schemaVersion})`);
+  lines.push(`  generated: ${report.generatedAt}`);
+  lines.push("");
+  lines.push(`  config:`);
+  lines.push(`    enabled:                 ${config.enabled}`);
+  lines.push(`    minOccurrences:          ${config.minOccurrences}`);
+  lines.push(`    successFloor:            ${config.successFloor}`);
+  lines.push(`    autoPromoteOccurrences:  ${config.autoPromoteOccurrences}`);
+  lines.push(`    autoPromoteEnabled:      ${config.autoPromoteEnabled}`);
+  lines.push(`    lookbackDays:            ${config.lookbackDays}`);
+  lines.push(`    recallMaxProcedures:     ${config.recallMaxProcedures}`);
+  lines.push("");
+  lines.push(`  counts:`);
+  lines.push(`    total:           ${counts.total}`);
+  lines.push(`    active:          ${counts.active}`);
+  lines.push(`    pending_review:  ${counts.pending_review}`);
+  lines.push(`    rejected:        ${counts.rejected}`);
+  lines.push(`    quarantined:     ${counts.quarantined}`);
+  lines.push(`    superseded:      ${counts.superseded}`);
+  lines.push(`    archived:        ${counts.archived}`);
+  if (counts.other > 0) {
+    lines.push(`    other:           ${counts.other}`);
+  }
+  lines.push("");
+  lines.push(`  recent:`);
+  lines.push(`    lastWriteAt:      ${recent.lastWriteAt ?? "(none)"}`);
+  lines.push(`    writesLast7Days:  ${recent.writesLast7Days}`);
+  lines.push(`    minerSourced:     ${recent.minerSourced}`);
+  return lines.join("\n") + "\n";
+}

package/src/procedural/procedure-types.ts

@@ -0,0 +1,132 @@
+/**
+ * Procedural memory types (issue #519).
+ * Bodies use ordered "## Step N" sections; machine fields live in frontmatter / structuredAttributes.
+ */
+
+export interface ProcedureStep {
+  order: number;
+  intent: string;
+  toolCall?: {
+    kind: string;
+    signature: string;
+  };
+  expectedOutcome?: string;
+  optional?: boolean;
+}
+
+/** Normalize loose extraction JSON into ProcedureStep records. */
+export function normalizeProcedureSteps(raw: unknown): ProcedureStep[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ProcedureStep[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const s = raw[i];
+    if (!s || typeof s !== "object") continue;
+    const o = s as Record<string, unknown>;
+    const intent = typeof o.intent === "string" ? o.intent.trim() : "";
+    if (!intent) continue;
+    const orderRaw = o.order;
+    const order =
+      typeof orderRaw === "number" && Number.isFinite(orderRaw)
+        ? Math.max(1, Math.floor(orderRaw))
+        : i + 1;
+    let toolCall: ProcedureStep["toolCall"];
+    const tc = o.toolCall;
+    if (tc && typeof tc === "object" && !Array.isArray(tc)) {
+      const t = tc as Record<string, unknown>;
+      const kind = typeof t.kind === "string" ? t.kind.trim() : "";
+      const signature = typeof t.signature === "string" ? t.signature.trim() : "";
+      if (kind && signature) {
+        toolCall = { kind, signature };
+      }
+    }
+    const expectedOutcome =
+      typeof o.expectedOutcome === "string" && o.expectedOutcome.trim()
+        ? o.expectedOutcome.trim()
+        : undefined;
+    const optional = o.optional === true ? true : undefined;
+    out.push({ order, intent, toolCall, expectedOutcome, optional });
+  }
+  return out;
+}
+
+/** Title line plus serialized steps for storage.writeMemory body. */
+export function buildProcedurePersistBody(title: string, procedureSteps: unknown): string {
+  const head = typeof title === "string" ? title.trim() : "";
+  const steps = normalizeProcedureSteps(procedureSteps);
+  if (steps.length === 0) return head;
+  return `${head}\n\n${buildProcedureMarkdownBody(steps)}`.trimEnd() + "\n";
+}
+
+/** Serialize steps into markdown body (human-editable). */
+export function buildProcedureMarkdownBody(steps: ProcedureStep[]): string {
+  const sorted = [...steps].sort((a, b) => a.order - b.order);
+  const lines: string[] = [];
+  for (const step of sorted) {
+    const n = Number.isFinite(step.order) ? Math.max(1, Math.floor(step.order)) : 1;
+    lines.push(`## Step ${n}`);
+    lines.push("");
+    lines.push(step.intent.trim());
+    if (step.toolCall?.kind && step.toolCall.signature) {
+      lines.push("");
+      lines.push(`- Tool: \`${step.toolCall.kind}\` — ${step.toolCall.signature}`);
+    }
+    if (step.expectedOutcome?.trim()) {
+      lines.push("");
+      lines.push(`- Expected: ${step.expectedOutcome.trim()}`);
+    }
+    if (step.optional === true) {
+      lines.push("");
+      lines.push("- Optional: true");
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+const STEP_HEADER_RE = /^##\s+Step\s+(\d+)\s*$/im;
+
+/**
+ * Best-effort parse of "## Step N" blocks into ProcedureStep records.
+ * Returns null when no step headers are found.
+ */
+export function parseProcedureStepsFromBody(content: string): ProcedureStep[] | null {
+  const text = content.replace(/\r\n/g, "\n").trim();
+  if (!text) return null;
+  const matches = [...text.matchAll(new RegExp(STEP_HEADER_RE.source, "gim"))];
+  if (matches.length === 0) return null;
+
+  const steps: ProcedureStep[] = [];
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const order = Number.parseInt(m[1] ?? "1", 10);
+    const start = (m.index ?? 0) + m[0].length;
+    const end = i + 1 < matches.length ? (matches[i + 1].index ?? text.length) : text.length;
+    const block = text.slice(start, end).trim();
+    const lines = block.split("\n").map((l) => l.trim());
+    const intentLines = lines.filter(
+      (l) => l.length > 0 && !l.startsWith("- Tool:") && !l.startsWith("- Expected:") && !l.startsWith("- Optional:"),
+    );
+    const intent = intentLines.join(" ").trim() || "(unspecified)";
+    let toolCall: ProcedureStep["toolCall"];
+    const toolLine = lines.find((l) => l.startsWith("- Tool:"));
+    if (toolLine) {
+      const inner = toolLine.replace(/^- Tool:\s*/i, "").trim();
+      const tick = inner.match(/^`([^`]+)`\s*[—-]\s*(.+)$/);
+      if (tick) {
+        toolCall = { kind: tick[1].trim(), signature: tick[2].trim() };
+      }
+    }
+    const expectedLine = lines.find((l) => l.startsWith("- Expected:"));
+    const expectedOutcome = expectedLine?.replace(/^- Expected:\s*/i, "").trim();
+    const optional = /^- Optional:\s*true$/i.test(lines.find((l) => l.startsWith("- Optional:")) ?? "");
+
+    steps.push({
+      order: Number.isFinite(order) ? order : i + 1,
+      intent,
+      toolCall,
+      expectedOutcome: expectedOutcome?.length ? expectedOutcome : undefined,
+      optional: optional || undefined,
+    });
+  }
+  return steps.length > 0 ? steps : null;
+}

package/src/procedural/reinforcement-core.test.ts

@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { clusterByKey, summarizeCluster } from "./reinforcement-core.js";
+
+interface Sample {
+  id: string;
+  group: string;
+  ts: string;
+}
+
+test("clusterByKey returns empty map for empty input", () => {
+  const out = clusterByKey<Sample>([], (s) => s.group);
+  assert.equal(out.size, 0);
+});
+
+test("clusterByKey returns a single cluster when all items share a key", () => {
+  const items: Sample[] = [
+    { id: "a", group: "g1", ts: "2026-04-01T00:00:00Z" },
+    { id: "b", group: "g1", ts: "2026-04-02T00:00:00Z" },
+    { id: "c", group: "g1", ts: "2026-04-03T00:00:00Z" },
+  ];
+  const out = clusterByKey(items, (s) => s.group);
+  assert.equal(out.size, 1);
+  const cluster = out.get("g1");
+  assert.ok(cluster);
+  assert.equal(cluster.length, 3);
+  // Preserves input order
+  assert.deepEqual(
+    cluster.map((s) => s.id),
+    ["a", "b", "c"],
+  );
+});
+
+test("clusterByKey splits items into multiple clusters by key", () => {
+  const items: Sample[] = [
+    { id: "a", group: "g1", ts: "2026-04-01T00:00:00Z" },
+    { id: "b", group: "g2", ts: "2026-04-02T00:00:00Z" },
+    { id: "c", group: "g1", ts: "2026-04-03T00:00:00Z" },
+    { id: "d", group: "g3", ts: "2026-04-04T00:00:00Z" },
+    { id: "e", group: "g2", ts: "2026-04-05T00:00:00Z" },
+  ];
+  const out = clusterByKey(items, (s) => s.group);
+  assert.equal(out.size, 3);
+  assert.deepEqual(out.get("g1")?.map((s) => s.id), ["a", "c"]);
+  assert.deepEqual(out.get("g2")?.map((s) => s.id), ["b", "e"]);
+  assert.deepEqual(out.get("g3")?.map((s) => s.id), ["d"]);
+  // First-seen insertion order
+  assert.deepEqual(Array.from(out.keys()), ["g1", "g2", "g3"]);
+});
+
+test("clusterByKey throws TypeError when keyFn returns a non-string", () => {
+  const items = [{ id: "a" }];
+  assert.throws(
+    () => clusterByKey(items, () => undefined as unknown as string),
+    (err: Error) => err instanceof TypeError && /must return a string/.test(err.message),
+  );
+  assert.throws(
+    () => clusterByKey(items, () => null as unknown as string),
+    (err: Error) => err instanceof TypeError && /null/.test(err.message),
+  );
+  assert.throws(
+    () => clusterByKey(items, () => 42 as unknown as string),
+    (err: Error) => err instanceof TypeError && /number/.test(err.message),
+  );
+});
+
+test("summarizeCluster throws RangeError on empty cluster", () => {
+  assert.throws(
+    () => summarizeCluster<Sample>([], (s) => s.ts),
+    (err: Error) => err instanceof RangeError,
+  );
+});
+
+test("summarizeCluster computes count and firstSeen/lastSeen for single-item cluster", () => {
+  const items: Sample[] = [{ id: "a", group: "g", ts: "2026-04-01T00:00:00Z" }];
+  const out = summarizeCluster(items, (s) => s.ts);
+  assert.equal(out.count, 1);
+  assert.equal(out.firstSeen, "2026-04-01T00:00:00Z");
+  assert.equal(out.lastSeen, "2026-04-01T00:00:00Z");
+});
+
+test("summarizeCluster finds min/max regardless of input order", () => {
+  const items: Sample[] = [
+    { id: "b", group: "g", ts: "2026-04-15T00:00:00Z" },
+    { id: "a", group: "g", ts: "2026-04-01T00:00:00Z" },
+    { id: "c", group: "g", ts: "2026-04-30T00:00:00Z" },
+    { id: "d", group: "g", ts: "2026-04-10T00:00:00Z" },
+  ];
+  const out = summarizeCluster(items, (s) => s.ts);
+  assert.equal(out.count, 4);
+  assert.equal(out.firstSeen, "2026-04-01T00:00:00Z");
+  assert.equal(out.lastSeen, "2026-04-30T00:00:00Z");
+});
+
+test("summarizeCluster handles all-equal timestamps", () => {
+  const ts = "2026-04-25T12:00:00Z";
+  const items: Sample[] = [
+    { id: "a", group: "g", ts },
+    { id: "b", group: "g", ts },
+    { id: "c", group: "g", ts },
+  ];
+  const out = summarizeCluster(items, (s) => s.ts);
+  assert.equal(out.count, 3);
+  assert.equal(out.firstSeen, ts);
+  assert.equal(out.lastSeen, ts);
+});
+
+test("summarizeCluster works with non-ISO string keys via localeCompare", () => {
+  // Simple lexicographic ordering — extractTimestamp can return any string.
+  const items = [{ k: "b" }, { k: "a" }, { k: "c" }];
+  const out = summarizeCluster(items, (s) => s.k);
+  assert.equal(out.firstSeen, "a");
+  assert.equal(out.lastSeen, "c");
+});
+
+test("clusterByKey + summarizeCluster compose for end-to-end summarization", () => {
+  const items: Sample[] = [
+    { id: "a", group: "g1", ts: "2026-04-01T00:00:00Z" },
+    { id: "b", group: "g2", ts: "2026-04-02T00:00:00Z" },
+    { id: "c", group: "g1", ts: "2026-04-10T00:00:00Z" },
+    { id: "d", group: "g1", ts: "2026-04-05T00:00:00Z" },
+  ];
+  const clusters = clusterByKey(items, (s) => s.group);
+  const g1 = summarizeCluster(clusters.get("g1") ?? [], (s) => s.ts);
+  assert.equal(g1.count, 3);
+  assert.equal(g1.firstSeen, "2026-04-01T00:00:00Z");
+  assert.equal(g1.lastSeen, "2026-04-10T00:00:00Z");
+  const g2 = summarizeCluster(clusters.get("g2") ?? [], (s) => s.ts);
+  assert.equal(g2.count, 1);
+  assert.equal(g2.firstSeen, g2.lastSeen);
+});

package/src/procedural/reinforcement-core.ts

@@ -0,0 +1,73 @@
+/**
+ * Generic reinforcement-core primitives extracted from `procedure-miner.ts`
+ * (issue #687 PR 1/4). Procedure-specific scoring (success rate, step
+ * normalization) intentionally stays in the miner — this module only
+ * exposes category-agnostic clustering and cluster summarization helpers
+ * so future PRs can run reinforcement across non-procedural categories.
+ *
+ * Pure refactor — no behavior change.
+ */
+
+/**
+ * Group `items` into clusters keyed by `keyFn(item)`.
+ *
+ * - Preserves the original input order within each cluster's array.
+ * - The returned `Map` insertion order matches first-seen key order, so
+ *   downstream iteration is deterministic for a given input.
+ * - Throws `TypeError` if `keyFn` returns a non-string (e.g. `undefined`,
+ *   `null`, or a number). Callers must produce a stable string key.
+ */
+export function clusterByKey<T>(items: readonly T[], keyFn: (item: T) => string): Map<string, T[]> {
+  const clusters = new Map<string, T[]>();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (typeof key !== "string") {
+      throw new TypeError(
+        `clusterByKey: keyFn must return a string, got ${key === null ? "null" : typeof key}`,
+      );
+    }
+    const existing = clusters.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      clusters.set(key, [item]);
+    }
+  }
+  return clusters;
+}
+
+export interface ClusterSummary {
+  /** Number of items in the cluster. */
+  count: number;
+  /** Earliest timestamp seen in the cluster (string min via `localeCompare`). */
+  firstSeen: string;
+  /** Latest timestamp seen in the cluster (string max via `localeCompare`). */
+  lastSeen: string;
+}
+
+/**
+ * Summarize a cluster by counting items and tracking earliest/latest
+ * timestamps. Timestamp comparison uses `String#localeCompare`, which is
+ * correct for ISO-8601 strings (lexicographic order matches chronological
+ * order).
+ *
+ * - Throws `RangeError` on empty clusters — `firstSeen`/`lastSeen` are not
+ *   meaningful without at least one item.
+ * - When all timestamps are equal, `firstSeen === lastSeen`.
+ */
+export function summarizeCluster<T>(
+  cluster: readonly T[],
+  extractTimestamp: (item: T) => string,
+): ClusterSummary {
+  if (cluster.length === 0) {
+    throw new RangeError("summarizeCluster: cluster must contain at least one item");
+  }
+  let firstSeen = extractTimestamp(cluster[0]);
+  let lastSeen = firstSeen;
+  for (let i = 1; i < cluster.length; i += 1) {
+    const ts = extractTimestamp(cluster[i]);
+    if (ts.localeCompare(firstSeen) < 0) firstSeen = ts;
+    if (ts.localeCompare(lastSeen) > 0) lastSeen = ts;
+  }
+  return { count: cluster.length, firstSeen, lastSeen };
+}