@remnic/core 9.54.5 → 9.54.7

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

@@ -11,6 +11,7 @@ import {
   SupportPassportCardStatusSchema,
   SupportPassportMemoryIdSchema,
   SupportPassportNamespaceSchema,
+  SupportPassportSourceMemoryIdSchema,
   computeSupportPassportCardRevision,
 } from "./contracts.js";
 
@@ -81,6 +82,8 @@ export const SUPPORT_PASSPORT_ATTRIBUTE_KEYS = Object.freeze({
   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";
@@ -156,20 +159,33 @@ export interface StoredSupportPassportCard {
   replacesDraftId?: string;
   replacedRevision?: string;
   draftReplacementPrepared: boolean;
+  generatedBatchId?: string;
+  generatedBatchSize?: number;
 }
 
 export function computeSupportPassportOwnerKey(principal: string): string {
   return createHash("sha256").update(principal).digest("hex");
 }
 
-function parseSourceMemoryIds(value: string | undefined): string[] | null {
-  if (value === undefined) return null;
-  if (value === "") return [];
-  const rawIds = value.split(",");
+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 = SupportPassportMemoryIdSchema.safeParse(rawId);
+    const parsed = SupportPassportSourceMemoryIdSchema.safeParse(rawId);
     if (!parsed.success) return null;
     normalized.push(parsed.data);
   }
@@ -186,35 +202,67 @@ interface SupportPassportCardMetadata {
   replacesDraftId?: string;
   replacedRevision?: string;
   draftReplacementPrepared: boolean;
+  generatedBatchId?: string;
+  generatedBatchSize?: number;
 }
 
-function parseSupportPassportCardMetadata(memory: Pick<MemoryFile, "frontmatter">): SupportPassportCardMetadata | null {
+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;
+  if (
+    !attributes ||
+    frontmatter.blockedBy ||
+    frontmatter.archivedAt ||
+    frontmatter.supersededBy
+  )
+    return null;
 
-  const category = SupportPassportCardCategorySchema.safeParse(attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.category]);
+  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(attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.sourceMemoryIds]);
+  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];
+  const rawReplacesDraftId =
+    attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.replacesDraftId];
   if (rawReplacesDraftId !== undefined) {
-    const parsedReplacesDraftId = SupportPassportMemoryIdSchema.safeParse(rawReplacesDraftId);
+    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];
+  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 ||
@@ -228,7 +276,10 @@ function parseSupportPassportCardMetadata(memory: Pick<MemoryFile, "frontmatter"
     !sourceMemoryIds
   )
     return null;
-  const fields = SupportPassportCardSchema.omit({ revision: true, statement: true }).safeParse({
+  const fields = SupportPassportCardSchema.omit({
+    revision: true,
+    statement: true,
+  }).safeParse({
     cardId: frontmatter.id,
     title: attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.title],
     category: category.data,
@@ -245,7 +296,11 @@ function parseSupportPassportCardMetadata(memory: Pick<MemoryFile, "frontmatter"
     owner,
     replacesDraftId,
     replacedRevision,
-    draftReplacementPrepared: attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared] === "true",
+    draftReplacementPrepared:
+      attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.draftReplacementPrepared] ===
+      "true",
+    generatedBatchId,
+    generatedBatchSize,
   };
 }
 
@@ -258,7 +313,9 @@ export function hasLiveSupportPassportCard(memory: Pick<MemoryFile, "frontmatter
   }).success;
 }
 
-export function projectSupportPassportCard(memory: MemoryFile): StoredSupportPassportCard | null {
+export function projectSupportPassportCard(
+  memory: MemoryFile,
+): StoredSupportPassportCard | null {
   const metadata = parseSupportPassportCardMetadata(memory);
   if (!metadata) return null;
 
@@ -266,7 +323,9 @@ export function projectSupportPassportCard(memory: MemoryFile): StoredSupportPas
     ...metadata.fields,
     statement: stripAttributesSuffix(memory.content),
   };
-  const normalized = SupportPassportCardSchema.omit({ revision: true }).safeParse(fields);
+  const normalized = SupportPassportCardSchema.omit({
+    revision: true,
+  }).safeParse(fields);
   if (!normalized.success) return null;
   const parsed = SupportPassportCardSchema.safeParse({
     ...normalized.data,
@@ -283,5 +342,7 @@ export function projectSupportPassportCard(memory: MemoryFile): StoredSupportPas
     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);
+});