@remnic/core 9.65.2 → 9.65.4

package/src/review/review-deck-http-base.ts

@@ -0,0 +1,133 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { EngramAccessInputError } from "../access-service.js";
+import type { OperationName } from "../access-boundary.js";
+import { SupportPassportAccessHttpBase } from "../support-passport/access-http-base.js";
+import type {
+  ReviewDeckActionRequest,
+  ReviewDeckUndoRequest,
+} from "./review-deck.js";
+
+const LIST_PATHS = ["/remnic/v1/review/deck", "/engram/v1/review/deck"] as const;
+const ACTION_PATHS = ["/remnic/v1/review/deck/action", "/engram/v1/review/deck/action"] as const;
+const UNDO_PATHS = ["/remnic/v1/review/deck/undo", "/engram/v1/review/deck/undo"] as const;
+const LIMIT_MIN = 1;
+const LIMIT_MAX = 100;
+const CURSOR_RE = /^[^\s%]{1,2048}$/;
+
+function requiredString(body: Record<string, unknown>, field: string): string {
+  const value = body[field];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramAccessInputError(`${field} is required`);
+  }
+  return value.trim();
+}
+
+function parseLimit(raw: string | null): number {
+  if (raw === null || raw.length === 0) {
+    throw new EngramAccessInputError("limit is required and must be an integer");
+  }
+  if (!/^(?:0|[1-9]\d*)$/.test(raw)) {
+    throw new EngramAccessInputError("limit must be an integer");
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < LIMIT_MIN || value > LIMIT_MAX) {
+    throw new EngramAccessInputError(`limit must be an integer from ${LIMIT_MIN} to ${LIMIT_MAX}`);
+  }
+  return value;
+}
+
+function parseCursor(raw: string | null): string | undefined {
+  if (raw === null) return undefined;
+  if (!CURSOR_RE.test(raw)) {
+    throw new EngramAccessInputError("cursor is malformed");
+  }
+  return raw;
+}
+
+function parseActionBody(body: Record<string, unknown>): ReviewDeckActionRequest {
+  const action = body.action;
+  if (action !== "keep" && action !== "not_true" && action !== "prepare_fix") {
+    throw new EngramAccessInputError("action must be one of: keep, not_true, prepare_fix");
+  }
+  const itemId = requiredString(body, "itemId");
+  const revision = requiredString(body, "revision");
+  const idempotencyKey = requiredString(body, "idempotencyKey");
+  if (action === "prepare_fix") {
+    const correctionText = requiredString(body, "correctionText");
+    return { schemaVersion: 1, itemId, revision, action, correctionText, idempotencyKey };
+  }
+  return { schemaVersion: 1, itemId, revision, action, idempotencyKey };
+}
+
+function parseUndoBody(body: Record<string, unknown>): ReviewDeckUndoRequest {
+  return {
+    schemaVersion: 1,
+    receiptId: requiredString(body, "receiptId"),
+    expectedRevision: requiredString(body, "expectedRevision"),
+    idempotencyKey: requiredString(body, "idempotencyKey"),
+  };
+}
+
+export abstract class ReviewDeckAccessHttpBase extends SupportPassportAccessHttpBase {
+  protected abstract enforceTokenOp(op: OperationName): void;
+  protected abstract resolveNamespace(req: IncomingMessage, bodyNamespace?: string): string | undefined;
+  protected abstract readonly maxBodyBytes: number;
+
+  protected async handleReviewDeckRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string,
+    abortSignal?: AbortSignal,
+  ): Promise<boolean> {
+    const method = req.method;
+    const isList = method === "GET" && (pathname === LIST_PATHS[0] || pathname === LIST_PATHS[1]);
+    const isAction = method === "POST" && (pathname === ACTION_PATHS[0] || pathname === ACTION_PATHS[1]);
+    const isUndo = method === "POST" && (pathname === UNDO_PATHS[0] || pathname === UNDO_PATHS[1]);
+    if (!isList && !isAction && !isUndo) return false;
+    if (!this.service.reviewDeckEnabled) {
+      this.respondJson(res, 404, { error: "not_found", code: "not_found" });
+      return true;
+    }
+
+    const parsed = new URL(req.url ?? "/", "http://127.0.0.1");
+    const namespace = this.resolveNamespace(req, parsed.searchParams.get("namespace") ?? undefined);
+    const principal = this.resolveRequestPrincipal(req);
+
+    if (isList) {
+      this.enforceTokenOp("review_deck_list");
+      const page = await this.service.reviewDeckList({
+        namespace,
+        principal,
+        cursor: parseCursor(parsed.searchParams.get("cursor")),
+        limit: parseLimit(parsed.searchParams.get("limit")),
+      });
+      this.respondJson(res, 200, page);
+      return true;
+    }
+
+    if (isAction) this.enforceTokenOp("review_deck_action");
+    else this.enforceTokenOp("review_deck_undo");
+    const writeQuota = this.reserveWriteRateLimitSlot(req);
+    try {
+      const body = await this.readJsonBody(req, this.maxBodyBytes);
+      const result = isAction
+        ? await this.service.reviewDeckAction(parseActionBody(body), {
+            namespace,
+            principal,
+            signal: abortSignal,
+          })
+        : await this.service.reviewDeckUndo(parseUndoBody(body), {
+            namespace,
+            principal,
+            signal: abortSignal,
+          });
+      writeQuota.commit();
+      this.respondJson(res, 200, result);
+    } catch (error) {
+      writeQuota.release();
+      throw error;
+    }
+    return true;
+  }
+}

