@remnic/core 9.54.4 → 9.54.6

package/src/support-passport/card-projection.ts

@@ -0,0 +1,348 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+
+import type { OfflineSyncExcludeFile } from "../offline-sync-file-io.js";
+import { stripAttributesSuffix } from "../structured-attributes.js";
+import type { MemoryFile } from "../types.js";
+import {
+  type SupportPassportCard,
+  SupportPassportCardCategorySchema,
+  SupportPassportCardSchema,
+  SupportPassportCardStatusSchema,
+  SupportPassportMemoryIdSchema,
+  SupportPassportNamespaceSchema,
+  SupportPassportSourceMemoryIdSchema,
+  computeSupportPassportCardRevision,
+} from "./contracts.js";
+
+export const SUPPORT_PASSPORT_CARD_TAG = "support-passport-card";
+export const SUPPORT_PASSPORT_AUDIT_TAG = "support-passport-audit";
+
+export function isSupportPassportPrivateMemory(memory: {
+  frontmatter: {
+    tags?: readonly string[];
+    structuredAttributes?: Readonly<Record<string, string>>;
+  };
+}): boolean {
+  const tags = memory.frontmatter.tags;
+  if (tags?.includes(SUPPORT_PASSPORT_CARD_TAG) === true || tags?.includes(SUPPORT_PASSPORT_AUDIT_TAG) === true) {
+    return true;
+  }
+  return Object.keys(memory.frontmatter.structuredAttributes ?? {})
+    .some((key) => key.startsWith("support-passport-"));
+}
+
+export function excludeSupportPassportPrivateMemories<T extends Pick<MemoryFile, "frontmatter">>(
+  memories: readonly T[]
+): T[] {
+  return memories.filter((memory) => !isSupportPassportPrivateMemory(memory));
+}
+
+export function createSupportPassportPrivateFileExclusion(storage: {
+  readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
+}): OfflineSyncExcludeFile {
+  const classifications = new Map<string, { identity: string; excluded: Promise<boolean> }>();
+  return async ({ filePath }) => {
+    let file: Awaited<ReturnType<typeof lstat>>;
+    try {
+      file = await lstat(filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        classifications.delete(filePath);
+        return false;
+      }
+      throw error;
+    }
+    const identity = `${file.dev}:${file.ino}:${file.size}:${file.mtimeMs}:${file.ctimeMs}`;
+    const cached = classifications.get(filePath);
+    if (cached?.identity === identity) return await cached.excluded;
+    const excluded = storage
+      .readMemoryByPath(filePath)
+      .then((memory) => (memory ? isSupportPassportPrivateMemory(memory) : false));
+    classifications.set(filePath, { identity, excluded });
+    try {
+      return await excluded;
+    } catch (error) {
+      if (classifications.get(filePath)?.excluded === excluded) classifications.delete(filePath);
+      throw error;
+    }
+  };
+}
+
+export const SUPPORT_PASSPORT_ATTRIBUTE_KEYS = Object.freeze({
+  namespace: "support-passport-namespace",
+  namespaceEncoding: "support-passport-namespace-encoding",
+  owner: "support-passport-owner",
+  title: "support-passport-title",
+  category: "support-passport-category",
+  order: "support-passport-order",
+  reviewBy: "support-passport-review-by",
+  sourceMemoryIds: "support-passport-source-ids",
+  replacesDraftId: "support-passport-replaces-draft-id",
+  replacedRevision: "support-passport-replaced-revision",
+  draftReplacementPrepared: "support-passport-draft-replacement-prepared",
+  replacementComplete: "support-passport-replacement-complete",
+  generatedBatchId: "support-passport-generated-batch-id",
+  generatedBatchSize: "support-passport-generated-batch-size",
+});
+
+const SUPPORT_PASSPORT_NAMESPACE_ENCODING = "base64url-v1";
+const SUPPORT_PASSPORT_NAMESPACE_CHUNK_PREFIX = "support-passport-namespace-";
+const SUPPORT_PASSPORT_NAMESPACE_CHUNK_SIZE = 1_024;
+const LegacySupportPassportNamespaceSchema = SupportPassportNamespaceSchema.refine(
+  (namespace) =>
+    !namespace.includes("/") &&
+    !namespace.includes("\\") &&
+    !namespace.includes("..") &&
+    !namespace.includes("]") &&
+    !namespace.includes("\0") &&
+    !namespace.includes("\n") &&
+    !namespace.includes("\r")
+);
+
+export function encodeSupportPassportNamespaceAttributes(namespace: string): Record<string, string> {
+  const canonical = SupportPassportNamespaceSchema.parse(namespace);
+  const encoded = Buffer.from(canonical, "utf8").toString("base64url");
+  const chunks = encoded.match(new RegExp(`.{1,${SUPPORT_PASSPORT_NAMESPACE_CHUNK_SIZE}}`, "g")) ?? [];
+  const digest = createHash("sha256").update(encoded).digest("hex");
+  return Object.fromEntries([
+    [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.namespace, chunks[0] ?? ""],
+    [
+      SUPPORT_PASSPORT_ATTRIBUTE_KEYS.namespaceEncoding,
+      `${SUPPORT_PASSPORT_NAMESPACE_ENCODING}:${chunks.length}:${digest}`,
+    ],
+    ...chunks.slice(1).map((chunk, index) => [`${SUPPORT_PASSPORT_NAMESPACE_CHUNK_PREFIX}${index + 1}`, chunk]),
+  ]);
+}
+
+export function decodeSupportPassportNamespaceAttributes(attributes: Readonly<Record<string, string>>): string | null {
+  const firstChunk = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.namespace];
+  const encoding = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.namespaceEncoding];
+  if (encoding === undefined) {
+    const legacy = LegacySupportPassportNamespaceSchema.safeParse(firstChunk);
+    return legacy.success ? legacy.data : null;
+  }
+  const match = /^base64url-v1:([1-9]\d*):([a-f0-9]{64})$/.exec(encoding);
+  if (!match || typeof firstChunk !== "string") return null;
+  const chunkCount = Number(match[1]);
+  if (!Number.isSafeInteger(chunkCount)) return null;
+  const chunkIndexes = Object.keys(attributes).flatMap((key) => {
+    const chunkMatch = /^support-passport-namespace-(\d+)$/.exec(key);
+    return chunkMatch ? [Number(chunkMatch[1])] : [];
+  });
+  if (
+    chunkIndexes.length !== chunkCount - 1 ||
+    chunkIndexes.some((index) => !Number.isSafeInteger(index) || index < 1 || index >= chunkCount)
+  )
+    return null;
+  const chunks = [firstChunk];
+  for (let index = 1; index < chunkCount; index += 1) {
+    const chunk = attributes[`${SUPPORT_PASSPORT_NAMESPACE_CHUNK_PREFIX}${index}`];
+    if (typeof chunk !== "string" || chunk.length === 0) return null;
+    chunks.push(chunk);
+  }
+  const encoded = chunks.join("");
+  if (createHash("sha256").update(encoded).digest("hex") !== match[2]) return null;
+  const decoded = Buffer.from(encoded, "base64url").toString("utf8");
+  if (Buffer.from(decoded, "utf8").toString("base64url") !== encoded) return null;
+  const namespace = SupportPassportNamespaceSchema.safeParse(decoded);
+  return namespace.success ? namespace.data : null;
+}
+
+export interface StoredSupportPassportCard {
+  card: SupportPassportCard;
+  memory: MemoryFile;
+  order: number;
+  sourceMemoryIds: string[];
+  namespace: string;
+  owner: string;
+  replacesDraftId?: string;
+  replacedRevision?: string;
+  draftReplacementPrepared: boolean;
+  generatedBatchId?: string;
+  generatedBatchSize?: number;
+}
+
+export function computeSupportPassportOwnerKey(principal: string): string {
+  return createHash("sha256").update(principal).digest("hex");
+}
+
+export function activeSupportPassportReplacementPredecessorIds(
+  cards: readonly StoredSupportPassportCard[],
+): Set<string> {
+  return new Set(
+    cards
+      .filter((item) => item.card.status === "active")
+      .map((item) => item.memory.frontmatter.supersedes)
+      .filter((cardId): cardId is string => typeof cardId === "string"),
+  );
+}
+
+function parseSourceMemoryIds(frontmatter: MemoryFile["frontmatter"]): string[] | null {
+  const lineage = frontmatter.lineage;
+  const legacyValue = frontmatter.structuredAttributes?.[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.sourceMemoryIds];
+  const rawIds = lineage ?? (legacyValue === undefined || legacyValue === "" ? [] : legacyValue.split(","));
+  if (rawIds.length > 5) return null;
+  const normalized: string[] = [];
+  for (const rawId of rawIds) {
+    const parsed = SupportPassportSourceMemoryIdSchema.safeParse(rawId);
+    if (!parsed.success) return null;
+    normalized.push(parsed.data);
+  }
+  if (new Set(normalized).size !== normalized.length) return null;
+  return normalized;
+}
+
+interface SupportPassportCardMetadata {
+  fields: Omit<SupportPassportCard, "revision" | "statement">;
+  order: number;
+  sourceMemoryIds: string[];
+  namespace: string;
+  owner: string;
+  replacesDraftId?: string;
+  replacedRevision?: string;
+  draftReplacementPrepared: boolean;
+  generatedBatchId?: string;
+  generatedBatchSize?: number;
+}
+
+function parseSupportPassportCardMetadata(
+  memory: Pick<MemoryFile, "frontmatter">,
+): SupportPassportCardMetadata | null {
+  const frontmatter = memory.frontmatter;
+  const attributes = frontmatter.structuredAttributes;
+  if (frontmatter.category !== "preference") return null;
+  if (!frontmatter.tags?.includes(SUPPORT_PASSPORT_CARD_TAG)) return null;
+  if (
+    !attributes ||
+    frontmatter.blockedBy ||
+    frontmatter.archivedAt ||
+    frontmatter.supersededBy
+  )
+    return null;
+
+  const category = SupportPassportCardCategorySchema.safeParse(
+    attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.category],
+  );
+  const status = SupportPassportCardStatusSchema.safeParse(frontmatter.status);
+  const rawOrder = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.order];
+  const order = Number(rawOrder);
+  const sourceMemoryIds = parseSourceMemoryIds(frontmatter);
+  const namespace = decodeSupportPassportNamespaceAttributes(attributes);
+  const owner = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.owner];
+  let replacesDraftId: string | undefined;
+  const rawReplacesDraftId =
+    attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacesDraftId];
+  if (rawReplacesDraftId !== undefined) {
+    const parsedReplacesDraftId =
+      SupportPassportMemoryIdSchema.safeParse(rawReplacesDraftId);
+    if (!parsedReplacesDraftId.success) return null;
+    replacesDraftId = parsedReplacesDraftId.data;
+  }
+  let replacedRevision: string | undefined;
+  const rawReplacedRevision =
+    attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacedRevision];
+  if (rawReplacedRevision !== undefined) {
+    if (!/^[a-f0-9]{64}$/.test(rawReplacedRevision)) return null;
+    replacedRevision = rawReplacedRevision;
+  }
+  const generatedBatchId = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.generatedBatchId];
+  const rawGeneratedBatchSize = attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.generatedBatchSize];
+  let generatedBatchSize: number | undefined;
+  if (generatedBatchId !== undefined) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(generatedBatchId)) {
+      return null;
+    }
+    if (
+      typeof rawGeneratedBatchSize !== "string" ||
+      !/^[1-8]$/.test(rawGeneratedBatchSize)
+    ) {
+      return null;
+    }
+    generatedBatchSize = Number(rawGeneratedBatchSize);
+  } else if (rawGeneratedBatchSize !== undefined) {
+    return null;
+  }
+  if (
+    !category.success ||
+    !status.success ||
+    status.data === "superseded" ||
+    typeof rawOrder !== "string" ||
+    !/^(?:0|[1-9]\d*)$/.test(rawOrder) ||
+    !Number.isSafeInteger(order) ||
+    namespace === null ||
+    typeof owner !== "string" ||
+    !/^[a-f0-9]{64}$/.test(owner) ||
+    !sourceMemoryIds
+  )
+    return null;
+  const fields = SupportPassportCardSchema.omit({
+    revision: true,
+    statement: true,
+  }).safeParse({
+    cardId: frontmatter.id,
+    title: attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.title],
+    category: category.data,
+    status: status.data,
+    updatedAt: frontmatter.updated,
+    reviewBy: attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.reviewBy],
+  });
+  if (!fields.success) return null;
+  return {
+    fields: fields.data,
+    order,
+    sourceMemoryIds,
+    namespace,
+    owner,
+    replacesDraftId,
+    replacedRevision,
+    draftReplacementPrepared:
+      attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared] ===
+      "true",
+    generatedBatchId,
+    generatedBatchSize,
+  };
+}
+
+export function hasLiveSupportPassportCard(memory: Pick<MemoryFile, "frontmatter" | "content">): boolean {
+  const metadata = parseSupportPassportCardMetadata(memory);
+  if (metadata?.fields.status !== "active" && metadata?.fields.status !== "pending_review") return false;
+  return SupportPassportCardSchema.omit({ revision: true }).safeParse({
+    ...metadata.fields,
+    statement: stripAttributesSuffix(memory.content),
+  }).success;
+}
+
+export function projectSupportPassportCard(
+  memory: MemoryFile,
+): StoredSupportPassportCard | null {
+  const metadata = parseSupportPassportCardMetadata(memory);
+  if (!metadata) return null;
+
+  const fields = {
+    ...metadata.fields,
+    statement: stripAttributesSuffix(memory.content),
+  };
+  const normalized = SupportPassportCardSchema.omit({
+    revision: true,
+  }).safeParse(fields);
+  if (!normalized.success) return null;
+  const parsed = SupportPassportCardSchema.safeParse({
+    ...normalized.data,
+    revision: computeSupportPassportCardRevision(normalized.data),
+  });
+  if (!parsed.success) return null;
+  return {
+    card: parsed.data,
+    memory,
+    order: metadata.order,
+    sourceMemoryIds: metadata.sourceMemoryIds,
+    namespace: metadata.namespace,
+    owner: metadata.owner,
+    replacesDraftId: metadata.replacesDraftId,
+    replacedRevision: metadata.replacedRevision,
+    draftReplacementPrepared: metadata.draftReplacementPrepared,
+    generatedBatchId: metadata.generatedBatchId,
+    generatedBatchSize: metadata.generatedBatchSize,
+  };
+}

