@remnic/core 9.65.2 → 9.65.4

package/src/procedural/skill-projection.ts

@@ -0,0 +1,356 @@
+/**
+ * skill-projection.ts — project active `procedure` memories into portable
+ * `skills/<slug>/SKILL.md` bundles, and parse hand-authored bundles back into
+ * procedure candidates (issue #2369).
+ *
+ * Pure module: no filesystem, no host coupling. The Codex materializer, the
+ * `remnic export skills` CLI, and `remnic import skills` all consume these
+ * functions so one slug + format contract serves every surface.
+ *
+ * Import is INERT by construction: this module only ever returns text and
+ * parsed steps. It never resolves, loads, or executes a bundle resource.
+ */
+
+import { coerceBool, coerceNumber } from "../connectors/coerce.js";
+import { isValidSkillSlug } from "../skills-registry.js";
+import { stripAttributesSuffix } from "../structured-attributes.js";
+import type { MemoryFile, MemoryStatus } from "../types.js";
+import { parseProcedureStepsFromBody, type ProcedureStep } from "./procedure-types.js";
+
+/** Provenance frontmatter keys. Namespaced so hosts treat them as opaque. */
+export const SKILL_MEMORY_ID_KEY = "x-remnic-memory-id";
+export const SKILL_UPDATED_KEY = "x-remnic-updated";
+export const SKILL_SOURCE_KEY = "x-remnic-source";
+
+/** File name every bundle directory must contain. */
+export const SKILL_FILE_NAME = "SKILL.md";
+
+/** Source tag written on imported procedure memories. */
+export const SKILL_IMPORT_SOURCE = "skill-import";
+
+/**
+ * The ONLY statuses that may be projected (Review Prevention Checklist §41 —
+ * define the active set, never an exclusion list). `pending_review`,
+ * `rejected`, `quarantined`, `superseded`, `archived`, and `forgotten` are
+ * withheld because a projected skill is loaded by a host with no further gate.
+ */
+const PROJECTABLE_STATUSES: Partial<Record<MemoryStatus, true>> = { active: true };
+
+/** Default projection cap. `0` disables projection entirely. */
+export const DEFAULT_SKILL_PROJECTION_MAX_SKILLS = 20;
+
+/** Hard ceiling so a misconfigured cap cannot flood a host skills directory. */
+const MAX_SKILL_PROJECTION_MAX_SKILLS = 500;
+
+const MAX_SLUG_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 300;
+
+export interface SkillBundleProvenance {
+  /** Remnic memory id this bundle was projected from. */
+  memoryId: string;
+  /** `frontmatter.updated` of the source memory. */
+  updated: string;
+  /** `frontmatter.source` of the source memory, when present. */
+  source?: string;
+}
+
+export interface SkillBundle {
+  slug: string;
+  frontmatter: { name: string; description: string };
+  /** Markdown body: the stored procedure body (title line + `## Step N`). */
+  body: string;
+  provenance: SkillBundleProvenance;
+}
+
+export interface ProjectProceduresOptions {
+  /** Cap on projected bundles. `0` projects nothing. Default 20. */
+  maxSkills?: number;
+  /** Slugs a projected bundle must not take (e.g. `BUILTIN_SKILLS` slugs). */
+  reservedSlugs?: readonly string[];
+}
+
+export interface SkillProjectionConfig {
+  enabled: boolean;
+  maxSkills: number;
+}
+
+/**
+ * Parse the `procedural.skillProjection` config block. Mirrors
+ * `parseProceduralMaintenanceConfig`: string forms (`"false"`, `"0"`) coerce,
+ * unrecognized values throw rather than silently defaulting.
+ */
+export function parseSkillProjectionConfig(raw: unknown): SkillProjectionConfig {
+  if (raw !== undefined && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
+    throw new Error(
+      `procedural.skillProjection must be an object (got ${JSON.stringify(raw)}). Omit the key to keep skill projection disabled (issue #2369).`,
+    );
+  }
+  const block = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+
+  let enabled = false;
+  if (block.enabled !== undefined) {
+    const coerced = coerceBool(block.enabled);
+    if (coerced === undefined) {
+      throw new Error(
+        `procedural.skillProjection.enabled must be a boolean or one of "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off" (got ${JSON.stringify(block.enabled)}).`,
+      );
+    }
+    enabled = coerced;
+  }
+
+  let maxSkills = DEFAULT_SKILL_PROJECTION_MAX_SKILLS;
+  if (block.maxSkills !== undefined) {
+    const coerced = coerceNumber(block.maxSkills);
+    if (coerced === undefined || !Number.isFinite(coerced)) {
+      throw new Error(
+        `procedural.skillProjection.maxSkills must be a finite number (got ${JSON.stringify(block.maxSkills)}).`,
+      );
+    }
+    if (!Number.isInteger(coerced)) {
+      throw new Error(
+        `procedural.skillProjection.maxSkills must be an integer (got ${JSON.stringify(block.maxSkills)}).`,
+      );
+    }
+    if (coerced < 0 || coerced > MAX_SKILL_PROJECTION_MAX_SKILLS) {
+      throw new Error(
+        `procedural.skillProjection.maxSkills must be between 0 and ${MAX_SKILL_PROJECTION_MAX_SKILLS} (got ${JSON.stringify(block.maxSkills)}). 0 disables projection.`,
+      );
+    }
+    // `0` is a documented disable value (§33) — never clamp it up.
+    maxSkills = coerced;
+  }
+
+  return { enabled, maxSkills };
+}
+
+/**
+ * Sanitize arbitrary text into a slug `isValidSkillSlug` accepts.
+ * Deterministic: the same title always yields the same slug.
+ */
+export function sanitizeSkillSlug(input: string): string {
+  const base = input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .slice(0, MAX_SLUG_LENGTH);
+  const trimmed = trimDashes(base);
+  return trimmed.length > 0 && isValidSkillSlug(trimmed) ? trimmed : "procedure";
+}
+
+function trimDashes(value: string): string {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "-") start += 1;
+  while (end > start && value[end - 1] === "-") end -= 1;
+  return value.slice(start, end);
+}
+
+/** Append a suffix while keeping the slug valid and within the length cap. */
+function withSuffix(base: string, suffix: string): string {
+  const room = MAX_SLUG_LENGTH - suffix.length;
+  const head = trimDashes(base.slice(0, Math.max(1, room)));
+  const candidate = `${head.length > 0 ? head : "procedure"}${suffix}`;
+  return isValidSkillSlug(candidate) ? candidate : `procedure${suffix}`;
+}
+
+/**
+ * Reserve a slug: prefix reserved (built-in) collisions with `user-`, then
+ * disambiguate duplicates with a stable `-2`, `-3`, … tiebreak so a batch with
+ * repeated titles never writes two bundles to one directory (§37).
+ */
+function allocateSlug(base: string, used: Set<string>, reserved: ReadonlySet<string>): string {
+  let candidate = reserved.has(base) ? withSuffix(`user-${base}`, "") : base;
+  if (!isValidSkillSlug(candidate)) candidate = "procedure";
+  if (!used.has(candidate) && !reserved.has(candidate)) {
+    used.add(candidate);
+    return candidate;
+  }
+  for (let n = 2; n < 10_000; n++) {
+    const next = withSuffix(candidate, `-${n}`);
+    if (!used.has(next) && !reserved.has(next)) {
+      used.add(next);
+      return next;
+    }
+  }
+  // Unreachable in practice (10k distinct suffixes per base slug).
+  throw new Error(`skill-projection: could not allocate a unique slug for ${base}`);
+}
+
+/** First non-empty line of the body, with a leading markdown heading stripped. */
+export function procedureTitleFromBody(body: string): string {
+  for (const line of body.replace(/\r\n/g, "\n").split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (/^##\s+Step\s+\d+/i.test(trimmed)) break;
+    return trimmed.replace(/^#{1,6}\s*/, "").trim();
+  }
+  return "";
+}
+
+/** Total comparator: newest first, `id` as the stable tiebreak (§12). */
+function compareProcedures(a: MemoryFile, b: MemoryFile): number {
+  const aTs = Date.parse(a.frontmatter.updated ?? "");
+  const bTs = Date.parse(b.frontmatter.updated ?? "");
+  const aVal = Number.isFinite(aTs) ? aTs : 0;
+  const bVal = Number.isFinite(bTs) ? bTs : 0;
+  if (aVal !== bVal) return bVal - aVal;
+  const aId = a.frontmatter.id ?? "";
+  const bId = b.frontmatter.id ?? "";
+  if (aId < bId) return -1;
+  if (aId > bId) return 1;
+  return 0;
+}
+
+/**
+ * Project procedure memories into skill bundles. Filters to `active`
+ * procedures, orders deterministically, caps at `maxSkills`, and assigns
+ * collision-free slugs.
+ */
+export function projectProceduresToSkills(
+  memories: readonly MemoryFile[],
+  options: ProjectProceduresOptions = {},
+): SkillBundle[] {
+  const maxSkills =
+    typeof options.maxSkills === "number" && Number.isInteger(options.maxSkills) && options.maxSkills >= 0
+      ? Math.min(MAX_SKILL_PROJECTION_MAX_SKILLS, options.maxSkills)
+      : DEFAULT_SKILL_PROJECTION_MAX_SKILLS;
+  if (maxSkills === 0) return [];
+
+  const reserved = new Set((options.reservedSlugs ?? []).map((s) => s.trim().toLowerCase()));
+  const candidates = memories
+    .filter(
+      (m) =>
+        m.frontmatter.category === "procedure" &&
+        PROJECTABLE_STATUSES[(m.frontmatter.status ?? "active") as MemoryStatus] === true &&
+        typeof m.content === "string" &&
+        m.content.trim().length > 0,
+    )
+    .sort(compareProcedures)
+    .slice(0, maxSkills);
+
+  const used = new Set<string>();
+  const bundles: SkillBundle[] = [];
+  for (const memory of candidates) {
+    // Drop the machine "[Attributes: ...]" footer writeMemory appends: a human
+    // skill body must not carry it, and leaving it in would let the footer be
+    // absorbed into the final step's intent on re-parse.
+    const body = stripAttributesSuffix(memory.content.replace(/\r\n/g, "\n")).trim();
+    const title = procedureTitleFromBody(body) || memory.frontmatter.id;
+    const slug = allocateSlug(sanitizeSkillSlug(title), used, reserved);
+    bundles.push({
+      slug,
+      frontmatter: {
+        name: slug,
+        description: title.slice(0, MAX_DESCRIPTION_LENGTH),
+      },
+      body: `${body}\n`,
+      provenance: {
+        memoryId: memory.frontmatter.id,
+        updated: memory.frontmatter.updated,
+        ...(memory.frontmatter.source ? { source: memory.frontmatter.source } : {}),
+      },
+    });
+  }
+  return bundles;
+}
+
+/**
+ * Render one bundle as SKILL.md text. Scalars are emitted as YAML
+ * double-quoted strings so a title containing `:` or `#` cannot corrupt the
+ * frontmatter block.
+ */
+export function renderSkillBundle(bundle: SkillBundle): string {
+  const lines = [
+    "---",
+    `name: ${yamlScalar(bundle.frontmatter.name)}`,
+    `description: ${yamlScalar(bundle.frontmatter.description)}`,
+    `${SKILL_MEMORY_ID_KEY}: ${yamlScalar(bundle.provenance.memoryId)}`,
+    `${SKILL_UPDATED_KEY}: ${yamlScalar(bundle.provenance.updated)}`,
+  ];
+  if (bundle.provenance.source) {
+    lines.push(`${SKILL_SOURCE_KEY}: ${yamlScalar(bundle.provenance.source)}`);
+  }
+  lines.push("---", "");
+  return `${lines.join("\n")}\n${bundle.body.trimEnd()}\n`;
+}
+
+function yamlScalar(value: string): string {
+  return JSON.stringify(value.replace(/\r?\n/g, " ").trim());
+}
+
+export interface ParsedSkillBundle {
+  /** Directory name the bundle was read from (already sanitized by the caller). */
+  slug: string;
+  name?: string;
+  description?: string;
+  /** Markdown body with the frontmatter block removed. */
+  body: string;
+  /** Parsed `## Step N` sections, or `null` for a step-less body. */
+  steps: ProcedureStep[] | null;
+  provenance: { memoryId?: string; updated?: string; source?: string };
+}
+
+/**
+ * Parse SKILL.md text. Frontmatter is optional; unknown keys are ignored.
+ * Returns `null` when there is no body to import.
+ */
+export function parseSkillBundle(text: string, slug: string): ParsedSkillBundle | null {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  // Line scan rather than a lazy `[\s\S]*?` fence regex (issue #2439).
+  let frontmatter: Record<string, string> = {};
+  let bodyLines = lines;
+  if (lines[0]?.trim() === "---") {
+    const close = lines.findIndex((line, idx) => idx > 0 && line.trim() === "---");
+    if (close !== -1) {
+      frontmatter = parseFlatFrontmatter(lines.slice(1, close).join("\n"));
+      bodyLines = lines.slice(close + 1);
+    }
+  }
+  const body = bodyLines.join("\n").trim();
+  if (body.length === 0) return null;
+  return {
+    slug,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    body,
+    steps: parseProcedureStepsFromBody(body),
+    provenance: {
+      memoryId: frontmatter[SKILL_MEMORY_ID_KEY],
+      updated: frontmatter[SKILL_UPDATED_KEY],
+      source: frontmatter[SKILL_SOURCE_KEY],
+    },
+  };
+}
+
+/**
+ * Minimal flat `key: value` frontmatter reader. Nested blocks and sequences
+ * (e.g. `allowed-tools:`) are skipped — the import path only consumes scalars.
+ */
+function parseFlatFrontmatter(block: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of block.split("\n")) {
+    if (/^\s/.test(line) || line.trim().startsWith("#")) continue;
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    const raw = line.slice(colon + 1).trim();
+    if (key.length === 0 || raw.length === 0) continue;
+    out[key] = unquoteScalar(raw);
+  }
+  return out;
+}
+
+function unquoteScalar(raw: string): string {
+  if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (typeof parsed === "string") return parsed;
+    } catch {
+      // fall through to the literal slice below
+    }
+    return raw.slice(1, -1);
+  }
+  if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}

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