@remnic/core 9.54.5 → 9.54.6

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

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
+
 import type { StorageManager } from "../index.js";
 import { log } from "../logger.js";
-import { stripAttributesSuffix } from "../structured-attributes.js";
 import type { MemoryFile } from "../types.js";
 import type { HeldFileLockController } from "../utils/serialize-mutations.js";
 import { composeMemoryEnvelope } from "../write-envelope.js";
@@ -9,10 +10,30 @@ import {
   SUPPORT_PASSPORT_CARD_TAG,
   type StoredSupportPassportCard,
   computeSupportPassportOwnerKey,
-  decodeSupportPassportNamespaceAttributes,
   encodeSupportPassportNamespaceAttributes,
-  projectSupportPassportCard,
 } from "./card-projection.js";
+import {
+  completeSupportPassportReplacementPrior,
+  prepareSupportPassportReplacementPrior,
+  validateSupportPassportReplacementPrior,
+} from "./card-replacement.js";
+import {
+  MAX_OWNER_VISIBLE_CARDS,
+  type SupportPassportCardServiceDependencies,
+  type SupportPassportOwnerScope,
+  invalidInput,
+  isStorageConflict,
+  once,
+  ownerListCards,
+  ownerVisibleCards,
+  ownsMemory,
+  projectOwnedCard,
+  projectRequiredCard,
+  requireRevision,
+  requireStatus,
+  revisionFor,
+  validateOwnerScope,
+} from "./card-state.js";
 import {
   type SupportPassportCard,
   type SupportPassportCardCategory,
@@ -22,52 +43,41 @@ import {
   SupportPassportListCardsInputSchema,
   type SupportPassportManualDraftInput,
   SupportPassportManualDraftInputSchema,
-  SupportPassportNamespaceSchema,
   type SupportPassportReplaceCardInput,
   SupportPassportReplaceCardInputSchema,
-  computeSupportPassportCardRevision,
 } from "./contracts.js";
 import { SupportPassportError } from "./errors.js";
+import {
+  type GeneratedBatchMarker,
+  commitSupportPassportGeneratedBatch,
+  isCommittedGeneratedCard,
+  persistSupportPassportGeneratedBatchMarker,
+  projectCommittedSupportPassportCards,
+  readCommittedSupportPassportCards,
+  recoverSupportPassportGeneratedBatches,
+  rollbackSupportPassportGeneratedBatch,
+} from "./generated-batch.js";
+import { type SupportPassportDraftCard, SupportPassportDraftOutputSchema } from "./model-contracts.js";
 import { withSupportPassportOwnerLock } from "./owner-lock.js";
-
-export interface SupportPassportOwnerScope {
-  principal: string;
-  namespace: string;
-  storage: StorageManager;
-}
-
-export interface SupportPassportCardServiceDependencies {
-  resolveOwner(principal: string): Promise<SupportPassportOwnerScope>;
-  now?: () => Date;
-}
-
-const OWNER_VISIBLE_STATUSES = new Set(["pending_review", "active"]);
-const MAX_OWNER_VISIBLE_CARDS = 100;
-
-function invalidInput(): SupportPassportError {
-  return new SupportPassportError("invalid_input", "The support card request is invalid.", 400);
-}
-
-function isStorageConflict(error: unknown): error is SupportPassportError {
-  return error instanceof SupportPassportError && error.code === "storage_conflict";
-}
-
+export type { SupportPassportCardServiceDependencies, SupportPassportOwnerScope } from "./card-state.js";
 export class SupportPassportCardService {
   private readonly resolveOwner: SupportPassportCardServiceDependencies["resolveOwner"];
   private readonly now: () => Date;
-
   constructor(dependencies: SupportPassportCardServiceDependencies) {
     this.resolveOwner = dependencies.resolveOwner;
     this.now = dependencies.now ?? (() => new Date());
   }
 
-  async listCards(input: { principal: string }): Promise<SupportPassportCard[]> {
+  async listCards(input: {
+    principal: string;
+  }): Promise<SupportPassportCard[]> {
     const parsed = SupportPassportListCardsInputSchema.safeParse(input);
     if (!parsed.success) throw invalidInput();
     const { principal, namespace, storage } = await this.resolveOwnerScope(parsed.data.principal);
-    return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
-      const stored = await this.readStoredCards(storage, lock, principal, namespace);
-      const cards = this.ownerVisibleCards(stored)
+    return await withSupportPassportOwnerLock(storage, { namespace, principal }, async () => {
+      const memories = await storage.readAllMemories();
+      const stored = await projectCommittedSupportPassportCards(storage, memories, namespace, principal);
+      const cards = ownerListCards(stored)
         .sort((a, b) => a.order - b.order || a.card.cardId.localeCompare(b.card.cardId))
         .map((item) => item.card);
       const output = SupportPassportCardListSchema.safeParse(cards);
@@ -78,12 +88,17 @@ export class SupportPassportCardService {
     });
   }
 
-  async createManualDraft(input: SupportPassportManualDraftInput): Promise<SupportPassportCard> {
+  async createManualDraft(
+    input: SupportPassportManualDraftInput,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
     const parsed = SupportPassportManualDraftInputSchema.safeParse(input);
     if (!parsed.success) throw invalidInput();
     const { principal, namespace, storage } = await this.resolveOwnerScope(parsed.data.principal);
-    return await withSupportPassportOwnerLock(storage, { namespace, principal }, (lock) =>
-      this.createDraft(
+    const onCommitted = once(options.onCommitted);
+    return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
+      options.signal?.throwIfAborted();
+      const created = await this.createDraft(
         storage,
         {
           title: parsed.data.title,
@@ -91,21 +106,127 @@ export class SupportPassportCardService {
           category: parsed.data.category,
           reviewBy: parsed.data.reviewBy,
           sourceMemoryIds: [],
+          onCommitted,
         },
         lock,
         principal,
         namespace
-      )
-    );
+      );
+      if (!options.signal?.aborted) return created;
+      if (!(await this.rejectGeneratedDraft(storage, created.cardId, lock, principal, namespace))) {
+        throw new SupportPassportError("storage_conflict", "A cancelled support card could not be rolled back.", 500);
+      }
+      options.signal.throwIfAborted();
+      return created;
+    });
+  }
+
+  async createGeneratedDrafts(input: {
+    principal: string;
+    cards: SupportPassportDraftCard[];
+  }): Promise<SupportPassportCard[]> {
+    const principal = SupportPassportListCardsInputSchema.safeParse({
+      principal: input.principal,
+    });
+    if (!principal.success) throw invalidInput();
+    const owner = await this.resolveOwnerScope(principal.data.principal);
+    return await this.createGeneratedDraftsForOwner({
+      authenticatedPrincipal: principal.data.principal,
+      owner,
+      cards: input.cards,
+    });
+  }
+
+  async createGeneratedDraftsForOwner(input: {
+    authenticatedPrincipal: string;
+    owner: SupportPassportOwnerScope;
+    cards: SupportPassportDraftCard[];
+    signal?: AbortSignal;
+    onCommitted?: () => void;
+    commitWithValidatedSources?: (commit: () => Promise<void>) => Promise<void>;
+  }): Promise<SupportPassportCard[]> {
+    const output = SupportPassportDraftOutputSchema.safeParse({
+      cards: input.cards,
+    });
+    if (!output.success) throw invalidInput();
+    const owner = validateOwnerScope(input.owner, input.authenticatedPrincipal);
+    const { principal, namespace, storage } = owner;
+    const onCommitted = once(input.onCommitted);
+    return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
+      const batchContext = this.generatedBatchContext(storage, lock, principal, namespace, onCommitted);
+      const batchId = randomUUID();
+      const created: SupportPassportCard[] = [];
+      const createdIds: string[] = [];
+      const createdRecords: StoredSupportPassportCard[] = [];
+      let marker: GeneratedBatchMarker | null = null;
+      try {
+        input.signal?.throwIfAborted();
+        input.signal?.throwIfAborted();
+        const storedCards = await this.readStoredCards(storage, lock, principal, namespace, onCommitted);
+        if (ownerVisibleCards(storedCards).length + output.data.cards.length > MAX_OWNER_VISIBLE_CARDS) {
+          throw new SupportPassportError(
+            "invalid_input",
+            "A support passport can contain at most 100 visible cards.",
+            400
+          );
+        }
+        let nextOrder = storedCards.reduce((maximum, card) => Math.max(maximum, card.order), -1) + 1;
+        marker = await persistSupportPassportGeneratedBatchMarker(batchContext, batchId, output.data.cards.length);
+        for (const card of output.data.cards) {
+          input.signal?.throwIfAborted();
+          created.push(
+            await this.persistDraft(
+              storage,
+              {
+                title: card.title,
+                statement: card.statement,
+                category: card.category,
+                sourceMemoryIds: card.sourceMemoryIds,
+                order: nextOrder,
+                generatedBatch: { batchId, size: output.data.cards.length },
+                onPersisted: (record) => {
+                  createdIds.push(record.card.cardId);
+                  createdRecords.push(record);
+                  onCommitted();
+                },
+              },
+              lock,
+              principal,
+              namespace
+            )
+          );
+          nextOrder += 1;
+        }
+        input.signal?.throwIfAborted();
+        const commit = async () =>
+          await commitSupportPassportGeneratedBatch(batchContext, marker!, createdRecords);
+        if (input.commitWithValidatedSources) await input.commitWithValidatedSources(commit);
+        else await commit();
+        return created;
+      } catch (error) {
+        if (!marker) throw error;
+        if (
+          !(await rollbackSupportPassportGeneratedBatch(batchContext, batchId, createdIds))
+        ) {
+          throw new SupportPassportError("storage_conflict", "A generated draft batch could not be rolled back.", 500);
+        }
+        throw error;
+      }
+    });
   }
 
-  async replaceCard(input: SupportPassportReplaceCardInput): Promise<SupportPassportCard> {
+  async replaceCard(
+    input: SupportPassportReplaceCardInput,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
     const parsed = SupportPassportReplaceCardInputSchema.safeParse(input);
     if (!parsed.success) throw invalidInput();
     const { principal, namespace, storage } = await this.resolveOwnerScope(parsed.data.principal);
+    const onCommitted = once(options.onCommitted);
     return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
+      options.signal?.throwIfAborted();
       const loadedPrior = await this.requireCard(storage, parsed.data.cardId, namespace, principal);
-      const storedCards = await this.readProjectedCards(storage, namespace, principal);
+      const storedCards = await readCommittedSupportPassportCards(storage, namespace, principal);
       const interruptedReplacements = storedCards.filter(
         (item) =>
           item.card.status === "pending_review" &&
@@ -142,22 +263,26 @@ export class SupportPassportCardService {
           interruptedReplacement.memory,
           lock,
           principal,
-          namespace
+          namespace,
+          {},
+          onCommitted
         );
-        return this.projectRequiredCard(recovered, namespace, principal).card;
+        return projectRequiredCard(recovered, namespace, principal).card;
       }
-      this.requireRevision(loadedPrior, parsed.data.expectedRevision);
-      await this.readStoredCards(storage, lock, principal, namespace);
+      requireRevision(loadedPrior, parsed.data.expectedRevision);
+      await this.readStoredCards(storage, lock, principal, namespace, onCommitted);
       const refreshedPrior = await this.requireCard(storage, parsed.data.cardId, namespace, principal);
-      this.requireRevision(refreshedPrior, parsed.data.expectedRevision);
+      requireRevision(refreshedPrior, parsed.data.expectedRevision);
       const recoveredMemory = await this.recoverReplacementTransition(
         storage,
         refreshedPrior.memory,
         lock,
         principal,
-        namespace
+        namespace,
+        {},
+        onCommitted
       );
-      const prior = this.projectRequiredCard(recoveredMemory, namespace, principal);
+      const prior = projectRequiredCard(recoveredMemory, namespace, principal);
       if (prior.card.status !== "active" && prior.card.status !== "pending_review") {
         throw new SupportPassportError(
           "invalid_card_status",
@@ -178,11 +303,22 @@ export class SupportPassportCardService {
           replacedRevision: prior.card.revision,
           order: prior.order,
           draftReplacementPrepared: prior.card.status === "pending_review",
+          onCommitted,
         },
         lock,
         principal,
         namespace
       );
+      if (options.signal?.aborted) {
+        if (!(await this.rejectGeneratedDraft(storage, replacement.cardId, lock, principal, namespace))) {
+          throw new SupportPassportError(
+            "storage_conflict",
+            "A cancelled support card edit could not be rolled back.",
+            500
+          );
+        }
+        options.signal.throwIfAborted();
+      }
       if (prior.card.status === "active") return replacement;
 
       const replacedAt = this.now().toISOString();
@@ -193,12 +329,27 @@ export class SupportPassportCardService {
         { actor: principal, reasonCode: "owner-replaced-draft" }
       );
       if (rejected) {
-        return await this.finishPreparedDraftReplacement(storage, replacement.cardId, lock, principal, namespace);
+        onCommitted();
+        return await this.finishPreparedDraftReplacement(
+          storage,
+          replacement.cardId,
+          lock,
+          principal,
+          namespace,
+          onCommitted
+        );
       }
       const currentPrior = await storage.getMemoryById(prior.card.cardId);
-      const currentPriorCard = currentPrior ? this.projectOwnedCard(currentPrior, namespace, principal) : null;
+      const currentPriorCard = currentPrior ? projectOwnedCard(currentPrior, namespace, principal) : null;
       if (currentPriorCard?.card.status === "rejected") {
-        return await this.finishPreparedDraftReplacement(storage, replacement.cardId, lock, principal, namespace);
+        return await this.finishPreparedDraftReplacement(
+          storage,
+          replacement.cardId,
+          lock,
+          principal,
+          namespace,
+          onCommitted
+        );
       }
 
       await this.rejectCreatedDraft(
@@ -207,28 +358,36 @@ export class SupportPassportCardService {
         "draft-replacement-failed",
         lock,
         principal,
-        namespace
+        namespace,
+        onCommitted
       );
       throw new SupportPassportError("storage_conflict", "The support card changed before it was edited.", 409);
     });
   }
 
-  async approveCard(input: SupportPassportCardMutationInput): Promise<SupportPassportCard> {
+  async approveCard(
+    input: SupportPassportCardMutationInput,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
     const parsed = SupportPassportCardMutationInputSchema.safeParse(input);
     if (!parsed.success) throw invalidInput();
     const { principal, namespace, storage } = await this.resolveOwnerScope(parsed.data.principal);
+    const onCommitted = once(options.onCommitted);
     return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
+      options.signal?.throwIfAborted();
       const loadedCard = await this.requireCard(storage, parsed.data.cardId, namespace, principal);
-      this.requireRevision(loadedCard, parsed.data.expectedRevision);
-      this.requireStatus(loadedCard, "pending_review");
+      requireRevision(loadedCard, parsed.data.expectedRevision);
+      requireStatus(loadedCard, "pending_review");
       const recoveredMemory = await this.recoverReplacementTransition(
         storage,
         loadedCard.memory,
         lock,
         principal,
-        namespace
+        namespace,
+        {},
+        onCommitted
       );
-      const card = this.projectRequiredCard(recoveredMemory, namespace, principal);
+      const card = projectRequiredCard(recoveredMemory, namespace, principal);
       if (card.card.status === "active") return card.card;
       if (card.card.status === "rejected") {
         throw new SupportPassportError(
@@ -237,8 +396,8 @@ export class SupportPassportCardService {
           409
         );
       }
-      this.requireStatus(card, "pending_review");
-      await this.validatePriorForReplacement(storage, card, namespace, principal);
+      requireStatus(card, "pending_review");
+      await validateSupportPassportReplacementPrior(storage, card, namespace, principal);
       const updatedAt = this.now().toISOString();
       await this.requireOwnerLock(lock);
       let approved: boolean;
@@ -246,21 +405,26 @@ export class SupportPassportCardService {
         approved = await storage.writeMemoryFrontmatterIfUnchanged(
           card.memory,
           { status: "active", updated: updatedAt },
-          { actor: principal, reasonCode: "owner-approved" }
+          {
+            actor: principal,
+            reasonCode: parsed.data.reasonCode ?? "owner-approved",
+          }
         );
       } catch (error) {
         const current = await storage.getMemoryById(card.card.cardId);
-        const currentCard = current ? this.projectOwnedCard(current, namespace, principal) : null;
+        const currentCard = current ? projectOwnedCard(current, namespace, principal) : null;
         if (currentCard?.card.status === "active") {
-          return await this.finishCommittedApproval(storage, currentCard, lock, principal, namespace);
+          onCommitted();
+          return await this.finishCommittedApproval(storage, currentCard, lock, principal, namespace, onCommitted);
         }
         throw error;
       }
       if (!approved) {
         const current = await storage.getMemoryById(card.card.cardId);
-        const currentCard = current ? this.projectOwnedCard(current, namespace, principal) : null;
+        const currentCard = current ? projectOwnedCard(current, namespace, principal) : null;
         if (currentCard?.card.status === "active") {
-          return await this.finishCommittedApproval(storage, currentCard, lock, principal, namespace);
+          onCommitted();
+          return await this.finishCommittedApproval(storage, currentCard, lock, principal, namespace, onCommitted);
         }
         throw new SupportPassportError("storage_conflict", "The support card changed before approval.", 409);
       }
@@ -268,11 +432,12 @@ export class SupportPassportCardService {
         ...card.card,
         status: "active",
         updatedAt,
-        revision: this.revisionFor(card.card, "active", updatedAt),
+        revision: revisionFor(card.card, "active", updatedAt),
       };
+      onCommitted();
       try {
         const current = await this.requireCard(storage, card.card.cardId, namespace, principal);
-        return await this.finishCommittedApproval(storage, current, lock, principal, namespace);
+        return await this.finishCommittedApproval(storage, current, lock, principal, namespace, onCommitted);
       } catch (error) {
         if (isStorageConflict(error)) throw error;
         log.warn(
@@ -283,12 +448,18 @@ export class SupportPassportCardService {
     });
   }
 
-  async rejectCard(input: SupportPassportCardMutationInput): Promise<SupportPassportCard> {
-    return await this.changeStatus(input, "pending_review", "rejected");
+  async rejectCard(
+    input: SupportPassportCardMutationInput,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return await this.changeStatus(input, "pending_review", "rejected", "owner-rejected", options);
   }
 
-  async withdrawCard(input: SupportPassportCardMutationInput): Promise<SupportPassportCard> {
-    return await this.changeStatus(input, "active", "archived");
+  async withdrawCard(
+    input: SupportPassportCardMutationInput,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return await this.changeStatus(input, "active", "archived", "owner-withdrew", options);
   }
 
   private async createDraft(
@@ -304,6 +475,9 @@ export class SupportPassportCardService {
       replacedRevision?: string;
       order?: number;
       draftReplacementPrepared?: boolean;
+      generatedBatch?: { batchId: string; size: number };
+      onPersisted?: (card: StoredSupportPassportCard) => void;
+      onCommitted?: () => void;
     },
     lock: HeldFileLockController,
     principal: string,
@@ -311,8 +485,8 @@ export class SupportPassportCardService {
   ): Promise<SupportPassportCard> {
     const now = this.now();
     const reviewBy = input.reviewBy ?? now.toISOString();
-    const storedCards = await this.readStoredCards(storage, lock, principal, namespace);
-    const visibleCards = this.ownerVisibleCards(storedCards);
+    const storedCards = await this.readStoredCards(storage, lock, principal, namespace, input.onCommitted);
+    const visibleCards = ownerListCards(storedCards);
     const replacesVisibleCard = visibleCards.some(
       (item) =>
         (input.replacesDraftId === item.card.cardId && item.card.status === "pending_review") ||
@@ -321,8 +495,34 @@ export class SupportPassportCardService {
     if (visibleCards.length - (replacesVisibleCard ? 1 : 0) >= MAX_OWNER_VISIBLE_CARDS) {
       throw new SupportPassportError("invalid_input", "A support passport can contain at most 100 visible cards.", 400);
     }
-    const maximumOrder = storedCards.reduce((maximum, card) => Math.max(maximum, card.order), -1);
-    const order = input.order ?? maximumOrder + 1;
+    const order = input.order ?? storedCards.reduce((maximum, card) => Math.max(maximum, card.order), -1) + 1;
+    return await this.persistDraft(storage, { ...input, order }, lock, principal, namespace);
+  }
+
+  private async persistDraft(
+    storage: StorageManager,
+    input: {
+      title: string;
+      statement: string;
+      category: SupportPassportCardCategory;
+      reviewBy?: string;
+      sourceMemoryIds: string[];
+      supersedes?: string;
+      replacesDraftId?: string;
+      replacedRevision?: string;
+      order: number;
+      draftReplacementPrepared?: boolean;
+      generatedBatch?: { batchId: string; size: number };
+      onPersisted?: (card: StoredSupportPassportCard) => void;
+      onCommitted?: () => void;
+    },
+    lock: HeldFileLockController,
+    principal: string,
+    namespace: string
+  ): Promise<SupportPassportCard> {
+    const now = this.now();
+    const reviewBy = input.reviewBy ?? now.toISOString();
+    const order = input.order;
     if (!Number.isSafeInteger(order)) {
       throw new SupportPassportError("storage_conflict", "The support card order range is exhausted.", 409);
     }
@@ -338,15 +538,26 @@ export class SupportPassportCardService {
           [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.category]: input.category,
           [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.order]: String(order),
           [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.reviewBy]: reviewBy,
-          [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.sourceMemoryIds]: input.sourceMemoryIds.join(","),
           ...(input.replacesDraftId
-            ? { [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacesDraftId]: input.replacesDraftId }
+            ? {
+                [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacesDraftId]: input.replacesDraftId,
+              }
             : {}),
           ...(input.replacedRevision
-            ? { [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacedRevision]: input.replacedRevision }
+            ? {
+                [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacedRevision]: input.replacedRevision,
+              }
             : {}),
           ...(input.draftReplacementPrepared
-            ? { [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared]: "true" }
+            ? {
+                [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared]: "true",
+              }
+            : {}),
+          ...(input.generatedBatch
+            ? {
+                [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.generatedBatchId]: input.generatedBatch.batchId,
+                [SUPPORT_PASSPORT_ATTRIBUTE_KEYS.generatedBatchSize]: String(input.generatedBatch.size),
+              }
             : {}),
         },
         sourceReason: "support-passport",
@@ -364,46 +575,61 @@ export class SupportPassportCardService {
     if (written.tombstoneBlocked) {
       throw new SupportPassportError("storage_conflict", "The support card needs memory review before use.", 409);
     }
-    return this.projectRequiredCard(written.memory, namespace, principal).card;
+    const stored = projectRequiredCard(written.memory, namespace, principal);
+    input.onPersisted?.(stored);
+    if (!input.generatedBatch) input.onCommitted?.();
+    return stored.card;
   }
 
   private async changeStatus(
     input: SupportPassportCardMutationInput,
     expectedStatus: "pending_review" | "active",
-    nextStatus: "rejected" | "archived"
+    nextStatus: "rejected" | "archived",
+    defaultReasonCode: string,
+    options: { signal?: AbortSignal; onCommitted?: () => void }
   ): Promise<SupportPassportCard> {
     const parsed = SupportPassportCardMutationInputSchema.safeParse(input);
     if (!parsed.success) throw invalidInput();
     const { principal, namespace, storage } = await this.resolveOwnerScope(parsed.data.principal);
+    const onCommitted = once(options.onCommitted);
     return await withSupportPassportOwnerLock(storage, { namespace, principal }, async (lock) => {
+      options.signal?.throwIfAborted();
       let card = await this.requireCard(storage, parsed.data.cardId, namespace, principal);
-      this.requireRevision(card, parsed.data.expectedRevision);
-      this.requireStatus(card, expectedStatus);
+      requireRevision(card, parsed.data.expectedRevision);
+      requireStatus(card, expectedStatus);
       if (expectedStatus === "pending_review" && nextStatus === "rejected") {
-        await this.rejectPendingReplacementForPredecessor(storage, card, lock, principal, namespace);
+        await this.rejectPendingReplacementForPredecessor(storage, card, lock, principal, namespace, onCommitted);
         card = await this.requireCard(storage, card.card.cardId, namespace, principal);
-        this.requireRevision(card, parsed.data.expectedRevision);
-        this.requireStatus(card, expectedStatus);
+        requireRevision(card, parsed.data.expectedRevision);
+        requireStatus(card, expectedStatus);
       }
       if (
         expectedStatus === "pending_review" ||
         (expectedStatus === "active" && (card.replacesDraftId || card.memory.frontmatter.supersedes))
       ) {
-        card = this.projectRequiredCard(
-          await this.recoverReplacementTransition(storage, card.memory, lock, principal, namespace, {
-            rollbackConflictedApproval: expectedStatus !== "active",
-          }),
+        card = projectRequiredCard(
+          await this.recoverReplacementTransition(
+            storage,
+            card.memory,
+            lock,
+            principal,
+            namespace,
+            {
+              rollbackConflictedApproval: expectedStatus !== "active",
+            },
+            onCommitted
+          ),
           namespace,
           principal
         );
       }
       if (card.card.status === nextStatus) return card.card;
-      this.requireStatus(card, expectedStatus);
+      requireStatus(card, expectedStatus);
       if (expectedStatus === "active" && nextStatus === "archived") {
-        await this.rejectPendingReplacementForPredecessor(storage, card, lock, principal, namespace);
+        await this.rejectPendingReplacementForPredecessor(storage, card, lock, principal, namespace, onCommitted);
         card = await this.requireCard(storage, card.card.cardId, namespace, principal);
-        this.requireRevision(card, parsed.data.expectedRevision);
-        this.requireStatus(card, expectedStatus);
+        requireRevision(card, parsed.data.expectedRevision);
+        requireStatus(card, expectedStatus);
       }
       const updatedAt = this.now().toISOString();
       await this.requireOwnerLock(lock);
@@ -414,7 +640,10 @@ export class SupportPassportCardService {
           updated: updatedAt,
           ...(nextStatus === "archived" ? { archivedAt: updatedAt } : {}),
         },
-        { actor: principal, reasonCode: nextStatus === "archived" ? "owner-withdrew" : "owner-rejected" }
+        {
+          actor: principal,
+          reasonCode: parsed.data.reasonCode ?? defaultReasonCode,
+        }
       );
       if (!changed)
         throw new SupportPassportError(
@@ -422,41 +651,19 @@ export class SupportPassportCardService {
           "The support card changed before the request completed.",
           409
         );
+      onCommitted();
       return {
         ...card.card,
         status: nextStatus,
         updatedAt,
-        revision: this.revisionFor(card.card, nextStatus, updatedAt),
+        revision: revisionFor(card.card, nextStatus, updatedAt),
       };
     });
   }
 
-  private revisionFor(card: SupportPassportCard, status: SupportPassportCard["status"], updatedAt: string): string {
-    return computeSupportPassportCardRevision({
-      cardId: card.cardId,
-      title: card.title,
-      statement: card.statement,
-      category: card.category,
-      status,
-      updatedAt,
-      reviewBy: card.reviewBy,
-    });
-  }
-
   private async resolveOwnerScope(principal: string): Promise<SupportPassportOwnerScope> {
-    const requestedPrincipal = SupportPassportListCardsInputSchema.safeParse({ principal });
     const owner = await this.resolveOwner(principal);
-    const namespace = SupportPassportNamespaceSchema.safeParse(owner.namespace);
-    const ownerPrincipal = SupportPassportListCardsInputSchema.safeParse({ principal: owner.principal });
-    if (
-      !requestedPrincipal.success ||
-      !namespace.success ||
-      !ownerPrincipal.success ||
-      ownerPrincipal.data.principal !== requestedPrincipal.data.principal
-    ) {
-      throw new SupportPassportError("card_data_invalid", "The support passport owner scope is invalid.", 500);
-    }
-    return { ...owner, principal: ownerPrincipal.data.principal, namespace: namespace.data };
+    return validateOwnerScope(owner, principal);
   }
 
   private async rejectCreatedDraft(
@@ -465,7 +672,8 @@ export class SupportPassportCardService {
     reasonCode: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     try {
       const current = await this.requireCard(storage, cardId, namespace, principal);
@@ -475,7 +683,8 @@ export class SupportPassportCardService {
         { status: "rejected", updated: this.now().toISOString() },
         { actor: principal, reasonCode }
       );
-      if (!rejected) log.warn("support passport could not roll back a replacement draft");
+      if (rejected) onCommitted?.();
+      else log.warn("support passport could not roll back a replacement draft");
     } catch (error) {
       log.warn(
         `support passport could not roll back a replacement draft: ${error instanceof Error ? error.message : String(error)}`
@@ -483,164 +692,70 @@ export class SupportPassportCardService {
     }
   }
 
-  private async requireCard(
+  private async rejectGeneratedDraft(
     storage: StorageManager,
     cardId: string,
-    namespace: string,
-    principal: string
-  ): Promise<StoredSupportPassportCard> {
-    const stored = await storage.getMemoryById(cardId);
-    const card = stored ? this.projectOwnedCard(stored, namespace, principal) : null;
-    if (!card) throw new SupportPassportError("card_not_found", "The support card was not found.", 404);
-    return card;
-  }
-
-  private projectRequiredCard(memory: MemoryFile, namespace: string, principal: string): StoredSupportPassportCard {
-    const card = projectSupportPassportCard(memory);
-    if (!card) throw new SupportPassportError("card_data_invalid", "The support card data is invalid.", 500);
-    if (
-      card.namespace !== namespace ||
-      card.owner !== computeSupportPassportOwnerKey(principal)
-    ) {
-      throw new SupportPassportError("card_not_found", "The support card was not found.", 404);
-    }
-    return card;
-  }
-
-  private projectOwnedCard(memory: MemoryFile, namespace: string, principal: string): StoredSupportPassportCard | null {
-    const card = projectSupportPassportCard(memory);
-    return card?.namespace === namespace &&
-      card.owner === computeSupportPassportOwnerKey(principal)
-      ? card
-      : null;
-  }
-
-  private ownsMemory(memory: MemoryFile, namespace: string, principal: string): boolean {
-    const attributes = memory.frontmatter.structuredAttributes;
-    return (
-      attributes !== undefined &&
-      decodeSupportPassportNamespaceAttributes(attributes) === namespace &&
-      attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.owner] === computeSupportPassportOwnerKey(principal)
-    );
-  }
-
-  private async readProjectedCards(
-    storage: StorageManager,
-    namespace: string,
-    principal: string
-  ): Promise<StoredSupportPassportCard[]> {
-    const owner = computeSupportPassportOwnerKey(principal);
-    const projected = (await storage.readAllMemories())
-      .map(projectSupportPassportCard)
-      .filter((card): card is StoredSupportPassportCard => card?.namespace === namespace && card.owner === owner);
-    const ids = new Set<string>();
-    for (const item of projected) {
-      if (ids.has(item.card.cardId)) {
-        throw new SupportPassportError("card_data_invalid", "Support card IDs must be unique.", 500);
-      }
-      ids.add(item.card.cardId);
-    }
-    return projected;
-  }
-
-  private requireRevision(card: StoredSupportPassportCard, expectedRevision: string): void {
-    if (card.card.revision !== expectedRevision) {
-      throw new SupportPassportError("revision_conflict", "The support card changed after it was loaded.", 409);
-    }
-  }
-
-  private requireStatus(card: StoredSupportPassportCard, status: SupportPassportCard["status"]): void {
-    if (card.card.status !== status) {
-      throw new SupportPassportError("invalid_card_status", `The support card must have status ${status}.`, 409);
+    lock: HeldFileLockController,
+    principal: string,
+    namespace: string
+  ): Promise<boolean> {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const memory = await storage.getMemoryById(cardId);
+      if (!memory) return true;
+      const stored = projectOwnedCard(memory, namespace, principal);
+      if (!stored) return false;
+      if (stored.card.status === "rejected") return true;
+      if (stored.card.status !== "pending_review") return false;
+      await this.requireOwnerLock(lock);
+      const rejected = await storage.writeMemoryFrontmatterIfUnchanged(
+        memory,
+        { status: "rejected", updated: this.now().toISOString() },
+        { actor: principal, reasonCode: "draft-batch-failed" }
+      );
+      if (rejected) return true;
     }
+    return false;
   }
 
   private async readStoredCards(
     storage: StorageManager,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<StoredSupportPassportCard[]> {
     const initialVersion = storage.getCorpusScanVersion();
     const initial = await storage.readAllMemories();
+    await recoverSupportPassportGeneratedBatches(
+      this.generatedBatchContext(storage, lock, principal, namespace, onCommitted),
+      initial
+    );
     for (const memory of initial) {
-      const card = this.projectOwnedCard(memory, namespace, principal);
-      if (card) await this.recoverReplacementTransition(storage, memory, lock, principal, namespace);
+      const card = projectOwnedCard(memory, namespace, principal);
+      if (card) {
+        await this.recoverReplacementTransition(storage, memory, lock, principal, namespace, {}, onCommitted);
+      }
     }
     const memories: MemoryFile[] =
       storage.getCorpusScanVersion() === initialVersion ? initial : await storage.readAllMemories();
-    const owner = computeSupportPassportOwnerKey(principal);
-    const projected = memories
-      .map(projectSupportPassportCard)
-      .filter((card): card is StoredSupportPassportCard => card?.namespace === namespace && card.owner === owner);
-    const ids = new Set<string>();
-    for (const item of projected) {
-      if (ids.has(item.card.cardId)) {
-        throw new SupportPassportError("card_data_invalid", "Support card IDs must be unique.", 500);
-      }
-      ids.add(item.card.cardId);
-    }
-    return projected;
-  }
-
-  private ownerVisibleCards(storedCards: StoredSupportPassportCard[]): StoredSupportPassportCard[] {
-    const visibleCards = storedCards.filter(
-      (item) => OWNER_VISIBLE_STATUSES.has(item.card.status) && !item.draftReplacementPrepared
-    );
-    if (visibleCards.length <= MAX_OWNER_VISIBLE_CARDS) return visibleCards;
-    const activeCardsWithPendingReplacements = new Set(
-      visibleCards
-        .filter((item) => item.card.status === "pending_review")
-        .map((item) => item.memory.frontmatter.supersedes)
-        .filter((cardId): cardId is string => typeof cardId === "string")
-    );
-    return visibleCards.filter(
-      (item) => item.card.status !== "active" || !activeCardsWithPendingReplacements.has(item.card.cardId)
-    );
+    return await projectCommittedSupportPassportCards(storage, memories, namespace, principal);
   }
 
-  private async preparePriorForReplacement(
+  private generatedBatchContext(
     storage: StorageManager,
-    replacement: StoredSupportPassportCard,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
-  ): Promise<string | null> {
-    const priorId = replacement.memory.frontmatter.supersedes;
-    if (!priorId) return null;
-    const priorMemory = await storage.getMemoryById(priorId);
-    const priorIsOwned = priorMemory ? this.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 = this.now().toISOString();
-    await this.requireOwnerLock(lock);
-    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);
-    }
-    return priorId;
+    namespace: string,
+    onCommitted?: () => void
+  ) {
+    return {
+      storage,
+      principal,
+      namespace,
+      now: this.now,
+      requireOwnerLock: async () => await this.requireOwnerLock(lock),
+      ...(onCommitted ? { onCommitted } : {}),
+    };
   }
 
   private async rejectPendingReplacementForPredecessor(
@@ -648,12 +763,13 @@ export class SupportPassportCardService {
     predecessor: StoredSupportPassportCard,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     const storedCards =
       predecessor.card.status === "active"
-        ? await this.readStoredCards(storage, lock, principal, namespace)
-        : await this.readProjectedCards(storage, namespace, principal);
+        ? await this.readStoredCards(storage, lock, principal, namespace, onCommitted)
+        : await readCommittedSupportPassportCards(storage, namespace, principal);
     const replacements = storedCards.filter((item) => {
       if (item.card.status !== "pending_review") return false;
       return predecessor.card.status === "pending_review"
@@ -678,44 +794,27 @@ export class SupportPassportCardService {
         reasonCode: predecessor.card.status === "pending_review" ? "source-draft-rejected" : "predecessor-withdrawn",
       }
     );
-    if (rejected) return;
+    if (rejected) {
+      onCommitted?.();
+      return;
+    }
     const current = await storage.getMemoryById(replacement.card.cardId);
-    const currentCard = current ? this.projectOwnedCard(current, namespace, principal) : null;
+    const currentCard = current ? projectOwnedCard(current, namespace, principal) : null;
     if (currentCard?.card.status !== "rejected") {
       throw new SupportPassportError("storage_conflict", "The pending support card edit could not be cancelled.", 409);
     }
   }
 
-  private async validatePriorForReplacement(
-    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 ? this.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);
-    }
-  }
-
   private async recoverReplacementTransition(
     storage: StorageManager,
     memory: MemoryFile,
     lock: HeldFileLockController,
     principal: string,
     namespace: string,
-    options: { rollbackConflictedApproval?: boolean } = {}
+    options: { rollbackConflictedApproval?: boolean } = {},
+    onCommitted?: () => void
   ): Promise<MemoryFile> {
-    const replacement = this.projectOwnedCard(memory, namespace, principal);
+    const replacement = projectOwnedCard(memory, namespace, principal);
     if (replacement?.card.status !== "pending_review" && replacement?.card.status !== "active") return memory;
     if (!replacement.replacesDraftId && !memory.frontmatter.supersedes) return memory;
     if (
@@ -724,9 +823,9 @@ export class SupportPassportCardService {
     ) {
       return memory;
     }
-    await this.recoverReplacedDraft(storage, replacement, lock, principal, namespace);
+    await this.recoverReplacedDraft(storage, replacement, lock, principal, namespace, onCommitted);
     const currentMemory = (await storage.getMemoryById(replacement.card.cardId)) ?? memory;
-    const currentCard = this.projectOwnedCard(currentMemory, namespace, principal);
+    const currentCard = projectOwnedCard(currentMemory, namespace, principal);
     if (currentCard?.card.status !== "pending_review" && currentCard?.card.status !== "active") {
       return currentMemory;
     }
@@ -736,7 +835,7 @@ export class SupportPassportCardService {
       const prior = await storage.getMemoryById(priorId);
       if (
         prior &&
-        this.ownsMemory(prior, namespace, principal) &&
+        ownsMemory(prior, namespace, principal) &&
         prior.frontmatter.status === "superseded" &&
         prior.frontmatter.supersededBy === replacement.card.cardId
       ) {
@@ -746,17 +845,18 @@ export class SupportPassportCardService {
           replacement.card.cardId,
           lock,
           principal,
-          namespace
+          namespace,
+          onCommitted
         );
       }
       return (await storage.getMemoryById(replacement.card.cardId)) ?? currentMemory;
     }
     try {
-      await this.completeReplacementAfterActivation(storage, currentCard, lock, principal, namespace);
+      await this.completeReplacementAfterActivation(storage, currentCard, lock, principal, namespace, onCommitted);
     } catch (error) {
       if (!isStorageConflict(error)) throw error;
       if (options.rollbackConflictedApproval === false) throw error;
-      await this.rollbackConflictedApproval(storage, currentCard.card.cardId, lock, principal, namespace);
+      await this.rollbackConflictedApproval(storage, currentCard.card.cardId, lock, principal, namespace, onCommitted);
     }
     return (await storage.getMemoryById(replacement.card.cardId)) ?? currentMemory;
   }
@@ -766,13 +866,33 @@ export class SupportPassportCardService {
     replacement: StoredSupportPassportCard,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
-    const priorId = await this.preparePriorForReplacement(storage, replacement, lock, principal, namespace);
-    if (priorId && !(await this.completePriorRetirement(storage, priorId, replacement, lock, principal, namespace))) {
+    const priorId = await prepareSupportPassportReplacementPrior({
+      storage,
+      replacement,
+      principal,
+      namespace,
+      now: this.now,
+      requireOwnerLock: () => this.requireOwnerLock(lock),
+      onCommitted,
+    });
+    if (
+      priorId &&
+      !(await completeSupportPassportReplacementPrior({
+        storage,
+        priorId,
+        replacement,
+        principal,
+        namespace,
+        requireOwnerLock: () => this.requireOwnerLock(lock),
+      }))
+    ) {
       throw new SupportPassportError("storage_conflict", "The prior support card changed before replacement.", 409);
     }
-    await this.markReplacementComplete(storage, replacement.card.cardId, lock, principal, namespace);
+    if (priorId) onCommitted?.();
+    await this.markReplacementComplete(storage, replacement.card.cardId, lock, principal, namespace, onCommitted);
   }
 
   private async finishCommittedApproval(
@@ -780,15 +900,23 @@ export class SupportPassportCardService {
     replacement: StoredSupportPassportCard,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<SupportPassportCard> {
     try {
       if (replacement.replacesDraftId || replacement.memory.frontmatter.supersedes) {
-        await this.completeReplacementAfterActivation(storage, replacement, lock, principal, namespace);
+        await this.completeReplacementAfterActivation(storage, replacement, lock, principal, namespace, onCommitted);
       }
     } catch (error) {
       if (isStorageConflict(error)) {
-        await this.rollbackConflictedApproval(storage, replacement.card.cardId, lock, principal, namespace);
+        await this.rollbackConflictedApproval(
+          storage,
+          replacement.card.cardId,
+          lock,
+          principal,
+          namespace,
+          onCommitted
+        );
         throw error;
       }
       log.warn(
@@ -803,7 +931,8 @@ export class SupportPassportCardService {
     replacementId: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     const replacement = await this.requireCard(storage, replacementId, namespace, principal);
     if (replacement.card.status !== "active") return;
@@ -820,54 +949,19 @@ export class SupportPassportCardService {
         409
       );
     }
+    onCommitted?.();
     const priorId = replacement.memory.frontmatter.supersedes;
     if (priorId) {
-      await this.restorePriorAfterApprovalFailure(storage, priorId, replacementId, lock, principal, namespace);
-    }
-  }
-
-  private async completePriorRetirement(
-    storage: StorageManager,
-    priorId: string,
-    replacement: StoredSupportPassportCard,
-    lock: HeldFileLockController,
-    principal: string,
-    namespace: string
-  ): Promise<boolean> {
-    const replacementId = replacement.card.cardId;
-    const prior = await storage.getMemoryById(priorId);
-    if (
-      !prior ||
-      !this.ownsMemory(prior, namespace, principal) ||
-      prior.frontmatter.status !== "superseded" ||
-      prior.frontmatter.supersededBy !== replacementId
-    ) {
-      return false;
+      await this.restorePriorAfterApprovalFailure(
+        storage,
+        priorId,
+        replacementId,
+        lock,
+        principal,
+        namespace,
+        onCommitted
+      );
     }
-    await this.requireOwnerLock(lock);
-    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;
   }
 
   private async recoverReplacedDraft(
@@ -875,11 +969,12 @@ export class SupportPassportCardService {
     replacement: StoredSupportPassportCard,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     if (!replacement.replacesDraftId) return;
     const replacedDraft = await storage.getMemoryById(replacement.replacesDraftId);
-    const projectedDraft = replacedDraft ? this.projectOwnedCard(replacedDraft, namespace, principal) : null;
+    const projectedDraft = replacedDraft ? projectOwnedCard(replacedDraft, namespace, principal) : null;
     if (
       replacedDraft &&
       projectedDraft?.card.status === "pending_review" &&
@@ -892,27 +987,42 @@ export class SupportPassportCardService {
         { actor: principal, reasonCode: "complete-draft-replacement" }
       );
       if (rejected) {
-        await this.finishPreparedDraftReplacement(storage, replacement.card.cardId, lock, principal, namespace);
+        onCommitted?.();
+        await this.finishPreparedDraftReplacement(
+          storage,
+          replacement.card.cardId,
+          lock,
+          principal,
+          namespace,
+          onCommitted
+        );
         return;
       }
     }
     const currentDraft = await storage.getMemoryById(replacement.replacesDraftId);
     if (
       currentDraft &&
-      this.ownsMemory(currentDraft, namespace, principal) &&
+      ownsMemory(currentDraft, namespace, principal) &&
       currentDraft.frontmatter.status === "rejected"
     ) {
-      await this.finishPreparedDraftReplacement(storage, replacement.card.cardId, lock, principal, namespace);
+      await this.finishPreparedDraftReplacement(
+        storage,
+        replacement.card.cardId,
+        lock,
+        principal,
+        namespace,
+        onCommitted
+      );
       return;
     }
     if (
       currentDraft &&
-      this.ownsMemory(currentDraft, namespace, principal) &&
+      ownsMemory(currentDraft, namespace, principal) &&
       currentDraft.frontmatter.status === "pending_review"
     ) {
       throw new SupportPassportError("storage_conflict", "The replaced draft changed during recovery.", 409);
     }
-    await this.rejectOrphanedReplacement(storage, replacement.card.cardId, lock, principal, namespace);
+    await this.rejectOrphanedReplacement(storage, replacement.card.cardId, lock, principal, namespace, onCommitted);
   }
 
   private async finishPreparedDraftReplacement(
@@ -920,11 +1030,14 @@ export class SupportPassportCardService {
     replacementId: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<SupportPassportCard> {
     const replacement = await this.requireCard(storage, replacementId, namespace, principal);
     if (!replacement.draftReplacementPrepared) return replacement.card;
-    const structuredAttributes = { ...replacement.memory.frontmatter.structuredAttributes };
+    const structuredAttributes = {
+      ...replacement.memory.frontmatter.structuredAttributes,
+    };
     delete structuredAttributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared];
     await this.requireOwnerLock(lock);
     const finished = await storage.writeMemoryFrontmatterIfUnchanged(
@@ -933,8 +1046,15 @@ export class SupportPassportCardService {
       { actor: principal, reasonCode: "draft-replacement-complete" }
     );
     if (finished) {
-      return this.projectRequiredCard(
-        { ...replacement.memory, frontmatter: { ...replacement.memory.frontmatter, structuredAttributes } },
+      onCommitted?.();
+      return projectRequiredCard(
+        {
+          ...replacement.memory,
+          frontmatter: {
+            ...replacement.memory.frontmatter,
+            structuredAttributes,
+          },
+        },
         namespace,
         principal
       ).card;
@@ -949,18 +1069,22 @@ export class SupportPassportCardService {
     replacementId: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     const currentReplacement = await this.requireCard(storage, replacementId, namespace, principal);
     if (currentReplacement.card.status === "rejected") return;
-    this.requireStatus(currentReplacement, "pending_review");
+    requireStatus(currentReplacement, "pending_review");
     await this.requireOwnerLock(lock);
     const rejected = await storage.writeMemoryFrontmatterIfUnchanged(
       currentReplacement.memory,
       { status: "rejected", updated: this.now().toISOString() },
       { actor: principal, reasonCode: "replaced-draft-approved" }
     );
-    if (rejected) return;
+    if (rejected) {
+      onCommitted?.();
+      return;
+    }
     const latest = await storage.getMemoryById(replacementId);
     if (latest?.frontmatter.status !== "rejected") {
       throw new SupportPassportError("storage_conflict", "The orphaned replacement could not be rejected.", 409);
@@ -973,15 +1097,16 @@ export class SupportPassportCardService {
     replacementId: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     const replacement = await storage.getMemoryById(replacementId);
-    if (replacement && !this.ownsMemory(replacement, namespace, principal)) {
+    if (replacement && !ownsMemory(replacement, namespace, principal)) {
       throw new SupportPassportError("storage_conflict", "The replacement support card changed ownership.", 409);
     }
     if (replacement?.frontmatter.status === "active") return;
     const prior = await storage.getMemoryById(priorId);
-    if (prior && !this.ownsMemory(prior, namespace, principal)) {
+    if (prior && !ownsMemory(prior, namespace, principal)) {
       throw new SupportPassportError("storage_conflict", "The prior support card changed ownership.", 409);
     }
     if (prior?.frontmatter.status === "active" && prior.frontmatter.supersededBy === undefined) return;
@@ -1001,7 +1126,10 @@ export class SupportPassportCardService {
       },
       { actor: principal, reasonCode: "replacement-activation-failed" }
     );
-    if (restored) return;
+    if (restored) {
+      onCommitted?.();
+      return;
+    }
     const currentPrior = await storage.getMemoryById(priorId);
     if (currentPrior?.frontmatter.status === "active" && currentPrior.frontmatter.supersededBy === undefined) return;
     throw new SupportPassportError("storage_conflict", "The prior support card could not be restored.", 409);
@@ -1012,7 +1140,8 @@ export class SupportPassportCardService {
     replacementId: string,
     lock: HeldFileLockController,
     principal: string,
-    namespace: string
+    namespace: string,
+    onCommitted?: () => void
   ): Promise<void> {
     const replacement = await this.requireCard(storage, replacementId, namespace, principal);
     if (
@@ -1032,11 +1161,24 @@ export class SupportPassportCardService {
       },
       { actor: principal, reasonCode: "replacement-side-effects-complete" }
     );
-    if (!marked) log.warn("support passport could not mark replacement side effects complete");
+    if (marked) onCommitted?.();
+    else log.warn("support passport could not mark replacement side effects complete");
   }
 
   private async requireOwnerLock(lock: HeldFileLockController): Promise<void> {
     if (await lock.refresh()) return;
     throw new SupportPassportError("storage_conflict", "The support passport lock changed. Try again.", 409);
   }
+
+  private async requireCard(
+    storage: StorageManager,
+    cardId: string,
+    namespace: string,
+    principal: string
+  ): Promise<StoredSupportPassportCard> {
+    const memory = await storage.getMemoryById(cardId);
+    const card = memory ? projectOwnedCard(memory, namespace, principal) : null;
+    if (card && (await isCommittedGeneratedCard(storage, card))) return card;
+    throw new SupportPassportError("card_not_found", "The support card was not found.", 404);
+  }
 }