package/src/support-passport/card-replacement.ts

@@ -0,0 +1,126 @@
+import type { StorageManager } from "../index.js";
+import { log } from "../logger.js";
+import { stripAttributesSuffix } from "../structured-attributes.js";
+import {
+  SUPPORT_PASSPORT_ATTRIBUTE_KEYS,
+  type StoredSupportPassportCard,
+  computeSupportPassportOwnerKey,
+  encodeSupportPassportNamespaceAttributes,
+  projectSupportPassportCard,
+} from "./card-projection.js";
+import { ownsMemory } from "./card-state.js";
+import { SupportPassportError } from "./errors.js";
+
+export async function validateSupportPassportReplacementPrior(
+  storage: StorageManager,
+  replacement: StoredSupportPassportCard,
+  namespace: string,
+  principal: string
+): Promise<void> {
+  const priorId = replacement.memory.frontmatter.supersedes;
+  if (!priorId) return;
+  const priorMemory = await storage.getMemoryById(priorId);
+  const priorIsOwned = priorMemory ? ownsMemory(priorMemory, namespace, principal) : false;
+  const alreadyRetired =
+    priorIsOwned &&
+    priorMemory?.frontmatter.status === "superseded" &&
+    priorMemory.frontmatter.supersededBy === replacement.card.cardId;
+  const prior = priorMemory && priorIsOwned && !alreadyRetired ? projectSupportPassportCard(priorMemory) : null;
+  if (prior?.card.status === "rejected" || alreadyRetired) return;
+  if (!priorMemory || prior?.card.status !== "active") {
+    throw new SupportPassportError("storage_conflict", "The prior support card changed before replacement.", 409);
+  }
+}
+
+export async function prepareSupportPassportReplacementPrior(input: {
+  storage: StorageManager;
+  replacement: StoredSupportPassportCard;
+  principal: string;
+  namespace: string;
+  now: () => Date;
+  requireOwnerLock: () => Promise<void>;
+  onCommitted?: () => void;
+}): Promise<string | null> {
+  const { storage, replacement, principal, namespace } = input;
+  const priorId = replacement.memory.frontmatter.supersedes;
+  if (!priorId) return null;
+  const priorMemory = await storage.getMemoryById(priorId);
+  const priorIsOwned = priorMemory ? ownsMemory(priorMemory, namespace, principal) : false;
+  const alreadyRetired =
+    priorIsOwned &&
+    priorMemory?.frontmatter.status === "superseded" &&
+    priorMemory.frontmatter.supersededBy === replacement.card.cardId;
+  const prior = priorMemory && priorIsOwned && !alreadyRetired ? projectSupportPassportCard(priorMemory) : null;
+  if (prior?.card.status === "rejected") return null;
+  if (!priorMemory || (!alreadyRetired && prior?.card.status !== "active")) {
+    throw new SupportPassportError("storage_conflict", "The prior support card changed before replacement.", 409);
+  }
+  if (alreadyRetired) return priorId;
+  const retiredAt = input.now().toISOString();
+  await input.requireOwnerLock();
+  const retired = await storage.writeMemoryFrontmatterIfUnchanged(
+    priorMemory,
+    {
+      status: "superseded",
+      supersededBy: replacement.card.cardId,
+      supersededAt: retiredAt,
+      supersessionCause: "direct",
+      updated: retiredAt,
+    },
+    {
+      actor: principal,
+      reasonCode: "support-passport-replacement-pending",
+      relatedMemoryIds: [replacement.card.cardId],
+    }
+  );
+  if (!retired) {
+    throw new SupportPassportError("storage_conflict", "The prior support card changed before replacement.", 409);
+  }
+  input.onCommitted?.();
+  return priorId;
+}
+
+export async function completeSupportPassportReplacementPrior(input: {
+  storage: StorageManager;
+  priorId: string;
+  replacement: StoredSupportPassportCard;
+  principal: string;
+  namespace: string;
+  requireOwnerLock: () => Promise<void>;
+}): Promise<boolean> {
+  const { storage, priorId, replacement, principal, namespace } = input;
+  const replacementId = replacement.card.cardId;
+  const prior = await storage.getMemoryById(priorId);
+  if (
+    !prior ||
+    !ownsMemory(prior, namespace, principal) ||
+    prior.frontmatter.status !== "superseded" ||
+    prior.frontmatter.supersededBy !== replacementId
+  ) {
+    return false;
+  }
+  await input.requireOwnerLock();
+  const completed = await storage.supersedeMemory(
+    priorId,
+    replacementId,
+    "support-passport-replacement",
+    { supersessionCause: "direct" },
+    {
+      actor: principal,
+      requireActive: true,
+      acceptExactReplay: true,
+      expectedSnapshot: prior,
+      audit: {
+        content: stripAttributesSuffix(prior.content),
+        tags: ["supersession", "auto-resolved", "support-passport-audit"],
+        structuredAttributes: {
+          ...encodeSupportPassportNamespaceAttributes(namespace),
+          [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.owner]: computeSupportPassportOwnerKey(principal),
+        },
+        source: "support-passport",
+      },
+    }
+  );
+  if (!completed) log.warn("support passport could not complete replacement retirement side effects");
+  return completed;
+}