package/src/review/review-deck-mutation.test.ts

@@ -0,0 +1,417 @@
+import assert from "node:assert/strict";
+
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test, { type TestContext } from "node:test";
+import { computeReviewItemRevision } from "./review-deck.js";
+import { readReviewDeckRow } from "./review-deck-snapshot.js";
+import {
+  executeReviewDeckAction,
+  executeReviewDeckUndo,
+  parseReviewLifecycleReceipt,
+  ReviewDeckIdempotencyError,
+  type ReviewDeckMutationContext,
+  type ReviewLifecycleLedgerEvent,
+} from "./review-deck-mutation.js";
+
+async function makeMemoryDir(t: TestContext): Promise<string> {
+  const dir = await mkdtempSafe(t);
+  await mkdir(path.join(dir, "review"), { recursive: true });
+  return dir;
+}
+
+async function mkdtempSafe(t: TestContext): Promise<string> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "remnic-review-deck-"));
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+function reviewMarkdown(id: string, extra = ""): string {
+  return `---
+id: ${id}
+category: fact
+confidence: 0.4
+confidenceTier: low
+source: test
+created: 2026-05-17T00:00:00.000Z
+reviewReason: low_confidence
+lifecycleState: pending_review
+status: pending_review
+${extra}---
+Candidate memory.
+`;
+}
+
+function makeCtx(
+  memoryDir: string,
+  events: unknown[],
+  extras: Partial<ReviewDeckMutationContext> = {},
+): ReviewDeckMutationContext {
+  return {
+    memoryDir,
+    namespace: "ns-test",
+    principalDigest: "prin-test",
+    async appendLifecycleEvents(next) {
+      events.push(...next);
+    },
+    async readLifecycleEvents(memoryId) {
+      if (!memoryId) return events;
+      return events.filter((row) => {
+        if (!row || typeof row !== "object" || !("memoryId" in row)) return false;
+        return row.memoryId === memoryId;
+      });
+    },
+    ...extras,
+  };
+}
+
+async function writeQueueItem(
+  memoryDir: string,
+  id: string,
+  extra = "",
+): Promise<{ filePath: string; content: string; revision: string }> {
+  const filePath = path.join(memoryDir, "review", `${id}.md`);
+  const content = reviewMarkdown(id, extra);
+  await writeFile(filePath, content, "utf8");
+  const row = readReviewDeckRow({ memoryDir, itemId: id });
+  assert.ok(row, `expected pending review row ${id}`);
+  return { filePath, content, revision: row.revision };
+}
+
+function ledgerEvent(value: unknown): ReviewLifecycleLedgerEvent {
+  if (!value || typeof value !== "object") throw new Error("expected lifecycle event");
+  // Test ledger rows are objects this suite appended.
+  return value as ReviewLifecycleLedgerEvent;
+}
+
+function todayStamp(): string {
+  return new Date().toISOString().split("T")[0];
+}
+
+test("keep promotes through performReview and fires tombstone revocation", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const hookCalls: Array<[string, string]> = [];
+  const item = await writeQueueItem(memoryDir, "keep-blocked", "blockedBy: tomb-1\n");
+  const ctx = makeCtx(memoryDir, events, {
+    onApproveBlockedMemory(tombstoneId, memoryId) {
+      hookCalls.push([tombstoneId, memoryId]);
+    },
+  });
+
+  const receipt = await executeReviewDeckAction(ctx, {
+    schemaVersion: 1,
+    itemId: "keep-blocked",
+    revision: item.revision,
+    action: "keep",
+    idempotencyKey: "keep-1",
+  });
+
+  assert.equal(receipt.outcome, "applied");
+  assert.equal(receipt.action, "keep");
+  assert.equal(receipt.undoAvailable, true);
+  assert.match(receipt.effect, /recalled/);
+  assert.deepEqual(hookCalls, [["tomb-1", "keep-blocked"]]);
+  await assert.rejects(stat(item.filePath), /ENOENT/);
+  const promoted = path.join(memoryDir, "facts", todayStamp(), "keep-blocked.md");
+  const promotedText = await readFile(promoted, "utf8");
+  assert.match(promotedText, /confidence: 0\.9/);
+  const row = ledgerEvent(events[0]);
+  assert.equal(row.eventType, "promoted");
+  assert.equal(row.actor, "admin-console.review-deck");
+  assert.equal(row.reviewReceipt?.action, "approve");
+});
+
+test("not true dismisses a queue item", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "dismiss-1");
+  const receipt = await executeReviewDeckAction(makeCtx(memoryDir, events), {
+    schemaVersion: 1,
+    itemId: "dismiss-1",
+    revision: item.revision,
+    action: "not_true",
+    idempotencyKey: "dismiss-1",
+  });
+
+  assert.equal(receipt.outcome, "applied");
+  assert.equal(receipt.action, "not_true");
+  assert.equal(receipt.undoAvailable, true);
+  assert.equal(typeof receipt.appliedRevision, "string");
+  await assert.rejects(stat(item.filePath), /ENOENT/);
+  const row = ledgerEvent(events[0]);
+  assert.equal(row.eventType, "rejected");
+  assert.equal(row.reviewReceipt?.action, "dismiss");
+  const undone = await executeReviewDeckUndo(makeCtx(memoryDir, events), {
+    schemaVersion: 1,
+    receiptId: receipt.receiptId,
+    expectedRevision: receipt.appliedRevision ?? "",
+    idempotencyKey: "dismiss-1-undo",
+  });
+  assert.equal(undone.outcome, "applied");
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+});
+
+test("stale revision returns conflict with no file change", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "stale-1");
+  const receipt = await executeReviewDeckAction(makeCtx(memoryDir, events), {
+    schemaVersion: 1,
+    itemId: "stale-1",
+    revision: "rv1:deadbeef",
+    action: "keep",
+    idempotencyKey: "stale-1",
+  });
+
+  assert.equal(receipt.outcome, "conflict");
+  assert.equal(receipt.appliedRevision, item.revision);
+  assert.equal(receipt.undoAvailable, false);
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+  assert.equal(events.length, 0);
+});
+
+test("duplicate idempotency key returns the saved receipt and does not apply twice", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "idemp-1");
+  const ctx = makeCtx(memoryDir, events);
+  const req = {
+    schemaVersion: 1 as const,
+    itemId: "idemp-1",
+    revision: item.revision,
+    action: "keep" as const,
+    idempotencyKey: "same-key",
+  };
+  const first = await executeReviewDeckAction(ctx, req);
+  const second = await executeReviewDeckAction(ctx, req);
+
+  assert.equal(first.outcome, "applied");
+  assert.equal(second.receiptId, first.receiptId);
+  assert.equal(second.outcome, first.outcome);
+  assert.equal(second.effect, first.effect);
+  assert.equal(events.length, 1);
+  const promoted = path.join(memoryDir, "facts", todayStamp(), "idemp-1.md");
+  assert.equal(computeReviewItemRevision(await readFile(promoted, "utf8")), first.appliedRevision);
+});
+
+test("same key with a different fingerprint is rejected", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const firstItem = await writeQueueItem(memoryDir, "fp-a");
+  await writeQueueItem(memoryDir, "fp-b");
+  const ctx = makeCtx(memoryDir, events);
+  await executeReviewDeckAction(ctx, {
+    schemaVersion: 1,
+    itemId: "fp-a",
+    revision: firstItem.revision,
+    action: "keep",
+    idempotencyKey: "shared-key",
+  });
+
+  await assert.rejects(
+    () =>
+      executeReviewDeckAction(ctx, {
+        schemaVersion: 1,
+        itemId: "fp-b",
+        revision: computeReviewItemRevision(fs.readFileSync(path.join(memoryDir, "review", "fp-b.md"), "utf8")),
+        action: "keep",
+        idempotencyKey: "shared-key",
+      }),
+    ReviewDeckIdempotencyError,
+  );
+  assert.ok(fs.existsSync(path.join(memoryDir, "review", "fp-b.md")));
+});
+
+test("prepare_fix returns a plan id and writes no lifecycle event and no file change", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "fix-1");
+  const receipt = await executeReviewDeckAction(
+    makeCtx(memoryDir, events, {
+      async planCorrection(input) {
+        return { planId: "plan-fix-1", preview: { itemId: input.itemId } };
+      },
+    }),
+    {
+      schemaVersion: 1,
+      itemId: "fix-1",
+      revision: item.revision,
+      action: "prepare_fix",
+      correctionText: "Replace the guessed preference.",
+      idempotencyKey: "fix-1",
+    },
+  );
+
+  assert.equal(receipt.outcome, "planned");
+  assert.equal(receipt.correctionPlanId, "plan-fix-1");
+  assert.deepEqual(receipt.correctionPreview, { itemId: "fix-1" });
+  assert.equal(receipt.undoAvailable, false);
+  assert.equal(events.length, 0);
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+});
+
+test("abort before the write leaves the file untouched", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "abort-1");
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(
+    () =>
+      executeReviewDeckAction(makeCtx(memoryDir, events, { signal: controller.signal }), {
+        schemaVersion: 1,
+        itemId: "abort-1",
+        revision: item.revision,
+        action: "keep",
+        idempotencyKey: "abort-1",
+      }),
+    (err: Error) => err.name === "AbortError",
+  );
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+  assert.equal(events.length, 0);
+});
+
+test("undo succeeds with no intervening change", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "undo-ok");
+  const ctx = makeCtx(memoryDir, events);
+  const kept = await executeReviewDeckAction(ctx, {
+    schemaVersion: 1,
+    itemId: "undo-ok",
+    revision: item.revision,
+    action: "keep",
+    idempotencyKey: "undo-ok",
+  });
+  const undone = await executeReviewDeckUndo(ctx, {
+    schemaVersion: 1,
+    receiptId: kept.receiptId,
+    expectedRevision: kept.appliedRevision ?? "",
+    idempotencyKey: "undo-ok-revert",
+  });
+
+  assert.equal(undone.outcome, "applied");
+  assert.equal(undone.action, "undo");
+  assert.equal(undone.undoAvailable, false);
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+  await assert.rejects(stat(path.join(memoryDir, "facts", todayStamp(), "undo-ok.md")), /ENOENT/);
+  const restored = ledgerEvent(events.at(-1));
+  assert.equal(restored.eventType, "restored");
+  assert.equal(restored.reviewReceipt?.undoOfReceiptId, kept.receiptId);
+});
+
+test("undo after an intervening revision change returns conflict and leaves the memory unchanged", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [];
+  const item = await writeQueueItem(memoryDir, "undo-conflict");
+  const ctx = makeCtx(memoryDir, events);
+  const kept = await executeReviewDeckAction(ctx, {
+    schemaVersion: 1,
+    itemId: "undo-conflict",
+    revision: item.revision,
+    action: "keep",
+    idempotencyKey: "undo-conflict",
+  });
+  const promoted = path.join(memoryDir, "facts", todayStamp(), "undo-conflict.md");
+  const edited = `${await readFile(promoted, "utf8")}\nEdited after keep.\n`;
+  await writeFile(promoted, edited, "utf8");
+
+  const undone = await executeReviewDeckUndo(ctx, {
+    schemaVersion: 1,
+    receiptId: kept.receiptId,
+    expectedRevision: kept.appliedRevision ?? "",
+    idempotencyKey: "undo-conflict-revert",
+  });
+
+  assert.equal(undone.outcome, "conflict");
+  assert.equal(await readFile(promoted, "utf8"), edited);
+  await assert.rejects(stat(item.filePath), /ENOENT/);
+});
+
+test("a corrupt receipt payload fails closed", async (t) => {
+  const memoryDir = await makeMemoryDir(t);
+  const events: unknown[] = [
+    {
+      eventId: "mle-corrupt",
+      memoryId: "ghost",
+      eventType: "promoted",
+      timestamp: "2026-05-17T00:00:00.000Z",
+      actor: "admin-console.review-deck",
+      ruleVersion: "admin-console.review-deck.v1",
+      reviewReceipt: {
+        schemaVersion: 1,
+        receiptId: "rcp1:corrupt",
+        requestFingerprint: "rfp1:x",
+        principalDigest: 12,
+        itemId: "ghost",
+        action: "approve",
+        beforeRevision: "rv1:a",
+        afterRevision: "rv1:b",
+        sourcePath: "review/ghost.md",
+      },
+    },
+  ];
+  const item = await writeQueueItem(memoryDir, "ghost");
+  const undone = await executeReviewDeckUndo(makeCtx(memoryDir, events), {
+    schemaVersion: 1,
+    receiptId: "rcp1:corrupt",
+    expectedRevision: "rv1:b",
+    idempotencyKey: "corrupt-undo",
+  });
+  assert.equal(undone.outcome, "failed");
+  assert.equal(undone.itemId, "");
+  assert.equal(await readFile(item.filePath, "utf8"), item.content);
+  assert.equal(parseReviewLifecycleReceipt(ledgerEvent(events[0]).reviewReceipt), null);
+});
+
+test("parseReviewLifecycleReceipt rejects invalid fields", () => {
+  assert.equal(parseReviewLifecycleReceipt(null), null);
+  assert.equal(parseReviewLifecycleReceipt("nope"), null);
+  assert.equal(
+    parseReviewLifecycleReceipt({
+      schemaVersion: 2,
+      receiptId: "rcp1:x",
+      requestFingerprint: "rfp1:x",
+      principalDigest: "p",
+      itemId: "i",
+      action: "approve",
+      beforeRevision: "a",
+      afterRevision: "b",
+      sourcePath: "review/x.md",
+    }),
+    null,
+  );
+  assert.equal(
+    parseReviewLifecycleReceipt({
+      schemaVersion: 1,
+      receiptId: "rcp1:x",
+      requestFingerprint: "rfp1:x",
+      principalDigest: "p",
+      itemId: "i",
+      action: "approve",
+      beforeRevision: "a",
+      afterRevision: "b",
+      sourcePath: "/abs/review/x.md",
+    }),
+    null,
+  );
+  const ok = parseReviewLifecycleReceipt({
+    schemaVersion: 1,
+    receiptId: "rcp1:x",
+    requestFingerprint: "rfp1:x",
+    principalDigest: "p",
+    itemId: "i",
+    action: "dismiss",
+    beforeRevision: "a",
+    afterRevision: "",
+    sourcePath: "review/x.md",
+    extra: "ignored",
+  });
+  assert.ok(ok);
+  assert.equal(ok?.action, "dismiss");
+  assert.equal(ok?.afterRevision, "");
+});
+