@remnic/core 9.54.4 → 9.54.6

package/src/support-passport/ui.test.ts

@@ -0,0 +1,181 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { EngramAccessHttpServer, resolveDefaultAdminConsolePublicDir } from "../access-http.js";
+import type { EngramAccessService } from "../access-service.js";
+import type { StorageManager } from "../storage.js";
+
+const adminConsolePublicDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../../admin-console/public"
+);
+
+async function withTempRoot(run: (root: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-support-passport-ui-"));
+  try {
+    await run(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function fakeService(root: string, enabled: boolean): EngramAccessService {
+  const storage = { dir: root } as StorageManager;
+  return {
+    supportPassportEnabled: enabled,
+    configRef: { defaultNamespace: "support-passport", namespacesEnabled: true },
+    getReadableStorageForNamespace: async () => ({ namespace: "support-passport", storage }),
+    getWritableStorageForNamespace: async () => ({ namespace: "support-passport", storage }),
+  } as unknown as EngramAccessService;
+}
+
+test("What Helps Me serves both aliases from one exact feature-gated allow-list", async () => {
+  await withTempRoot(async (root) => {
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, true),
+      host: "127.0.0.1",
+      port: 0,
+      authToken: "owner-token",
+      principal: "support-passport-owner",
+      adminConsoleEnabled: false,
+      adminConsolePublicDir,
+      adminConsolePrefillToken: true,
+    });
+    const status = await server.start();
+    const origin = `http://127.0.0.1:${status.port}`;
+    try {
+      for (const prefix of ["remnic", "engram"]) {
+        const redirect = await fetch(`${origin}/${prefix}/ui/what-helps-me`, { redirect: "manual" });
+        assert.equal(redirect.status, 301);
+        assert.equal(redirect.headers.get("location"), `/${prefix}/ui/what-helps-me/`);
+        const redirectWithGrant = await fetch(`${origin}/${prefix}/ui/what-helps-me?grant=grant-one&mode=replay`, {
+          redirect: "manual",
+        });
+        assert.equal(
+          redirectWithGrant.headers.get("location"),
+          `/${prefix}/ui/what-helps-me/?grant=grant-one&mode=replay`
+        );
+
+        const shell = await fetch(`${origin}/${prefix}/ui/what-helps-me/`);
+        assert.equal(shell.status, 200);
+        assert.match(shell.headers.get("content-type") ?? "", /^text\/html/);
+        assert.equal(shell.headers.get("content-security-policy"), "frame-ancestors 'none'");
+        assert.equal(shell.headers.get("x-frame-options"), "DENY");
+        assert.doesNotMatch(await shell.text(), /__REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN__/);
+
+        const authorizedShell = await fetch(`${origin}/${prefix}/ui/what-helps-me/`, {
+          headers: { authorization: "Bearer owner-token" },
+        });
+        assert.equal(authorizedShell.status, 200);
+        assert.equal(authorizedShell.headers.get("cache-control"), "private, no-store");
+        const authorizedShellText = await authorizedShell.text();
+        assert.match(authorizedShellText, /Object\.defineProperty\(window,key/);
+        assert.match(authorizedShellText, /new URLSearchParams\(location\.hash\.slice\(1\)\)\.has\("secret"\)/);
+        assert.match(authorizedShellText, /\}\)\("owner-token",document\.currentScript\)/);
+
+        const helperShell = await fetch(`${origin}/${prefix}/ui/what-helps-me/?grant=grant-one`, {
+          headers: { authorization: "Bearer owner-token" },
+        });
+        assert.equal(helperShell.status, 200);
+        assert.doesNotMatch(await helperShell.text(), /__REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN__|owner-token/);
+
+        const expectedAssets = new Map([
+          ["what-helps-me.css", /^text\/css/],
+          ["model.js", /^application\/javascript/],
+          ["app.js", /^application\/javascript/],
+        ]);
+        for (const [fileName, contentType] of expectedAssets) {
+          const asset = await fetch(`${origin}/${prefix}/ui/what-helps-me/${fileName}`);
+          assert.equal(asset.status, 200, `${prefix}/${fileName}`);
+          assert.match(asset.headers.get("content-type") ?? "", contentType);
+          assert.ok((await asset.text()).length > 100);
+        }
+
+        const unknown = await fetch(`${origin}/${prefix}/ui/what-helps-me/not-allowed.js`);
+        assert.equal(unknown.status, 404);
+        const nested = await fetch(`${origin}/${prefix}/ui/what-helps-me/app.js/extra`);
+        assert.equal(nested.status, 404);
+      }
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("What Helps Me finds repository assets without a source-mode path override", async () => {
+  const sourceModuleUrl = new URL("../access-http.ts", import.meta.url);
+  assert.equal(resolveDefaultAdminConsolePublicDir(sourceModuleUrl.href), adminConsolePublicDir);
+  await withTempRoot(async (root) => {
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, true),
+      host: "127.0.0.1",
+      port: 0,
+      authToken: "owner-token",
+      principal: "support-passport-owner",
+      adminConsoleEnabled: false,
+    });
+    const status = await server.start();
+    try {
+      const shell = await fetch(`http://127.0.0.1:${status.port}/remnic/ui/what-helps-me/`);
+      assert.equal(shell.status, 200);
+      assert.match(await shell.text(), /What Helps Me/);
+      const asset = await fetch(`http://127.0.0.1:${status.port}/remnic/ui/what-helps-me/app.js`);
+      assert.equal(asset.status, 200);
+      assert.ok((await asset.text()).length > 100);
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("What Helps Me finds copied assets from the published source export", async () => {
+  await withTempRoot(async (root) => {
+    const sourceModulePath = path.join(root, "package", "src", "access-http.ts");
+    const publishedAssets = path.join(root, "package", "dist", "admin-console", "public");
+    await mkdir(path.dirname(sourceModulePath), { recursive: true });
+    await mkdir(publishedAssets, { recursive: true });
+    await writeFile(sourceModulePath, "");
+    assert.equal(resolveDefaultAdminConsolePublicDir(new URL(`file://${sourceModulePath}`).href), publishedAssets);
+  });
+});
+
+test("What Helps Me assets stay hidden while support passport is disabled", async () => {
+  await withTempRoot(async (root) => {
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, false),
+      host: "127.0.0.1",
+      port: 0,
+      authToken: "owner-token",
+      principal: "support-passport-owner",
+      adminConsoleEnabled: true,
+      adminConsolePublicDir,
+    });
+    const status = await server.start();
+    try {
+      const response = await fetch(`http://127.0.0.1:${status.port}/remnic/ui/what-helps-me/`);
+      assert.equal(response.status, 404);
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("What Helps Me disables the browser cache for credentialed API requests", async () => {
+  const source = await readFile(path.join(adminConsolePublicDir, "what-helps-me", "app.js"), "utf8");
+  assert.match(source, /fetch\(path, \{[\s\S]*?cache: "no-store"/);
+});
+
+test("What Helps Me clears any prefill getter before helper initialization", async () => {
+  const source = await readFile(path.join(adminConsolePublicDir, "what-helps-me", "app.js"), "utf8");
+  assert.match(source, /if \(grantId \|\| hasSecretFragment\) \{\s+clearPrefillToken\(\);/);
+  assert.match(source, /delete window\.__REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN__/);
+});
+
+test("What Helps Me wordmark does not depend on the optional admin console", async () => {
+  const source = await readFile(path.join(adminConsolePublicDir, "what-helps-me", "index.html"), "utf8");
+  assert.doesNotMatch(source, /class="wordmark"[^>]*href=/);
+});

package/src/tier-routing.ts

@@ -1,10 +1,6 @@
+import { type LifecycleSignals, clamp01, computeLifecycleValueInputs, daysSince } from "./lifecycle.js";
+import { hasLiveSupportPassportCard } from "./support-passport/card-projection.js";
 import type { MemoryFile } from "./types.js";
-import {
-  clamp01,
-  computeLifecycleValueInputs,
-  daysSince,
-  type LifecycleSignals,
-} from "./lifecycle.js";
 
 export type MemoryTier = "hot" | "cold";
 
@@ -23,34 +19,39 @@ export interface TierTransitionDecision {
   reason: string;
 }
 
+function requiresHotTier(memory: Pick<MemoryFile, "frontmatter" | "content">): boolean {
+  return hasLiveSupportPassportCard(memory);
+}
+
 export function computeTierValueScore(
   memory: Pick<MemoryFile, "frontmatter">,
   now: Date,
-  signals?: LifecycleSignals,
+  signals?: LifecycleSignals
 ): number {
   const fm = memory.frontmatter;
   const inputs = computeLifecycleValueInputs(memory, now, signals);
   const correctionBoost = fm.category === "correction" ? 0.08 : 0;
   const confirmedBoost = fm.verificationState === "user_confirmed" ? 0.05 : 0;
 
-  const score = (inputs.confidence * 0.24)
-    + (inputs.access * 0.26)
-    + (inputs.recency * 0.2)
-    + (inputs.importance * 0.2)
-    + (inputs.feedback * 0.1)
-    + correctionBoost
-    + confirmedBoost
-    - (inputs.disputedPenalty * 0.5);
+  const score =
+    inputs.confidence * 0.24 +
+    inputs.access * 0.26 +
+    inputs.recency * 0.2 +
+    inputs.importance * 0.2 +
+    inputs.feedback * 0.1 +
+    correctionBoost +
+    confirmedBoost -
+    inputs.disputedPenalty * 0.5;
 
   return clamp01(score);
 }
 
 export function decideTierTransition(
-  memory: Pick<MemoryFile, "frontmatter">,
+  memory: Pick<MemoryFile, "frontmatter" | "content">,
   currentTier: MemoryTier,
   policy: TierRoutingPolicy,
   now: Date,
-  signals?: LifecycleSignals,
+  signals?: LifecycleSignals
 ): TierTransitionDecision {
   const valueScore = computeTierValueScore(memory, now, signals);
   if (!policy.enabled) {
@@ -63,6 +64,16 @@ export function decideTierTransition(
     };
   }
 
+  if (requiresHotTier(memory)) {
+    return {
+      currentTier,
+      nextTier: "hot",
+      valueScore,
+      changed: currentTier !== "hot",
+      reason: "support_passport_card_requires_hot_tier",
+    };
+  }
+
   if (currentTier === "hot") {
     const ageDays = daysSince(memory.frontmatter.updated ?? memory.frontmatter.created, now.getTime());
     if (ageDays >= policy.demotionMinAgeDays && valueScore <= policy.demotionValueThreshold) {

package/src/training-export/converter.test.ts

@@ -72,6 +72,30 @@ describe("convertMemoriesToRecords", () => {
     assert.deepEqual(records[0].sourceIds, ["mem-001"]);
   });
 
+  it("excludes private support passport cards and audits", async () => {
+    const dir = await makeTmpDir();
+    await writeSyntheticMemory(dir, "facts", "public.md", {
+      id: "public",
+      content: "This memory can be exported.",
+    });
+    await writeSyntheticMemory(dir, "preferences", "card.md", {
+      id: "card",
+      category: "preference",
+      tags: ["support-passport-card"],
+      content: "Private support card.",
+    });
+    await writeSyntheticMemory(dir, "corrections", "audit.md", {
+      id: "audit",
+      category: "correction",
+      tags: ["support-passport-audit"],
+      content: "Private support card audit.",
+    });
+
+    const records = await convertMemoriesToRecords({ memoryDir: dir });
+
+    assert.deepEqual(records.map((record) => record.sourceIds?.[0]), ["public"]);
+  });
+
   it("filters by minConfidence", async () => {
     const dir = await makeTmpDir();
     await writeSyntheticMemory(dir, "facts", "high.md", {

package/src/training-export/converter.ts

@@ -15,6 +15,7 @@ import path from "node:path";
 
 import { parseStrictCliDate } from "./date-parse.js";
 import type { TrainingExportOptions, TrainingExportRecord } from "./types.js";
+import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 
 // ---------------------------------------------------------------------------
@@ -293,6 +294,7 @@ export async function convertMemoriesToRecords(
     const parsed = parseFrontmatter(raw);
     if (!parsed) continue; // skip malformed files
     if (!parsed.content) continue; // skip empty content
+    if (isSupportPassportPrivateMemory({ frontmatter: { tags: parsed.tags } })) continue;
 
     parsed.filePath = filePath;
 

package/src/types.ts

@@ -548,6 +548,11 @@ export interface ChatConfig {
   sessionTtlHours: number;
 }
 
+export interface SupportPassportConfig {
+  enabled: boolean;
+  trustedProxyAddresses: string[];
+}
+
 /**
  * Session-scoped coding context. Produced by `resolveGitContext()` in the
  * connector layer and attached to a session so that recall + write paths can
@@ -1257,6 +1262,8 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   // Conversational memory inspection and correction (issue #1583). Off by
   // default — byte-identical pre-feature when enabled === false (rule 39).
   chat: ChatConfig;
+  /** Owner-controlled support passport. Off by default. */
+  supportPassport: SupportPassportConfig;
   slotBehavior: SlotBehaviorConfig;
   /** OpenClaw bridge mode (#2120): `"embedded"` (default) or `"delegate"`. */
   bridgeMode: string;
@@ -3631,7 +3638,7 @@ export interface MemoryProjectionCurrentState {
   accessCount?: number;
   lastAccessed?: string;
   tags?: string[];
-  preview?: string;
+  preview?: string; privateRecord?: boolean;
 }
 
 export interface CompressionGuidelineOptimizerSourceWindow {

package/src/wearables/service.test.ts

@@ -562,6 +562,19 @@ test("support corpus includes pending_review rows and excludes terminal statuses
       "pending-1",
     );
 
+    const privatePassport = makeRow(
+      "passport-1",
+      "pending_review",
+      "The launch moved to September twelfth after the vendor call, noted earlier.",
+    );
+    privatePassport.frontmatter.tags.push("support-passport-card");
+    const passportUnsupported = await runSmartSync([privatePassport]);
+    assert.equal(passportUnsupported.status, "pending_review");
+    assert.equal(
+      (passportUnsupported.structuredAttributes as Record<string, string>).supportingMemoryId,
+      undefined,
+    );
+
     // Terminal statuses with the same content are NOT support evidence.
     const similar =
       "The launch moved to September twelfth after the vendor call, noted earlier.";

package/src/wearables/service.ts

@@ -13,6 +13,7 @@ import {
 } from "./corrections.js";
 import { describeErrorForOperator, WearablesInputError } from "./errors.js";
 import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 import {
   bodyIsEscaped,
   decodeTranscriptBody,
@@ -388,6 +389,7 @@ export class WearablesService {
             const memories = await storage.readAllMemories();
             const support: Array<{ id: string; content: string }> = [];
             for (const memory of memories) {
+              if (isSupportPassportPrivateMemory(memory)) continue;
               // WearableStorageIo narrows MemoryFrontmatter for
               // testability; production hands us the real thing.
               const status = inferMemoryStatus(

package/src/write-rate-limiter.test.ts

@@ -28,7 +28,7 @@ test("WriteRateLimiter: capacity check, record, and sampled rejection logging (i
     assert.equal(limiter.hasCapacity(), false);
     assert.ok(
       warnings.some((w) => w.includes("write_rate_limited")),
-      "a refused write is logged server-side",
+      "a refused write is logged server-side"
     );
     assert.equal(warnings.length, 1, "logging is sampled within the interval, not per-refusal");
   } finally {
@@ -38,15 +38,39 @@ test("WriteRateLimiter: capacity check, record, and sampled rejection logging (i
 
 test("WriteRateLimiter: reserve returns a release, refuses at the limit, frees on release", () => {
   const limiter = new WriteRateLimiter(1, 60_000);
-  const release = limiter.reserve();
-  assert.ok(release, "first reservation succeeds");
-  assert.equal(limiter.slotsFor().length, 1);
+  const reservation = limiter.reserve();
+  assert.ok(reservation, "first reservation succeeds");
+  assert.equal(limiter.inFlightFor(), 1);
+  assert.equal(limiter.totalSlots(), 1);
+  assert.equal(limiter.slotsFor().length, 0);
   assert.equal(limiter.reserve(), null, "second reservation refused at the limit");
-  release?.();
-  assert.equal(limiter.slotsFor().length, 0, "release frees the reserved slot");
+  reservation?.release();
+  assert.equal(limiter.inFlightFor(), 0, "release frees the reserved slot");
   assert.ok(limiter.reserve(), "capacity restored after release");
 });
 
+test("WriteRateLimiter: an in-flight write does not expire and commit starts its window", () => {
+  const realNow = Date.now;
+  try {
+    let now = 1_000_000;
+    Date.now = () => now;
+    const limiter = new WriteRateLimiter(1, 1000);
+    const reservation = limiter.reserve();
+    assert.ok(reservation);
+    now += 1001;
+    assert.equal(limiter.reserve(), null, "an active reservation remains capacity-bound");
+
+    reservation.commit();
+    assert.equal(limiter.inFlightFor(), 0);
+    assert.equal(limiter.slotsFor()[0]?.recordedAt, now);
+    assert.equal(limiter.reserve(), null, "the commit starts a new rolling window");
+    now += 1000;
+    assert.ok(limiter.reserve(), "capacity returns when the commit window expires");
+  } finally {
+    Date.now = realNow;
+  }
+});
+
 test("WriteRateLimiter: old slots pruned after the rolling window", () => {
   const realNow = Date.now;
   try {

package/src/write-rate-limiter.ts

@@ -27,6 +27,11 @@ const GLOBAL_BUCKET = "";
 
 type Slot = { readonly recordedAt: number };
 
+export interface WriteRateLimitReservation {
+  commit(): void;
+  release(): void;
+}
+
 function sanitizePositiveInteger(value: number | undefined, fallback: number): number {
   return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : fallback;
 }
@@ -37,6 +42,7 @@ export class WriteRateLimiter {
   // One rolling window per principal. Empty buckets are pruned so the map does
   // not grow without bound.
   private readonly buckets = new Map<string, Slot[]>();
+  private readonly inFlight = new Map<string, number>();
   private lastLogAt = 0;
   private suppressed = 0;
 
@@ -63,16 +69,21 @@ export class WriteRateLimiter {
     }
   }
 
-  /** Live reservation/record count for a principal (test/introspection). */
+  /** Committed slots for a principal (test/introspection). */
   slotsFor(principal?: string): ReadonlyArray<Slot> {
     return this.buckets.get(this.key(principal)) ?? [];
   }
 
+  inFlightFor(principal?: string): number {
+    return this.inFlight.get(this.key(principal)) ?? 0;
+  }
+
   /** Total live reservations across all principals (test/introspection). */
   totalSlots(): number {
     this.sweep(Date.now());
     let total = 0;
     for (const slots of this.buckets.values()) total += slots.length;
+    for (const count of this.inFlight.values()) total += count;
     return total;
   }
 
@@ -81,7 +92,7 @@ export class WriteRateLimiter {
     this.sweep(Date.now());
     const key = this.key(principal);
     const slots = this.buckets.get(key);
-    if (slots && slots.length >= this.maxRequests) {
+    if ((slots?.length ?? 0) + (this.inFlight.get(key) ?? 0) >= this.maxRequests) {
       this.logRejected(key);
       return false;
     }
@@ -92,30 +103,32 @@ export class WriteRateLimiter {
   record(principal?: string): void {
     this.sweep(Date.now());
     const key = this.key(principal);
-    const slots = this.buckets.get(key) ?? this.buckets.set(key, []).get(key)!;
+    let slots = this.buckets.get(key);
+    if (!slots) {
+      slots = [];
+      this.buckets.set(key, slots);
+    }
     slots.push({ recordedAt: Date.now() });
   }
 
   /**
-   * Reserve a slot for an in-flight write. Returns a release function, or
-   * `null` when the principal is already at the limit (caller raises its 429).
+   * Reserve a slot for an in-flight write. Commit starts the rolling window
+   * when persistence finishes. Release restores capacity after a failed write.
    */
-  reserve(principal?: string): (() => void) | null {
+  reserve(principal?: string): WriteRateLimitReservation | null {
     if (!this.hasCapacity(principal)) return null;
     const key = this.key(principal);
-    const slots = this.buckets.get(key) ?? this.buckets.set(key, []).get(key)!;
-    const slot: Slot = { recordedAt: Date.now() };
-    slots.push(slot);
+    this.inFlight.set(key, (this.inFlight.get(key) ?? 0) + 1);
     let active = true;
-    return () => {
+    const finish = (committed: boolean) => {
       if (!active) return;
       active = false;
-      const current = this.buckets.get(key);
-      if (!current) return;
-      const index = current.indexOf(slot);
-      if (index >= 0) current.splice(index, 1);
-      if (current.length === 0) this.buckets.delete(key);
+      const count = this.inFlight.get(key) ?? 0;
+      if (count <= 1) this.inFlight.delete(key);
+      else this.inFlight.set(key, count - 1);
+      if (committed) this.record(principal);
     };
+    return { commit: () => finish(true), release: () => finish(false) };
   }
 
   private logRejected(principal: string): void {
@@ -127,9 +140,7 @@ export class WriteRateLimiter {
     this.lastLogAt = now;
     const who = principal === GLOBAL_BUCKET ? "(no principal)" : principal;
     log.warn(
-      `write_rate_limited: rejected ${rejected} write(s) for principal ${who}; ` +
-        `per-principal limit is ${this.maxRequests} per ${this.windowMs}ms. Raise ` +
-        `server.writeRateLimitMaxRequests (or REMNIC_WRITE_RATE_LIMIT_MAX_REQUESTS) if sustained.`,
+      `write_rate_limited: rejected ${rejected} write(s) for principal ${who}; per-principal limit is ${this.maxRequests} per ${this.windowMs}ms. Raise server.writeRateLimitMaxRequests (or REMNIC_WRITE_RATE_LIMIT_MAX_REQUESTS) if sustained.`
     );
   }
 }