@remnic/core 9.65.1 → 9.65.3

package/src/procedural/procedure-stats.ts

@@ -12,6 +12,8 @@
  */
 import type { MemoryFile, MemoryStatus, PluginConfig } from "../types.js";
 import type { StorageManager } from "../storage.js";
+import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { readProcedureMaintenanceMarker } from "./library-maintenance.js";
 
 export interface ProcedureStatusCounts {
   total: number;
@@ -50,6 +52,10 @@ export interface ProcedureStatsReport {
   counts: ProcedureStatusCounts;
   recent: ProcedureStatsRecent;
   config: ProcedureStatsConfigSnapshot;
+  /** ISO timestamp of the last library-maintenance run marker, or null (issue #2370). */
+  lastMaintenanceAt: string | null;
+  /** Active procedures currently carrying a `needsRepair` flag (issue #2370). */
+  needsRepairFlags: number;
 }
 
 function snapshotConfig(config: PluginConfig): ProcedureStatsConfigSnapshot {
@@ -102,6 +108,7 @@ export async function computeProcedureStats(options: {
   let lastWriteMs: number | null = null;
   let writesLast7Days = 0;
   let minerSourced = 0;
+  let needsRepairFlags = 0;
 
   const known: MemoryStatus[] = [
     "active",
@@ -159,8 +166,15 @@ export async function computeProcedureStats(options: {
     if (m.frontmatter.source === "procedure-miner") {
       minerSourced += 1;
     }
+    if (
+      m.frontmatter.structuredAttributes?.needsRepair !== undefined &&
+      isActiveMemoryStatus(m.frontmatter.status)
+    ) {
+      needsRepairFlags += 1;
+    }
   }
 
+  const maintenanceMarker = await readProcedureMaintenanceMarker(storage.dir);
   return {
     schemaVersion: 1,
     generatedAt: new Date(nowMs).toISOString(),
@@ -171,6 +185,8 @@ export async function computeProcedureStats(options: {
       minerSourced,
     },
     config: snapshotConfig(config),
+    lastMaintenanceAt: maintenanceMarker?.lastRunAt ?? null,
+    needsRepairFlags,
   };
 }
 
@@ -210,5 +226,9 @@ export function formatProcedureStatsText(report: ProcedureStatsReport): string {
   lines.push(`    lastWriteAt:      ${recent.lastWriteAt ?? "(none)"}`);
   lines.push(`    writesLast7Days:  ${recent.writesLast7Days}`);
   lines.push(`    minerSourced:     ${recent.minerSourced}`);
+  lines.push("");
+  lines.push(`  maintenance:`);
+  lines.push(`    lastMaintenanceAt: ${report.lastMaintenanceAt ?? "(never)"}`);
+  lines.push(`    needsRepairFlags:  ${report.needsRepairFlags}`);
   return lines.join("\n") + "\n";
 }

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

@@ -0,0 +1,325 @@
+import assert from "node:assert/strict";
+import { request as httpRequest } from "node:http";
+import test from "node:test";
+
+import { EngramAccessHttpServer } from "../access-http.js";
+import type { EngramAccessService } from "../access-service.js";
+import type {
+  ReviewDeckActionReceipt,
+  ReviewDeckActionRequest,
+  ReviewDeckPage,
+  ReviewDeckUndoRequest,
+} from "./review-deck.js";
+
+const TOKEN = "test-token";
+
+function deferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function page(): ReviewDeckPage {
+  return { schemaVersion: 1, items: [], total: 0 };
+}
+
+function receipt(
+  action: ReviewDeckActionReceipt["action"] = "keep",
+): ReviewDeckActionReceipt {
+  return {
+    schemaVersion: 1,
+    receiptId: "receipt-1",
+    itemId: "item-1",
+    action,
+    outcome: "applied",
+    effect: action,
+    undoAvailable: action !== "undo",
+  };
+}
+
+function mockService(overrides: Partial<EngramAccessService> = {}): EngramAccessService {
+  return {
+    reviewDeckEnabled: true,
+    reviewDeckList: async () => page(),
+    reviewDeckAction: async () => receipt("keep"),
+    reviewDeckUndo: async () => receipt("undo"),
+    reviewQueue: async () => ({ found: true, runId: "existing-review" }),
+    ...overrides,
+  } as unknown as EngramAccessService;
+}
+
+async function startServer(
+  service: EngramAccessService,
+  extras: ConstructorParameters<typeof EngramAccessHttpServer>[0] extends infer T
+    ? T extends { service: EngramAccessService }
+      ? Omit<T, "service" | "port" | "adminConsoleEnabled">
+      : never
+    : never = { authToken: TOKEN },
+): Promise<{ port: number; stop: () => Promise<void> }> {
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    adminConsoleEnabled: false,
+    ...extras,
+  });
+  const status = await server.start();
+  return { port: status.port, stop: () => server.stop() };
+}
+
+async function jsonRequest(
+  port: number,
+  path: string,
+  options: {
+    method?: string;
+    token?: string;
+    body?: unknown;
+  } = {},
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+    method: options.method ?? "GET",
+    headers: {
+      authorization: `Bearer ${options.token ?? TOKEN}`,
+      ...(options.body !== undefined ? { "content-type": "application/json" } : {}),
+    },
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+const keepBody: ReviewDeckActionRequest = {
+  schemaVersion: 1,
+  itemId: "item-1",
+  revision: "rv1:abc",
+  action: "keep",
+  idempotencyKey: "key-1",
+};
+
+const undoBody: ReviewDeckUndoRequest = {
+  schemaVersion: 1,
+  receiptId: "receipt-1",
+  expectedRevision: "rv1:abc",
+  idempotencyKey: "key-undo",
+};
+
+test("canonical and engram alias list routes return schemaVersion 1", async () => {
+  const { port, stop } = await startServer(mockService());
+  try {
+    for (const prefix of ["/remnic/v1", "/engram/v1"] as const) {
+      const listed = await jsonRequest(port, `${prefix}/review/deck?limit=1`);
+      assert.equal(listed.status, 200);
+      assert.equal(listed.body.schemaVersion, 1);
+      const acted = await jsonRequest(port, `${prefix}/review/deck/action`, {
+        method: "POST",
+        body: keepBody,
+      });
+      assert.equal(acted.status, 200);
+      assert.equal(acted.body.schemaVersion, 1);
+      const undone = await jsonRequest(port, `${prefix}/review/deck/undo`, {
+        method: "POST",
+        body: undoBody,
+      });
+      assert.equal(undone.status, 200);
+      assert.equal(undone.body.schemaVersion, 1);
+    }
+  } finally {
+    await stop();
+  }
+});
+
+test("invalid cursor, limit, action, revision, and missing idempotency key are client errors", async () => {
+  const { port, stop } = await startServer(mockService());
+  try {
+    const cases: Array<{ path: string; method?: string; body?: unknown; message: RegExp }> = [
+      { path: "/engram/v1/review/deck?limit=1&cursor=%%%", message: /cursor is malformed/ },
+      { path: "/engram/v1/review/deck", message: /limit is required/ },
+      { path: "/engram/v1/review/deck?limit=abc", message: /limit must be an integer/ },
+      { path: "/engram/v1/review/deck?limit=0", message: /limit must be an integer from 1 to 100/ },
+      { path: "/engram/v1/review/deck?limit=101", message: /limit must be an integer from 1 to 100/ },
+      {
+        path: "/engram/v1/review/deck/action",
+        method: "POST",
+        body: { ...keepBody, action: "later" },
+        message: /action must be one of/,
+      },
+      {
+        path: "/engram/v1/review/deck/action",
+        method: "POST",
+        body: { ...keepBody, revision: "" },
+        message: /revision is required/,
+      },
+      {
+        path: "/engram/v1/review/deck/action",
+        method: "POST",
+        body: { ...keepBody, idempotencyKey: undefined },
+        message: /idempotencyKey is required/,
+      },
+      {
+        path: "/engram/v1/review/deck/action",
+        method: "POST",
+        body: { ...keepBody, action: "prepare_fix", correctionText: "   " },
+        message: /correctionText is required/,
+      },
+    ];
+    for (const item of cases) {
+      const result = await jsonRequest(port, item.path, { method: item.method, body: item.body });
+      assert.equal(result.status, 400, item.path);
+      assert.match(String(result.body.error), item.message);
+    }
+  } finally {
+    await stop();
+  }
+});
+
+test("POST body principal and namespace are ignored in favor of the boundary", async () => {
+  let seen: { namespace?: string; principal?: string } | undefined;
+  const { port, stop } = await startServer(
+    mockService({
+      reviewDeckAction: async (_req, opts) => {
+        seen = { namespace: opts.namespace, principal: opts.principal };
+        return receipt("keep");
+      },
+    }),
+    { authToken: TOKEN, principal: "boundary-principal" },
+  );
+  try {
+    const result = await jsonRequest(
+      port,
+      "/engram/v1/review/deck/action?namespace=boundary-ns",
+      {
+        method: "POST",
+        body: {
+          ...keepBody,
+          namespace: "body-ns",
+          principal: "body-principal",
+        },
+      },
+    );
+    assert.equal(result.status, 200);
+    assert.deepEqual(seen, { namespace: "boundary-ns", principal: "boundary-principal" });
+  } finally {
+    await stop();
+  }
+});
+
+test("a read-only token cannot call action or undo", async () => {
+  const { port, stop } = await startServer(mockService(), {
+    authTokenEntriesGetter: () => [
+      { token: "reader", capabilities: { version: 1, ops: ["review_deck_list"] } },
+    ],
+  });
+  try {
+    const listed = await jsonRequest(port, "/engram/v1/review/deck?limit=1", { token: "reader" });
+    assert.equal(listed.status, 200);
+    const acted = await jsonRequest(port, "/engram/v1/review/deck/action", {
+      method: "POST",
+      token: "reader",
+      body: keepBody,
+    });
+    assert.equal(acted.status, 403);
+    const undone = await jsonRequest(port, "/engram/v1/review/deck/undo", {
+      method: "POST",
+      token: "reader",
+      body: undoBody,
+    });
+    assert.equal(undone.status, 403);
+  } finally {
+    await stop();
+  }
+});
+
+test("disabled gate returns 404 for deck routes while review-queue still works", async () => {
+  let queueCalled = false;
+  let deckCalled = false;
+  const { port, stop } = await startServer(
+    mockService({
+      reviewDeckEnabled: false,
+      reviewDeckList: async () => {
+        deckCalled = true;
+        return page();
+      },
+      reviewQueue: async () => {
+        queueCalled = true;
+        return { found: true, runId: "existing-review" };
+      },
+    }),
+  );
+  try {
+    for (const path of [
+      "/engram/v1/review/deck?limit=1",
+      "/remnic/v1/review/deck?limit=1",
+      "/engram/v1/review/deck/action",
+      "/remnic/v1/review/deck/undo",
+    ]) {
+      const method = path.includes("/action") || path.includes("/undo") ? "POST" : "GET";
+      const result = await jsonRequest(port, path, {
+        method,
+        body: method === "POST" ? keepBody : undefined,
+      });
+      assert.equal(result.status, 404, path);
+      assert.equal(result.body.code, "not_found");
+    }
+    assert.equal(deckCalled, false);
+    const queue = await jsonRequest(port, "/engram/v1/review-queue");
+    assert.equal(queue.status, 200);
+    assert.equal(queueCalled, true);
+  } finally {
+    await stop();
+  }
+});
+
+test("cancellation reaches the deck action executor", async () => {
+  const started = deferred<void>();
+  const settled = deferred<void>();
+  const forceRelease = deferred<void>();
+  let observed: AbortSignal | undefined;
+  const { port, stop } = await startServer(
+    mockService({
+      reviewDeckAction: async (_req, opts) => {
+        observed = opts.signal;
+        started.resolve();
+        try {
+          await Promise.race([
+            forceRelease.promise,
+            new Promise<void>((_resolve, reject) => {
+              opts.signal?.addEventListener("abort", () => reject(opts.signal?.reason), { once: true });
+            }),
+          ]);
+        } finally {
+          settled.resolve();
+        }
+        if (opts.signal?.aborted) throw opts.signal.reason;
+        return receipt("keep");
+      },
+    }),
+  );
+  try {
+    const client = httpRequest({
+      host: "127.0.0.1",
+      port,
+      path: "/engram/v1/review/deck/action",
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${TOKEN}`,
+        "content-type": "application/json",
+      },
+    });
+    client.on("error", () => {});
+    client.end(JSON.stringify(keepBody));
+    await started.promise;
+    assert.ok(observed, "abort signal must reach the executor");
+    client.destroy();
+    await settled.promise;
+    assert.equal(observed.aborted, true);
+  } finally {
+    forceRelease.resolve();
+    await stop();
+  }
+});

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;
+  }
+}