feat(memory-diag): add memory command detail

2026-07-17 12:56:42 +02:00 · 2026-05-14 09:29:55 +08:00
parent 3c4282b241
commit 93550b2e41
4 changed files with 404 additions and 2 deletions
@@ -9,7 +9,7 @@ export function usage(): string {
  memory-diag rejected [--workspace <path>] [--verbose] [--json]
  memory-diag missing [--workspace <path>] [--verbose] [--json]
  memory-diag explain [memory-id] [--workspace <path>] [--raw]
-  memory-diag commands [--workspace <path>] [--verbose] [--json]
+  memory-diag commands [--workspace <path>] [--verbose] [--json] [--memory <id>]
  memory-diag quality [--workspace <path>] [--verbose] [--json] [--raw] [--no-emoji]
  memory-diag revert (--memory <replacement-id> | --event <event-id>) [--workspace <path>] [--apply]

@@ -121,7 +121,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
  if (command !== "audit" && options.migration) {
    return error(`${command} does not accept --migration`);
  }
-  if (command !== "explain" && command !== "revert" && options.memory) {
+  if (command !== "explain" && command !== "revert" && command !== "commands" && options.memory) {
    return error(`${command} does not accept --memory`);
  }
  if (command !== "revert" && options.event) return error(`${command} does not accept --event`);
@@ -1,6 +1,11 @@
 import { queryEvidenceEvents, type EvidenceEventV1, type EvidenceOutcome } from "../../../src/evidence-log.ts";
+import { workspaceKey, workspaceMemoryPath } from "../../../src/paths.ts";
+import type { WorkspaceMemoryStore } from "../../../src/types.ts";
+import { accountWorkspaceMemoryRender } from "../../../src/workspace-memory.ts";
+import { readJSONFile } from "../io.ts";
 import { objectFromCounts, sortedCounts } from "../text.ts";
 import type { CliOptions, CommandResult } from "../types.ts";
+import { normalizedStore } from "../workspace-snapshot.ts";

 type CommandKind = "reinforce" | "replace";

@@ -33,6 +38,42 @@ type MemoryCommandSummary = {
  }>;
 };

+type MemoryCommandDetail = {
+  version: 1;
+  generatedAt: string;
+  memoryId: string;
+  current: {
+    present: boolean;
+    status?: string;
+    renderStatus?: "rendered" | "not_rendered" | "unknown";
+    type?: string;
+    source?: string;
+  };
+  summary: {
+    attempts: number;
+    reinforced: number;
+    rejectedOrBlocked: number;
+    windowBlocked: number;
+    blocksByReason: Record<string, number>;
+    blockDetailsMissing: number;
+    refs: string[];
+    sameSessionCrossUtcDayBlocks: number;
+  };
+  events: Array<{
+    eventId: string;
+    createdAt: string;
+    outcome: EvidenceOutcome;
+    ref?: string;
+    blockReason?: string;
+    reasonCodes: string[];
+    attemptedAtIso?: string;
+    lastReinforcedAtIso?: string;
+    crossUtcDay?: boolean | "unknown";
+    producerVersion?: string;
+    instrumentationVersion?: number;
+  }>;
+};
+
 const INVALID_COMMAND_REASONS = new Set([
  "invalid_memory_command",
  "invalid_memory_ref",
@@ -66,6 +107,124 @@ function refFromEvent(event: EvidenceEventV1): string | undefined {
  return typeof ref === "string" ? ref : undefined;
 }

+function isReinforcementEvent(event: EvidenceEventV1): boolean {
+  return event.type === "memory_reinforced";
+}
+
+function stringDetail(event: EvidenceEventV1, key: string): string | undefined {
+  const value = event.details?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function isRejectedOrBlocked(event: EvidenceEventV1): boolean {
+  return event.outcome === "rejected" || hasReason(event, "reinforcement_window_blocked");
+}
+
+function blockReasonFor(event: EvidenceEventV1): string | undefined {
+  if (!isRejectedOrBlocked(event)) return undefined;
+  return stringDetail(event, "blockReason") ?? "unknown";
+}
+
+function isCrossUtcDay(attemptedAtIso: string | undefined, lastReinforcedAtIso: string | undefined): boolean | "unknown" {
+  if (!attemptedAtIso || !lastReinforcedAtIso) return "unknown";
+  const attempted = new Date(attemptedAtIso);
+  const lastReinforced = new Date(lastReinforcedAtIso);
+  if (Number.isNaN(attempted.getTime()) || Number.isNaN(lastReinforced.getTime())) return "unknown";
+  return attempted.toISOString().slice(0, 10) !== lastReinforced.toISOString().slice(0, 10);
+}
+
+async function currentMemoryStatus(root: string, memoryId: string): Promise<MemoryCommandDetail["current"]> {
+  const rawStore = await readJSONFile<WorkspaceMemoryStore>(await workspaceMemoryPath(root));
+  const storeRoot = rawStore?.workspace?.root ?? root;
+  const storeKey = rawStore?.workspace?.key ?? await workspaceKey(root);
+  const store = normalizedStore(rawStore, storeRoot, storeKey);
+  const activeEntry = store.entries.find(entry => entry.id === memoryId && entry.status !== "superseded");
+  const renderAccounting = accountWorkspaceMemoryRender(store);
+  const renderedIds = new Set(renderAccounting.rendered.map(memory => memory.id));
+  const omittedIds = new Set(renderAccounting.omitted.map(item => item.memory.id));
+  const renderStatus = renderedIds.has(memoryId)
+    ? "rendered"
+    : omittedIds.has(memoryId)
+      ? "not_rendered"
+      : "unknown";
+
+  if (!activeEntry) {
+    return { present: false, renderStatus };
+  }
+
+  return {
+    present: true,
+    status: activeEntry.status,
+    renderStatus,
+    type: activeEntry.type,
+    source: activeEntry.source,
+  };
+}
+
+function detailEventJSON(event: EvidenceEventV1): MemoryCommandDetail["events"][number] {
+  const attemptedAtIso = stringDetail(event, "attemptedAtIso");
+  const lastReinforcedAtIso = stringDetail(event, "lastReinforcedAtIso");
+  const blocked = isRejectedOrBlocked(event);
+  const blockReason = blockReasonFor(event);
+  return {
+    eventId: event.eventId,
+    createdAt: event.createdAt,
+    outcome: event.outcome,
+    ref: refFromEvent(event),
+    blockReason,
+    reasonCodes: event.reasonCodes,
+    attemptedAtIso,
+    lastReinforcedAtIso,
+    crossUtcDay: blocked ? isCrossUtcDay(attemptedAtIso, lastReinforcedAtIso) : undefined,
+    producerVersion: event.producerVersion,
+    instrumentationVersion: event.instrumentationVersion,
+  };
+}
+
+export async function buildMemoryCommandDetail(
+  root: string,
+  memoryId: string,
+  events: EvidenceEventV1[],
+  generatedAt = new Date().toISOString(),
+): Promise<MemoryCommandDetail> {
+  const reinforcementEvents = events.filter(isReinforcementEvent);
+  const blockReasonCounts = new Map<string, number>();
+  const refs = new Set<string>();
+  let blockDetailsMissing = 0;
+  let sameSessionCrossUtcDayBlocks = 0;
+
+  for (const event of reinforcementEvents) {
+    const ref = refFromEvent(event);
+    if (ref) refs.add(ref);
+    if (!isRejectedOrBlocked(event)) continue;
+
+    const blockReason = blockReasonFor(event) ?? "unknown";
+    blockReasonCounts.set(blockReason, (blockReasonCounts.get(blockReason) ?? 0) + 1);
+    if (!stringDetail(event, "blockReason")) blockDetailsMissing += 1;
+    if (blockReason === "same_session" && isCrossUtcDay(stringDetail(event, "attemptedAtIso"), stringDetail(event, "lastReinforcedAtIso")) === true) {
+      sameSessionCrossUtcDayBlocks += 1;
+    }
+  }
+
+  return {
+    version: 1,
+    generatedAt,
+    memoryId,
+    current: await currentMemoryStatus(root, memoryId),
+    summary: {
+      attempts: reinforcementEvents.length,
+      reinforced: reinforcementEvents.filter(event => event.outcome === "reinforced").length,
+      rejectedOrBlocked: reinforcementEvents.filter(isRejectedOrBlocked).length,
+      windowBlocked: reinforcementEvents.filter(event => hasReason(event, "reinforcement_window_blocked")).length,
+      blocksByReason: objectFromCounts(blockReasonCounts),
+      blockDetailsMissing,
+      refs: [...refs].sort(),
+      sameSessionCrossUtcDayBlocks,
+    },
+    events: reinforcementEvents.map(detailEventJSON),
+  };
+}
+
 function latestEventJSON(event: EvidenceEventV1): MemoryCommandSummary["latestEvents"][number] {
  return {
    eventId: event.eventId,
@@ -145,6 +304,73 @@ function formatLatestEvents(events: MemoryCommandSummary["latestEvents"]): strin
  });
 }

+function formatInlineCounts(counts: Record<string, number>): string {
+  const rows = sortedCounts(new Map(Object.entries(counts)));
+  return rows.length > 0 ? rows.map(([reason, count]) => `${reason}=${count}`).join(", ") : "(none)";
+}
+
+function formatCrossUtcDay(value: boolean | "unknown" | undefined): string {
+  if (value === true) return "yes";
+  if (value === false) return "no";
+  return "unknown";
+}
+
+function formatMemoryCommandDetailEvents(events: MemoryCommandDetail["events"]): string[] {
+  if (events.length === 0) return ["  (none)"];
+  return events.map(event => {
+    const ref = event.ref ? ` ref=${event.ref}` : "";
+    const blockReason = event.blockReason ? ` blockReason=${event.blockReason}` : "";
+    const attemptedAt = event.attemptedAtIso ? ` attemptedAt=${event.attemptedAtIso}` : "";
+    const lastReinforcedAt = event.lastReinforcedAtIso ? ` lastReinforcedAt=${event.lastReinforcedAtIso}` : "";
+    const crossUtcDay = event.crossUtcDay !== undefined ? ` crossUtcDay=${formatCrossUtcDay(event.crossUtcDay)}` : "";
+    return `  - ${event.createdAt} outcome=${event.outcome}${ref}${blockReason}${attemptedAt}${lastReinforcedAt}${crossUtcDay} reasons=${event.reasonCodes.join(",") || "none"}`;
+  });
+}
+
+export function formatMemoryCommandDetail(detail: MemoryCommandDetail, options: Pick<CliOptions, "verbose"> = {}): string {
+  const current = detail.current;
+  const lines = [
+    `Memory command diagnostics for ${detail.memoryId}`,
+    "",
+    "Current memory:",
+    `  - present: ${current.present ? "yes" : "no"}`,
+    `  - status: ${current.status ?? "unknown"}`,
+    `  - render: ${current.renderStatus ?? "unknown"}`,
+  ];
+
+  if (current.type) lines.push(`  - type: ${current.type}`);
+  if (current.source) lines.push(`  - source: ${current.source}`);
+
+  lines.push("");
+  if (detail.summary.attempts === 0) {
+    lines.push(`No reinforcement command evidence found for ${detail.memoryId}.`);
+    return lines.join("\n");
+  }
+
+  lines.push(
+    "Reinforcement summary:",
+    `  - attempts: ${detail.summary.attempts}`,
+    `  - reinforced: ${detail.summary.reinforced}`,
+    `  - rejected/blocked: ${detail.summary.rejectedOrBlocked}`,
+    `  - window blocked: ${detail.summary.windowBlocked}`,
+    `  - block reasons: ${formatInlineCounts(detail.summary.blocksByReason)}`,
+    `  - block details missing: ${detail.summary.blockDetailsMissing}`,
+    `  - same-session cross UTC day blocks: ${detail.summary.sameSessionCrossUtcDayBlocks}`,
+    `  - refs: ${detail.summary.refs.length > 0 ? detail.summary.refs.join(", ") : "(none)"}`,
+    "",
+  );
+
+  const eventRows = options.verbose ? detail.events : detail.events.slice(-10).reverse();
+  if (!options.verbose && detail.events.length > eventRows.length) {
+    lines.push(`Latest reinforcement events (showing ${eventRows.length} of ${detail.events.length}):`);
+  } else {
+    lines.push("Latest reinforcement events:");
+  }
+  lines.push(...formatMemoryCommandDetailEvents(eventRows));
+
+  return lines.join("\n");
+}
+
 export function formatMemoryCommandSummary(summary: MemoryCommandSummary, options: Pick<CliOptions, "verbose" | "noEmoji"> = {}): string {
  const warning = options.noEmoji ? "!" : "⚠";
  const lines = [
@@ -176,6 +402,17 @@ export function formatMemoryCommandSummary(summary: MemoryCommandSummary, option

 export async function runCommands(options: CliOptions): Promise<CommandResult> {
  const root = options.workspace ?? process.cwd();
+  if (options.memory) {
+    const events = await queryEvidenceEvents(root, { memoryId: options.memory });
+    const detail = await buildMemoryCommandDetail(root, options.memory, events);
+
+    if (options.json) {
+      return { stdout: JSON.stringify(detail, null, 2) };
+    }
+
+    return { stdout: formatMemoryCommandDetail(detail, options) };
+  }
+
  const events = await queryEvidenceEvents(root);
  const summary = buildMemoryCommandSummary(events);