package/src/support-passport/card-service-commit-forwarding.test.ts

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { StorageManager } from "../index.js";
+import type { MemoryFile } from "../types.js";
+import type { HeldFileLockController } from "../utils/serialize-mutations.js";
+import {
+  SUPPORT_PASSPORT_ATTRIBUTE_KEYS,
+  SUPPORT_PASSPORT_CARD_TAG,
+  type StoredSupportPassportCard,
+  computeSupportPassportOwnerKey,
+  projectSupportPassportCard,
+} from "./card-projection.js";
+import type { SupportPassportCard } from "./contracts.js";
+import { SupportPassportCardService } from "./card-service.js";
+
+const PRINCIPAL = "owner:alice";
+const NAMESPACE = "alice";
+
+function memory(id: string, status: "pending_review" | "rejected", replacesDraftId?: string): MemoryFile {
+  return {
+    path: `/memory/preferences/${id}.md`,
+    content: "Offer me a quiet place and time.",
+    frontmatter: {
+      id,
+      category: "preference",
+      source: "support-passport",
+      confidence: 1,
+      confidenceTier: "explicit",
+      created: "2026-08-11T12:00:00.000Z",
+      updated: "2026-08-11T12:00:00.000Z",
+      status,
+      tags: [SUPPORT_PASSPORT_CARD_TAG],
+      structuredAttributes: {
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.namespace]: NAMESPACE,
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.owner]: computeSupportPassportOwnerKey(PRINCIPAL),
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.title]: "Quiet space",
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.category]: "environment",
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.order]: "0",
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.reviewBy]: "2026-09-01T12:00:00.000Z",
+        [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.sourceMemoryIds]: "",
+        ...(replacesDraftId
+          ? {
+              [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacesDraftId]: replacesDraftId,
+              [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared]: "true",
+            }
+          : {}),
+      },
+    },
+  } as MemoryFile;
+}
+
+test("rejected-draft recovery forwards the commit notification", async () => {
+  const replaced = memory("draft-one", "rejected");
+  const replacement = projectSupportPassportCard(memory("draft-two", "pending_review", "draft-one"));
+  assert.ok(replacement);
+  const storage = {
+    getMemoryById: async (id: string) => (id === "draft-one" ? replaced : null),
+  } as unknown as StorageManager;
+  const service = new SupportPassportCardService({
+    resolveOwner: async () => ({ principal: PRINCIPAL, namespace: NAMESPACE, storage }),
+  });
+  let commitNotifications = 0;
+  const inspected = service as unknown as {
+    recoverReplacedDraft(
+      target: StorageManager,
+      card: StoredSupportPassportCard,
+      lock: HeldFileLockController,
+      principal: string,
+      namespace: string,
+      onCommitted?: () => void
+    ): Promise<void>;
+    finishPreparedDraftReplacement(
+      target: StorageManager,
+      replacementId: string,
+      lock: HeldFileLockController,
+      principal: string,
+      namespace: string,
+      onCommitted?: () => void
+    ): Promise<SupportPassportCard>;
+  };
+  inspected.finishPreparedDraftReplacement = async (
+    _target,
+    _replacementId,
+    _lock,
+    _principal,
+    _namespace,
+    onCommitted
+  ) => {
+    onCommitted?.();
+    return replacement.card;
+  };
+
+  await inspected.recoverReplacedDraft(
+    storage,
+    replacement,
+    {} as HeldFileLockController,
+    PRINCIPAL,
+    NAMESPACE,
+    () => {
+      commitNotifications += 1;
+    }
+  );
+
+  assert.equal(commitNotifications, 1);
+});
+
+test("pre-write card recovery forwards the commit notification", async () => {
+  const replacementMemory = memory("draft-two", "pending_review", "draft-one");
+  const storage = {
+    getCorpusScanVersion: () => "1:0",
+    readAllMemories: async () => [replacementMemory],
+  } as unknown as StorageManager;
+  const service = new SupportPassportCardService({
+    resolveOwner: async () => ({ principal: PRINCIPAL, namespace: NAMESPACE, storage }),
+  });
+  let commitNotifications = 0;
+  const inspected = service as unknown as {
+    readStoredCards(
+      target: StorageManager,
+      lock: HeldFileLockController,
+      principal: string,
+      namespace: string,
+      onCommitted?: () => void
+    ): Promise<StoredSupportPassportCard[]>;
+    recoverReplacementTransition(
+      target: StorageManager,
+      candidate: MemoryFile,
+      lock: HeldFileLockController,
+      principal: string,
+      namespace: string,
+      options?: { rollbackConflictedApproval?: boolean },
+      onCommitted?: () => void
+    ): Promise<MemoryFile>;
+  };
+  inspected.recoverReplacementTransition = async (
+    _target,
+    candidate,
+    _lock,
+    _principal,
+    _namespace,
+    _options,
+    onCommitted
+  ) => {
+    onCommitted?.();
+    return candidate;
+  };
+
+  await inspected.readStoredCards(
+    storage,
+    {} as HeldFileLockController,
+    PRINCIPAL,
+    NAMESPACE,
+    () => {
+      commitNotifications += 1;
+    }
+  );
+
+  assert.equal(commitNotifications, 1);
+});