@remnic/core 9.54.4 → 9.54.6

package/src/orchestration/workspace-ops.ts

@@ -33,6 +33,7 @@ import { evaluateMemoryActionPolicy } from "../memory-action-policy.js";
 import { NamespaceStorageRouter } from "../namespaces/storage.js";
 import { namespaceCollectionName } from "../namespaces/search.js";
 import { parseMemoryActionEligibilityContext } from "../schemas.js";
+import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 import type { SearchBackend } from "../search/port.js";
 import { type AccessTrackingEntry, type MemoryActionEvent, type MemoryFile, type PluginConfig, confidenceTier } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
@@ -371,41 +372,16 @@ export class WorkspaceOpsCoordinator {
             const fullPath = path.join(dateDir, entry.name);
             try {
               assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
-              const raw = await readFile(fullPath, "utf-8");
-              const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-              if (!fmMatch) continue;
-              const fmBlock = fmMatch[1];
-              const content = fmMatch[2].trim();
-              const fm: Record<string, string> = {};
-              for (const line of fmBlock.split("\n")) {
-                const colonIdx = line.indexOf(":");
-                if (colonIdx === -1) continue;
-                fm[line.slice(0, colonIdx).trim()] = line
-                  .slice(colonIdx + 1)
-                  .trim();
-              }
-              const created = fm.created || "unknown";
-              const createdAt = parseFiniteDate(created);
+              const memory = await storage.readMemoryByPath(fullPath);
+              if (!memory || isSupportPassportPrivateMemory(memory)) continue;
+              const createdAt = parseFiniteDate(memory.frontmatter.created);
               if (
                 createdAt &&
                 formatDateInTimeZone(createdAt, timeZone) !== targetLocalDate
               ) {
                 continue;
               }
-              facts.push({
-                path: fullPath,
-                frontmatter: {
-                  id: fm.id || path.basename(entry.name, ".md"),
-                  category: (fm.category as any) || "fact",
-                  created,
-                  updated: fm.updated || created,
-                  source: fm.source || "unknown",
-                  confidence: parseFloat(fm.confidence || "0.8"),
-                  confidenceTier: (fm.confidenceTier as any) || "implied",
-                  tags: [],
-                },
-                content,
-              });
+              facts.push(memory);
             } catch {
               // Skip unreadable files
             }

package/src/orchestrator.ts

@@ -1116,6 +1116,13 @@ export class Orchestrator {
     return this.storageRouter.storageFor(ns);
   }
 
+  filterPrivateSearchResults = (
+    results: QmdSearchResult[], namespaces: readonly string[] = [], preserveUnresolved = false,
+    visibilityCache?: Map<string, boolean>,
+  ) => this.qmdResultResolver.filterPrivateSearchResults(
+    results, this.storage, namespaces, preserveUnresolved, visibilityCache,
+  );
+
   private configuredNamespaceList(): string[] {
     // #1521: delegates to the scope-module resolver. The inline derivation is
     // retired so the adHocNamespaceResolutions ratchet no longer counts this
@@ -3784,14 +3791,6 @@ export class Orchestrator {
       .filter((id): id is string => id !== null);
   }
 
-  // ---------------------------------------------------------------------------
-  // Contradiction Detection (Phase 2B)
-  // ---------------------------------------------------------------------------
-
-  // ---------------------------------------------------------------------------
-  // Feedback (v2.2)
-  // ---------------------------------------------------------------------------
-
   async recordMemoryFeedback(
     memoryId: string,
     vote: "up" | "down",

package/src/relay/mission-access.test.ts

@@ -367,25 +367,25 @@ test("Relay write quota releases the exact reservation when timestamps collide",
     adminConsoleEnabled: false,
   });
   const internals = server as unknown as {
-    writeLimiter: { slotsFor(principal?: string): ReadonlyArray<{ readonly recordedAt: number }> };
-    reserveWriteRateLimitSlot: () => () => void;
+    writeLimiter: {
+      slotsFor(principal?: string): ReadonlyArray<{ readonly recordedAt: number }>;
+      inFlightFor(principal?: string): number;
+    };
+    reserveWriteRateLimitSlot: () => { commit(): void; release(): void };
   };
   const originalNow = Date.now;
   try {
     Date.now = () => 1_754_000_000_000;
-    const releaseCommitted = internals.reserveWriteRateLimitSlot();
+    const committed = internals.reserveWriteRateLimitSlot();
+    committed.commit();
     const committedSlot = internals.writeLimiter.slotsFor()[0];
-    const releaseFailed = internals.reserveWriteRateLimitSlot();
-    const failedSlot = internals.writeLimiter.slotsFor()[1];
+    const failed = internals.reserveWriteRateLimitSlot();
     assert.ok(committedSlot);
-    assert.ok(failedSlot);
-    assert.notEqual(committedSlot, failedSlot);
+    assert.equal(internals.writeLimiter.inFlightFor(), 1);
 
-    releaseFailed();
+    failed.release();
     assert.deepEqual(internals.writeLimiter.slotsFor(), [committedSlot]);
-
-    releaseCommitted();
-    assert.deepEqual(internals.writeLimiter.slotsFor(), []);
+    assert.equal(internals.writeLimiter.inFlightFor(), 0);
   } finally {
     Date.now = originalNow;
   }

package/src/relay/mission-ui.test.ts

@@ -62,7 +62,9 @@ test("Relay Mission Control serves both aliases from one exact static allow-list
         });
         assert.equal(authorizedShell.status, 200);
         assert.equal(authorizedShell.headers.get("cache-control"), "private, no-store");
-        assert.match(await authorizedShell.text(), /__REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN__="relay-token"/);
+        const authorizedShellText = await authorizedShell.text();
+        assert.match(authorizedShellText, /Object\.defineProperty\(window,key/);
+        assert.match(authorizedShellText, /\}\)\("relay-token",document\.currentScript\)/);
 
         const expectedAssets = new Map([
           ["relay.css", /^text\/css/],

package/src/storage/supersession-audit.ts

@@ -2,6 +2,7 @@ import { readdir } from "node:fs/promises";
 import type { Dirent } from "node:fs";
 import path from "node:path";
 
+import { stripAttributesSuffix } from "../structured-attributes.js";
 import type { MemoryFile } from "../types.js";
 import { isErrnoCode } from "../utils/errno.js";
 
@@ -15,6 +16,7 @@ export async function hasSupersessionAudit(
   oldMemoryId: string,
   newMemoryId: string,
   auditBody: string,
+  structuredAttributes?: Record<string, string>
 ): Promise<boolean> {
   let entries: Dirent[];
   try {
@@ -32,7 +34,11 @@ export async function hasSupersessionAudit(
       (memory.frontmatter.sourceMemoryId === oldMemoryId ||
         (memory.frontmatter.sourceMemoryId === undefined && memory.frontmatter.lineage?.includes(oldMemoryId))) &&
       memory.frontmatter.lineage?.includes(newMemoryId) &&
-      memory.content === auditBody
+      stripAttributesSuffix(memory.content) === auditBody &&
+      (structuredAttributes === undefined ||
+        Object.entries(structuredAttributes).every(
+          ([key, value]) => memory.frontmatter.structuredAttributes?.[key] === value
+        ))
     ) {
       return true;
     }

package/src/storage/supersession-side-effects.ts

@@ -31,6 +31,8 @@ export interface SupersessionSideEffectOptions {
   exactReplay: boolean;
   currentBefore: MemoryFile;
   updatedFm: MemoryFrontmatter;
+  actor?: string;
+  audit?: SupersessionAuditOptions;
   citationTemplate: string;
   correctionsDir: string;
   readMemoryByPath: (filePath: string) => Promise<MemoryFile | null>;
@@ -44,10 +46,17 @@ export interface SupersessionSideEffectOptions {
   appendTombstone: (input: TombstoneInput) => Promise<string | null>;
   writeSealedMemory: (
     envelope: SealedMemoryEnvelope,
-    extras: { lineage: [string, string]; sourceMemoryId: string }
+    extras: { actor?: string; lineage: [string, string]; sourceMemoryId: string }
   ) => Promise<unknown>;
 }
 
+export interface SupersessionAuditOptions {
+  content: string;
+  tags?: string[];
+  structuredAttributes?: Record<string, string>;
+  source?: string;
+}
+
 export async function runSupersessionSideEffects(options: SupersessionSideEffectOptions): Promise<boolean> {
   const {
     oldMemoryId,
@@ -90,7 +99,7 @@ export async function runSupersessionSideEffects(options: SupersessionSideEffect
       }
     }
 
-    const auditBody = `Superseded: ${currentBefore.content}\n\nReason: ${reason}`;
+    const auditBody = `Superseded: ${options.audit?.content ?? currentBefore.content}\n\nReason: ${reason}`;
     const auditExists = await hasSupersessionAudit(
       {
         correctionsDir: options.correctionsDir,
@@ -98,7 +107,8 @@ export async function runSupersessionSideEffects(options: SupersessionSideEffect
       },
       oldMemoryId,
       newMemoryId,
-      auditBody
+      auditBody,
+      options.audit?.structuredAttributes
     );
     if (!auditExists) {
       const auditEnvelope = composeMemoryEnvelope(
@@ -106,11 +116,13 @@ export async function runSupersessionSideEffects(options: SupersessionSideEffect
           content: auditBody,
           category: "correction",
           confidence: 1,
-          tags: ["supersession", "auto-resolved"],
+          tags: options.audit?.tags ?? ["supersession", "auto-resolved"],
+          structuredAttributes: options.audit?.structuredAttributes,
         },
-        { source: "contradiction-detection" }
+        { source: options.audit?.source ?? "contradiction-detection" }
       );
       await options.writeSealedMemory(auditEnvelope, {
+        actor: options.actor,
         lineage: [oldMemoryId, newMemoryId],
         sourceMemoryId: oldMemoryId,
       });

package/src/storage/tombstone-blocked-capture-sync.ts

@@ -11,6 +11,7 @@ import { pathMayCarryEntityRefs, requestEntityCanonicalIdReconcile } from "./ent
 import { withRawEntityPageMutation } from "./entity-canonical-id-lock.js";
 import { readMaybeEncryptedFileFromChunks, writeMaybeEncryptedFileFromChunks } from "../secure-store/secure-fs.js";
 import * as archiveMutation from "../archive-mutation-version.js";
+import { invalidationCommitFingerprint } from "./deletion-revision-store.js";
 import {
   buildExplicitCaptureDedupKey,
   buildCapturePathLockIdentity,
@@ -236,6 +237,36 @@ export abstract class TombstoneBlockedCaptureIndexHost {
     return await this.getTombstoneBlockedCaptureIndex().withCaptureWriteLock(task, identity);
   }
 
+  /** Read selected memories while their mutation locks remain held. */
+  async readMemorySnapshotsIfUnchanged(expected: readonly MemoryFile[]): Promise<MemoryFile[] | null> {
+    return await this.withMemorySnapshotsIfUnchanged(expected, async (memories) => memories);
+  }
+
+  async withMemorySnapshotsIfUnchanged<T>(
+    expected: readonly MemoryFile[],
+    task: (memories: MemoryFile[]) => Promise<T>,
+  ): Promise<T | null> {
+    if (expected.length === 0) return await task([]);
+    const pathnames = [...new Set(expected.map((memory) => memory.path))];
+    if (pathnames.length !== expected.length) return null;
+    return await this.withTombstoneBlockedCaptureWriteLock(async () => {
+      const current = await Promise.all(pathnames.map((pathname) => this.readMemoryByPath(pathname)));
+      for (let index = 0; index < expected.length; index += 1) {
+        const actual = current[index];
+        const snapshot = expected[index];
+        if (
+          !actual ||
+          !snapshot ||
+          actual.frontmatter.id !== snapshot.frontmatter.id ||
+          invalidationCommitFingerprint(actual) !== invalidationCommitFingerprint(snapshot)
+        ) {
+          return null;
+        }
+      }
+      return await task(current as MemoryFile[]);
+    }, pathnames.map(buildCapturePathLockIdentity));
+  }
+
   protected async withTombstoneBlockedCaptureWriteLockAndHashes<T>(
     task: () => Promise<T>,
     identity: string | readonly string[] | undefined,

package/src/storage-contract/failure-semantics.test.ts

@@ -52,6 +52,108 @@ test("failure-semantics: getMemoryById on empty store returns null (not throw)",
   }
 });
 
+test("failure-semantics: selected memory snapshots reject a changed member", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+    assert.equal(await storage.updateMemory(second.id, "Changed source"), true);
+
+    assert.equal(await storage.readMemorySnapshotsIfUnchanged([firstSnapshot, secondSnapshot]), null);
+    assert.deepEqual(
+      (await storage.readMemorySnapshotsIfUnchanged([firstSnapshot]))?.map((memory) => memory.frontmatter.id),
+      [first.id]
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: selected memory snapshots block member writes until every read completes", async () => {
+  const { storage, cleanup } = await makeStorage();
+  const secondReadStarted = Promise.withResolvers<void>();
+  const releaseSecondRead = Promise.withResolvers<void>();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+    const readMemoryByPath = storage.readMemoryByPath.bind(storage);
+    let pauseSecond = true;
+    storage.readMemoryByPath = async (filePath) => {
+      const memory = await readMemoryByPath(filePath);
+      if (pauseSecond && filePath === second.memory.path) {
+        pauseSecond = false;
+        secondReadStarted.resolve();
+        await releaseSecondRead.promise;
+      }
+      return memory;
+    };
+
+    const snapshotPromise = storage.readMemorySnapshotsIfUnchanged([firstSnapshot, secondSnapshot]);
+    await secondReadStarted.promise;
+    let writeSettled = false;
+    const writePromise = storage.updateMemory(first.id, "Changed source").finally(() => {
+      writeSettled = true;
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(writeSettled, false);
+
+    releaseSecondRead.resolve();
+    assert.deepEqual(
+      (await snapshotPromise)?.map((memory) => memory.frontmatter.id),
+      [first.id, second.id]
+    );
+    assert.equal(await writePromise, true);
+  } finally {
+    releaseSecondRead.resolve();
+    await cleanup();
+  }
+});
+
+test("failure-semantics: selected memory snapshot tasks hold every member lock", async () => {
+  const { storage, cleanup } = await makeStorage();
+  const taskStarted = Promise.withResolvers<void>();
+  const releaseTask = Promise.withResolvers<void>();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+
+    const snapshotTask = storage.withMemorySnapshotsIfUnchanged(
+      [firstSnapshot, secondSnapshot],
+      async (memories) => {
+        taskStarted.resolve();
+        await releaseTask.promise;
+        return memories.map((memory) => memory.frontmatter.id);
+      },
+    );
+    await taskStarted.promise;
+    let writeSettled = false;
+    const writePromise = storage.updateMemoryIfUnchanged(firstSnapshot, "Changed source").finally(() => {
+      writeSettled = true;
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(writeSettled, false);
+
+    releaseTask.resolve();
+    assert.deepEqual(await snapshotTask, [first.id, second.id]);
+    assert.equal(await writePromise, true);
+  } finally {
+    releaseTask.resolve();
+    await cleanup();
+  }
+});
+
 test("failure-semantics: readMemoryByPath on a non-existent file returns null (not throw)", async () => {
   const { storage, baseDir, cleanup } = await makeStorage();
   try {

package/src/storage.ts

@@ -137,7 +137,7 @@ import {
   type TombstoneStats,
 } from "./lifecycle/tombstones.js";
 import { supersessionKeysForFact } from "./temporal-supersession.js";
-import { runSupersessionSideEffects } from "./storage/supersession-side-effects.js";
+import { runSupersessionSideEffects, type SupersessionAuditOptions } from "./storage/supersession-side-effects.js";
 import type {
   AccessTrackingEntry,
   BufferState,
@@ -233,6 +233,7 @@ import {
 } from "./memory-projection-store.js";
 import { inferMemoryStatus, isArchivedMemoryPath, toMemoryPathRel } from "./memory-lifecycle-ledger-utils.js";
 import { normalizeProjectionPreview, normalizeProjectionTags } from "./memory-projection-format.js";
+import { isSupportPassportPrivateMemory } from "./support-passport/card-projection.js";
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
 import {
   composeMemoryEnvelope,
@@ -3682,7 +3683,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     category: MemoryCategory,
     content: string,
     options: WriteMemoryOptions = {}
-  ): Promise<MemoryWriteResult> {
+  ) {
     await this.ensureDirectories();
     const rawEntityRef = options.entityRef;
     let refIds = typeof options.entityRef === "string" ? this.currentHistoricalIds() : null;
@@ -3883,6 +3884,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         tombstoneBlocked: true,
         blockedBy: duplicateBlocked.frontmatter.blockedBy,
         duplicateOf: duplicateBlocked.frontmatter.id,
+        memory: duplicateBlocked,
       };
     }
     await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
@@ -3937,7 +3939,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       }
     }
     log.debug(`wrote memory ${id} to ${filePath}`);
-    return { id, tombstoneBlocked, ...(fm.blockedBy ? { blockedBy: fm.blockedBy } : {}) };
+    return { id, tombstoneBlocked, ...(fm.blockedBy ? { blockedBy: fm.blockedBy } : {}), memory: { path: filePath, frontmatter: fm, content: sanitized.text } };
   }
 
   /**
@@ -3959,7 +3961,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    * `envelope.sourceReason` is access-layer metadata with no frontmatter
    * field and is deliberately not persisted here.
    */
-  async writeSealedMemory(envelope: SealedMemoryEnvelope, extras: SealedWriteExtras = {}): Promise<MemoryWriteResult> {
+  async writeSealedMemory(envelope: SealedMemoryEnvelope, extras: SealedWriteExtras = {}) {
     if (!isSealedMemoryEnvelope(envelope)) {
       throw new Error(
         "writeSealedMemory: value is not a valid sealed memory envelope (fails the composeMemoryEnvelope contract)"
@@ -6636,21 +6638,18 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return updated;
   }
 
-  /**
-   * Get a memory by its ID.
-   */
   async getMemoryById(id: string): Promise<MemoryFile | null> {
     const memories = await this.readAllMemories();
     return memories.find((m) => m.frontmatter.id === id) ?? null;
   }
 
-  /**
-   * Resolve existing active memory IDs to their on-disk paths.
-   *
-   * Uses a lightweight directory scan (collectActiveMemoryPaths) that reads
-   * file names without parsing frontmatter — much cheaper than readAllMemories()
-   * for citation usage tracking and other existence checks.
-   */
+  async getMemoryByIdIncludingArchived(id: string): Promise<MemoryFile | null> {
+    const active = await this.getMemoryById(id);
+    return active ?? (await this.readAllColdMemories()).find((memory) => memory.frontmatter.id === id) ??
+      (await this.readArchivedMemories()).find((memory) => memory.frontmatter.id === id) ?? null;
+  }
+
+  /** Resolve existing active memory IDs through a lightweight directory scan. */
   async findExistingMemoryPaths(
     ids: string[],
     preferredPaths: Map<string, string[]> = new Map()
@@ -6751,6 +6750,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       lastAccessed: memory.frontmatter.lastAccessed,
       tags: normalizeProjectionTags(memory.frontmatter.tags),
       preview: normalizeProjectionPreview(memory.content),
+      privateRecord: isSupportPassportPrivateMemory(memory),
     };
   }
 
@@ -6916,9 +6916,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     reason: string,
     supersessionMetadata?: Pick<MemoryFrontmatter, "supersessionCause" | "invalidatedBy">,
     options: {
-      requireActive?: boolean;
-      acceptExactReplay?: boolean;
+      actor?: string; requireActive?: boolean; acceptExactReplay?: boolean;
       expectedSnapshot?: Pick<MemoryFile, "content" | "frontmatter"> & Partial<Pick<MemoryFile, "path">>;
+      audit?: SupersessionAuditOptions;
     } = {},
   ): Promise<boolean> {
     const matchesSupersession = (memory: MemoryFile): boolean =>
@@ -7061,6 +7061,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         exactReplay,
         currentBefore,
         updatedFm,
+        actor: options.actor, audit: options.audit,
         citationTemplate: this.citationTemplate,
         correctionsDir: this.correctionsDir,
         readMemoryByPath: (filePath) => this.readMemoryByPath(filePath),
@@ -7093,7 +7094,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             memoryId: oldMemoryId,
             eventType: "superseded",
             timestamp: supersededAt,
-            actor: "storage.supersedeMemory",
+            actor: options.actor ?? "storage.supersedeMemory",
             reasonCode: reason,
             before: exactReplay ? { ...beforeState, status: "active" } : beforeState,
             after: afterState,
@@ -7107,14 +7108,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         writeSealedMemory: (envelope, extras) => this.writeSealedMemory(envelope, extras),
       });
       return sideEffectsComplete || options.acceptExactReplay !== true;
-
     } catch (err) {
       log.error(`failed to supersede memory ${oldMemoryId}:`, err);
       return false;
     }
   }
 
-
   private get summariesDir(): string {
     return path.join(this.baseDir, "summaries");
   }

package/src/support-passport/access-http-base.ts

@@ -0,0 +1,143 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
+
+import { EngramAccessForbiddenError } from "../access-errors.js";
+import type { EngramAccessService } from "../access-service.js";
+import { enforceNamespaceAllowList, tokenCapabilityStore } from "../access-token-capabilities.js";
+import type { WriteRateLimitReservation } from "../write-rate-limiter.js";
+import { handleSupportPassportOwnerHttp } from "./access-http.js";
+import { buildSupportPassportPublicRequestHandler } from "./public-http.js";
+
+const SUPPORT_PASSPORT_QUOTA_LIMITED_WRITE_TOOLS = new Set([
+  "engram.support_passport_draft_create",
+  "remnic.support_passport_draft_create",
+  "engram.support_passport_drafts_generate",
+  "remnic.support_passport_drafts_generate",
+  "engram.support_passport_card_replace",
+  "remnic.support_passport_card_replace",
+  "engram.support_passport_card_approve",
+  "remnic.support_passport_card_approve",
+  "engram.support_passport_card_reject",
+  "remnic.support_passport_card_reject",
+  "engram.support_passport_card_withdraw",
+  "remnic.support_passport_card_withdraw",
+  "engram.support_passport_grant_create",
+  "remnic.support_passport_grant_create",
+  "engram.support_passport_grant_revoke",
+  "remnic.support_passport_grant_revoke",
+]);
+const SUPPORT_PASSPORT_ADMIN_CONSOLE_ASSETS = new Map<string, string>([
+  ["what-helps-me.css", "text/css; charset=utf-8"],
+  ["model.js", "application/javascript; charset=utf-8"],
+  ["app.js", "application/javascript; charset=utf-8"],
+]);
+
+export abstract class SupportPassportAccessHttpBase {
+  private supportPassportPublicHandler: ReturnType<typeof buildSupportPassportPublicRequestHandler> | undefined;
+  protected abstract readonly service: EngramAccessService;
+  protected abstract readonly adminConsolePublicDir: string;
+  protected abstract resolveRequestPrincipal(req: IncomingMessage): string | undefined;
+  protected abstract readJsonBody(req: IncomingMessage, maxBodyBytes?: number): Promise<Record<string, unknown>>;
+  protected abstract respondJson(res: ServerResponse, status: number, payload: unknown): void;
+  protected abstract reserveWriteRateLimitSlot(req?: IncomingMessage): WriteRateLimitReservation;
+  protected abstract respondAdminConsoleShell(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string,
+    relativePath?: string,
+    allowPrefill?: boolean,
+  ): Promise<void>;
+  protected abstract respondStatic(res: ServerResponse, filePath: string, contentType: string): Promise<void>;
+
+  protected handleSupportPassportOwnerRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string,
+    hasQuery: boolean,
+    abortSignal: AbortSignal
+  ): Promise<boolean> {
+    return handleSupportPassportOwnerHttp({
+      req,
+      res,
+      pathname,
+      hasQuery,
+      service: this.service,
+      principal: this.resolveRequestPrincipal(req),
+      abortSignal,
+      readJsonBody: () => this.readJsonBody(req),
+      respondJson: (status, payload) => {
+        res.setHeader("cache-control", "private, no-store");
+        res.setHeader("vary", "Authorization");
+        this.respondJson(res, status, payload);
+      },
+      reserveWriteRateLimitSlot: () => this.reserveWriteRateLimitSlot(req),
+    });
+  }
+
+  protected handleSupportPassportPublicRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+    this.supportPassportPublicHandler ??= buildSupportPassportPublicRequestHandler(this.service, {
+      trustedProxyAddresses: this.service.configRef?.supportPassport?.trustedProxyAddresses ?? [],
+    });
+    return this.supportPassportPublicHandler(req, res, {
+      authorized: false,
+      tokenAuthorized: false,
+    });
+  }
+
+  protected async enforceSupportPassportAuthorizationProbe(req: IncomingMessage): Promise<void> {
+    const principal = this.resolveRequestPrincipal(req)?.trim();
+    if (!principal) {
+      throw new EngramAccessForbiddenError("A trusted principal is required for support passport access.");
+    }
+    const owner = await this.service.getWritableStorageForNamespace(undefined, principal);
+    enforceNamespaceAllowList(
+      tokenCapabilityStore.getStore(),
+      owner.namespace,
+      this.service.configRef.defaultNamespace
+    );
+  }
+
+  protected isSupportPassportQuotaLimitedWriteTool(toolName: string): boolean {
+    return SUPPORT_PASSPORT_QUOTA_LIMITED_WRITE_TOOLS.has(toolName);
+  }
+
+  protected async handleSupportPassportUi(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string
+  ): Promise<boolean> {
+    if (req.method !== "GET") return false;
+    const isSupportPassportPath =
+      pathname === "/remnic/ui/what-helps-me" ||
+      pathname === "/engram/ui/what-helps-me" ||
+      pathname.startsWith("/remnic/ui/what-helps-me/") ||
+      pathname.startsWith("/engram/ui/what-helps-me/");
+    if (!isSupportPassportPath) return false;
+    if (!this.service.supportPassportEnabled) {
+      this.respondJson(res, 404, { error: "not_found" });
+      return true;
+    }
+    if (pathname === "/remnic/ui/what-helps-me" || pathname === "/engram/ui/what-helps-me") {
+      const search = new URL(req.url ?? pathname, "http://placeholder").search;
+      res.statusCode = 301;
+      res.setHeader("location", `${pathname}/${search}`);
+      res.end();
+      return true;
+    }
+    if (pathname === "/remnic/ui/what-helps-me/" || pathname === "/engram/ui/what-helps-me/") {
+      const helperRequest = new URL(req.url ?? pathname, "http://placeholder").searchParams.has("grant");
+      res.setHeader("content-security-policy", "frame-ancestors 'none'");
+      res.setHeader("x-frame-options", "DENY");
+      await this.respondAdminConsoleShell(req, res, pathname, "what-helps-me/index.html", !helperRequest);
+      return true;
+    }
+    const fileName = pathname.split("/").at(-1) ?? "";
+    const assetType = SUPPORT_PASSPORT_ADMIN_CONSOLE_ASSETS.get(fileName);
+    if (assetType && pathname.split("/").length === 5) {
+      await this.respondStatic(res, path.join(this.adminConsolePublicDir, "what-helps-me", fileName), assetType);
+      return true;
+    }
+    this.respondJson(res, 404, { error: "not_found" });
+    return true;
+  }
+}