@remnic/core 9.7.10 → 9.7.12

package/dist/verified-recall.js

@@ -1,10 +1,10 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-YLTG6BO4.js";
+} from "./chunk-OIFZII6J.js";
 import "./chunk-2A3OXAP2.js";
 import "./chunk-ZBJMUXZH.js";
-import "./chunk-KXLRMM35.js";
+import "./chunk-TRH533CA.js";
 import "./chunk-L2B3EE7B.js";
 import "./chunk-B3ABVQ36.js";
 import "./chunk-5UZXUTVO.js";
@@ -15,7 +15,7 @@ import "./chunk-6CIAGZ6X.js";
 import "./chunk-J6A3CX5N.js";
 import "./chunk-4KJLYTLS.js";
 import "./chunk-SVOZFLIQ.js";
-import "./chunk-3ZVFLMFQ.js";
+import "./chunk-G5PVJJRA.js";
 import "./chunk-RULE4VG5.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-RHOZ5LLO.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.7.10",
+  "version": "9.7.12",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3010,7 +3010,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.7.10"
+    "@remnic/coding-graph": "^9.7.12"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-boundary.ts

@@ -102,6 +102,8 @@ export const OPERATION_NAMES = [
   "shared_context_write_output",
   "shared_feedback_record",
   "shared_priorities_append",
+  "relay_mission_append",
+  "relay_mission_read",
   "shared_context_cross_signals_run",
   "shared_context_curate_daily",
   "compounding_weekly_synthesize",

package/src/access-http.ts

@@ -53,6 +53,7 @@ import { handleChatMessage, handleChatEventsSSE } from "./chat/chat-http.js";
 import { cleanupExpiredChatSessions, enforceChatSessionNamespace } from "./chat/chat-session.js";
 import { isDefaultReviewNamespace, listPairs, readPair } from "./contradiction/contradiction-review.js";
 import { isValidResolutionVerb, executeResolution } from "./contradiction/resolution.js";
+import { RelayMissionStoreError } from "./relay/mission.js";
 
 export interface AccessHttpReadinessState {
   ready: boolean;
@@ -339,6 +340,22 @@ function decodePeerIdSegment(raw: string): string {
   }
 }
 
+function decodeRelayMissionIdSegment(raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new EngramAccessInputError(
+      "missionId path segment is not valid percent-encoded input",
+    );
+  }
+}
+
+function rejectBlankRelayNamespace(value: string | null | undefined): void {
+  if (value !== undefined && value !== null && value.trim().length === 0) {
+    throw new EngramAccessInputError("Relay namespace must not be blank when provided");
+  }
+}
+
 function codingContextFromProjectTag(projectTag: string): {
   projectId: string;
   branch: string | null;
@@ -378,7 +395,7 @@ export class EngramAccessHttpServer {
     res: ServerResponse,
     ctx: { authorized: boolean },
   ) => Promise<boolean>;
-  private readonly writeRequestTimestamps: number[] = [];
+  private readonly writeRequestSlots: Array<{ readonly recordedAt: number }> = [];
   private readonly writeRateLimitMaxRequests: number;
   private readonly writeRateLimitWindowMs: number;
   private readonly mcpServer: EngramMcpServer;
@@ -499,6 +516,20 @@ export class EngramAccessHttpServer {
             this.respondJson(res, 400, { error: err.message, code: "correction_contract_error" });
             return;
           }
+          if (err instanceof RelayMissionStoreError) {
+            const status = err.code === "idempotency_conflict"
+              ? 409
+              : err.code === "limit_exceeded"
+                ? 413
+                : err.code === "lock_unavailable"
+                  ? 503
+                  : 500;
+            this.respondJson(res, status, {
+              error: status >= 500 ? "relay_backend_unavailable" : err.message,
+              code: `relay_${err.code}`,
+            });
+            return;
+          }
           if (res.headersSent) {
             res.destroy(err as Error);
             return;
@@ -1670,6 +1701,103 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    // Remnic Relay mission receipts (issue #1966). These two routes share the
+    // access-boundary schemas and namespace-resolved storage contract. The
+    // browser receives an already-reduced snapshot; it never scans general
+    // memories, recall logs, or production state.
+    const relayEventMatch = /^\/engram\/v1\/relay\/missions\/([^/]+)\/events$/.exec(pathname);
+    if (req.method === "POST" && relayEventMatch) {
+      const missionId = decodeRelayMissionIdSegment(relayEventMatch[1] ?? "");
+      const body = await this.readJsonBody(req);
+      const unexpectedFields = Object.keys(body).filter(
+        (key) => key !== "namespace" && key !== "event",
+      );
+      if (unexpectedFields.length > 0) {
+        throw new EngramAccessInputError(
+          `Relay append body contains unexpected field(s): ${unexpectedFields.sort().join(", ")}`,
+        );
+      }
+      if (!Object.prototype.hasOwnProperty.call(body, "event")) {
+        throw new EngramAccessInputError("Relay append body must contain an event object");
+      }
+      if (
+        Object.prototype.hasOwnProperty.call(body, "namespace") &&
+        body.namespace !== undefined &&
+        body.namespace !== null &&
+        typeof body.namespace !== "string"
+      ) {
+        throw new EngramAccessInputError("namespace must be a string when provided");
+      }
+      rejectBlankRelayNamespace(
+        typeof body.namespace === "string" ? body.namespace : undefined,
+      );
+      const namespace = this.resolveNamespace(
+        req,
+        typeof body.namespace === "string" ? body.namespace : undefined,
+      );
+      const op = getOperation("relay_mission_append");
+      if (!op) {
+        throw new Error("access-boundary: operation not registered: relay_mission_append");
+      }
+      let releaseWriteQuota: (() => void) | undefined;
+      try {
+        const output = (await op.run(
+          { missionId, namespace, event: body.event },
+          {
+            service: this.service,
+            authenticatedPrincipal: this.resolveRequestPrincipal(req),
+            hooks: {
+              enforceWriteQuota: () => {
+                releaseWriteQuota ??= this.reserveWriteRateLimitSlot();
+              },
+            },
+          },
+        )) as { result: { appended: boolean; replayed: boolean; event: unknown } };
+        if (output.result.appended) {
+          // The reservation is now the committed quota hit. Do not record a
+          // second timestamp after the append returns.
+          releaseWriteQuota = undefined;
+        }
+        this.respondJson(res, output.result.appended ? 201 : 200, output.result);
+      } finally {
+        // Replays never invoke the hook. If a future store path invokes it but
+        // does not append, or persistence throws after reservation, return the
+        // slot so a failed write cannot exhaust the rolling window.
+        releaseWriteQuota?.();
+      }
+      return;
+    }
+
+    const relayMissionMatch = /^\/engram\/v1\/relay\/missions\/([^/]+)$/.exec(pathname);
+    if (req.method === "GET" && relayMissionMatch) {
+      const missionId = decodeRelayMissionIdSegment(relayMissionMatch[1] ?? "");
+      rejectBlankRelayNamespace(parsed.searchParams.get("namespace"));
+      const namespace = this.resolveNamespace(
+        req,
+        parsed.searchParams.get("namespace") ?? undefined,
+      );
+      const op = getOperation("relay_mission_read");
+      if (!op) {
+        throw new Error("access-boundary: operation not registered: relay_mission_read");
+      }
+      const output = (await op.run(
+        {
+          missionId,
+          namespace,
+          since: parsed.searchParams.get("since") ?? undefined,
+          until: parsed.searchParams.get("until") ?? undefined,
+          limit: parsed.searchParams.get("limit") ?? undefined,
+        },
+        {
+          service: this.service,
+          authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        },
+      )) as { result: unknown };
+      res.setHeader("cache-control", "no-store");
+      this.respondJson(res, 200, output.result);
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/engram/v1/memories") {
       // Migrated through the access boundary (issue #1525): the registry
       // entry owns schema validation, normalization, and service dispatch.
@@ -3711,18 +3839,31 @@ export class EngramAccessHttpServer {
   private ensureWriteRateLimitAvailable(): void {
     const now = Date.now();
     while (
-      this.writeRequestTimestamps.length > 0 &&
-      now - (this.writeRequestTimestamps[0] ?? 0) > this.writeRateLimitWindowMs
+      this.writeRequestSlots.length > 0 &&
+      now - (this.writeRequestSlots[0]?.recordedAt ?? 0) > this.writeRateLimitWindowMs
     ) {
-      this.writeRequestTimestamps.shift();
+      this.writeRequestSlots.shift();
     }
-    if (this.writeRequestTimestamps.length >= this.writeRateLimitMaxRequests) {
+    if (this.writeRequestSlots.length >= this.writeRateLimitMaxRequests) {
       throw new HttpError(429, "write_rate_limited", "write_rate_limited");
     }
   }
 
   private recordWriteRateLimitHit(): void {
-    this.writeRequestTimestamps.push(Date.now());
+    this.writeRequestSlots.push({ recordedAt: Date.now() });
+  }
+
+  private reserveWriteRateLimitSlot(): () => void {
+    this.ensureWriteRateLimitAvailable();
+    const slot = { recordedAt: Date.now() };
+    this.writeRequestSlots.push(slot);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const index = this.writeRequestSlots.indexOf(slot);
+      if (index >= 0) this.writeRequestSlots.splice(index, 1);
+    };
   }
 
   private shouldCountWriteRateLimit(response: { dryRun?: boolean; idempotencyReplay?: boolean }): boolean {

package/src/access-mcp-cancellation.test.ts

@@ -282,7 +282,7 @@ test("MCP write quota is recorded after commit even when the client disconnects
   });
   const serverHost = server as unknown as {
     mcpServer: EngramMcpServer;
-    writeRequestTimestamps: number[];
+    writeRequestSlots: Array<{ readonly recordedAt: number }>;
   };
   const originalHandleRequest = serverHost.mcpServer.handleRequest.bind(serverHost.mcpServer);
   serverHost.mcpServer.handleRequest = async (request, options) => {
@@ -318,7 +318,7 @@ test("MCP write quota is recorded after commit even when the client disconnects
 
     await waitFor(operationSettled.promise);
     await new Promise<void>((resolve) => setImmediate(resolve));
-    assert.equal(serverHost.writeRequestTimestamps.length, 1);
+    assert.equal(serverHost.writeRequestSlots.length, 1);
     assert.equal(responseStarted, false, "the disconnected client must not receive the committed write response");
   } finally {
     releaseOperation.resolve();

package/src/access-operations.ts

@@ -678,6 +678,8 @@ export const codegraphIngestTracesOperation = defineOperation<
 // Batch-migrated operations (issue #1525): registers all remaining
 // handlers through the boundary as a side effect of importing this module.
 import "./access-operations-batch.js";
+// Remnic Relay mission evidence operations (issue #1966).
+import "./relay/mission-access.js";
 
 export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,

package/src/access-surface-catalog.ts

@@ -193,6 +193,8 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: "lcm_compaction_flush" },
   { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: "lcm_compaction_record" },
   { method: "GET", pathname: "/engram/v1/lcm/status", operation: "lcm_status" },
+  { method: "GET", pathname: "/engram/v1/relay/missions/:id", operation: "relay_mission_read" },
+  { method: "POST", pathname: "/engram/v1/relay/missions/:id/events", operation: "relay_mission_append" },
   // Correction Contract (issue #1580) — plan/apply/pending.
   { method: "POST", pathname: "/engram/v1/correction/plan", operation: "memory_correct_plan" },
   { method: "POST", pathname: "/engram/v1/correction/apply", operation: "memory_correct_apply" },

package/src/config.test.ts

@@ -2161,3 +2161,47 @@ test("parseConfig rejects non-positive extraction retry/breaker numerics and fal
   assert.equal(c.extractionBreakerAuthCooldownMs, 1_800_000, "non-positive auth cooldown -> default");
   assert.deepEqual(c.extractionRetryScheduleMs, [60_000, 300_000, 1_800_000, 7_200_000], "schedule with non-positive entry -> default");
 });
+
+test("parseConfig namespace-catalog touch-path knobs: defaults, 0-accepting numerics, and validation (#1903)", () => {
+  // Documented defaults when absent.
+  const d = parseConfig({});
+  assert.equal(d.namespacesCatalogCompactBytes, 16 * 1024 * 1024, "compactBytes default 16 MB");
+  assert.equal(d.namespacesCatalogReadTouchCoalesceMs, 60_000, "read coalesce default 60000ms");
+  assert.equal(d.namespacesCatalogWriteTouchCoalesceMs, 1_000, "write coalesce default 1000ms");
+  assert.equal(d.namespacesCatalogTouchStateWrites, false, "state-write touch default false");
+
+  // 0 is an accepted disable switch for every numeric (resolveNonNegativeIntegerConfig).
+  assert.equal(parseConfig({ namespacesCatalogCompactBytes: 0 }).namespacesCatalogCompactBytes, 0);
+  assert.equal(parseConfig({ namespacesCatalogReadTouchCoalesceMs: 0 }).namespacesCatalogReadTouchCoalesceMs, 0);
+  assert.equal(parseConfig({ namespacesCatalogWriteTouchCoalesceMs: 0 }).namespacesCatalogWriteTouchCoalesceMs, 0);
+
+  // Positive integers pass through; CLI/env numeric strings coerce.
+  assert.equal(parseConfig({ namespacesCatalogCompactBytes: 4096 }).namespacesCatalogCompactBytes, 4096);
+  assert.equal(parseConfig({ namespacesCatalogReadTouchCoalesceMs: "30000" }).namespacesCatalogReadTouchCoalesceMs, 30_000);
+
+  // Boolean-like coercion for the state-write toggle (gotcha #36).
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: true }).namespacesCatalogTouchStateWrites, true);
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: "true" }).namespacesCatalogTouchStateWrites, true);
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: "off" }).namespacesCatalogTouchStateWrites, false);
+
+  // Negative and non-integer numerics are rejected with the documented message.
+  for (const key of [
+    "namespacesCatalogCompactBytes",
+    "namespacesCatalogReadTouchCoalesceMs",
+    "namespacesCatalogWriteTouchCoalesceMs",
+  ]) {
+    for (const bad of [-1, 1.5, "1.5", "abc", Number.NaN, Infinity]) {
+      assert.throws(
+        () => parseConfig({ [key]: bad }),
+        new RegExp(`${key} must be a non-negative integer`),
+        `${key}=${JSON.stringify(bad)} should throw`,
+      );
+    }
+  }
+
+  // A present-but-malformed boolean toggle fails fast (gotcha #51).
+  assert.throws(
+    () => parseConfig({ namespacesCatalogTouchStateWrites: "maybe" }),
+    /namespacesCatalogTouchStateWrites must be a boolean-like value/,
+  );
+});

package/src/config.ts

@@ -435,6 +435,26 @@ function resolvePositiveIntegerConfig(
   return coerced;
 }
 
+function resolveNonNegativeIntegerConfig(
+  value: unknown,
+  defaultValue: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < 0
+  ) {
+    throw new Error(
+      `${keyName} must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
 export function isOpenaiApiKeyDisabled(value: unknown): boolean {
   return value === false || (typeof value === "string" && value.trim().toLowerCase() === "false");
 }
@@ -2934,6 +2954,29 @@ export function parseConfig(
     // silently defaulting to enabled (CLAUDE.md rule #51); default to enabled
     // only when the value is absent.
     namespaceCatalogEnabled: resolveNamespaceCatalogEnabled(cfg.namespaceCatalogEnabled, rawOperatorConfig, runtimeSet),
+    // Namespace catalog touch-path performance knobs (issue #1903). Numerics use
+    // resolveNonNegativeIntegerConfig so 0 is an accepted disable switch; a
+    // present-but-invalid value (negative/non-integer) is REJECTED (rule #51).
+    namespacesCatalogCompactBytes: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogCompactBytes,
+      16 * 1024 * 1024,
+      "namespacesCatalogCompactBytes",
+    ),
+    namespacesCatalogReadTouchCoalesceMs: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogReadTouchCoalesceMs,
+      60_000,
+      "namespacesCatalogReadTouchCoalesceMs",
+    ),
+    namespacesCatalogWriteTouchCoalesceMs: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogWriteTouchCoalesceMs,
+      1_000,
+      "namespacesCatalogWriteTouchCoalesceMs",
+    ),
+    namespacesCatalogTouchStateWrites: resolveBooleanConfig(
+      cfg.namespacesCatalogTouchStateWrites,
+      false,
+      "namespacesCatalogTouchStateWrites",
+    ),
     // NOTE: namespace identifiers are intentionally NOT sanitized here — the
     // codebase rejects unsafe namespaces at the point of use (see
     // codex-materialize-runner and NamespaceStorageRouter / resolveNamespaceDir),

package/src/index.ts

@@ -387,6 +387,59 @@ export {
 } from "./access-http.js";
 export { EngramMcpServer } from "./access-mcp.js";
 
+// Remnic Relay — host-agnostic mission evidence and receipt contract.
+export {
+  RELAY_MISSION_DEFAULT_EVENT_LIMIT,
+  RELAY_MISSION_MAX_EVENT_LIMIT,
+  RELAY_MISSION_MAX_EVENTS,
+  RELAY_MISSION_MAX_FILE_BYTES,
+  RELAY_MISSION_MAX_LINE_BYTES,
+  RELAY_MISSION_SCHEMA_VERSION,
+  RelayEvidenceRefSchema,
+  RelayMissionEventInputSchema,
+  RelayMissionEventSchema,
+  RelayMissionPayloadSchema,
+  RelayMissionReadOptionsSchema,
+  RelayMissionStore,
+  RelayMissionStoreError,
+  compareRelayEvents,
+  reduceRelayMission,
+  relayMissionReceiptDigest,
+  type RelayAgentOutputSnapshot,
+  type RelayAgentSnapshot,
+  type RelayConflictSnapshot,
+  type RelayCorrectionSnapshot,
+  type RelayDecisionSnapshot,
+  type RelayEvidenceRef,
+  type RelayMissionAppendResult,
+  type RelayMissionEvent,
+  type RelayMissionEventInput,
+  type RelayMissionPayload,
+  type RelayMissionReadOptions,
+  type RelayMissionSnapshot,
+  type RelayMissionStatus,
+  type RelayMissionStoreErrorCode,
+  type RelayMissionStoreOptions,
+  type RelayPropagationSnapshot,
+  type RelayRecallSnapshot,
+  type RelayTestSnapshot,
+} from "./relay/mission.js";
+export {
+  RELAY_DEMO_MISSION_ID,
+  RELAY_DEMO_NAMESPACE,
+  createRelayMissionFixture,
+} from "./relay/mission-fixture.js";
+export {
+  appendRelayMissionEvent,
+  readRelayMission,
+  relayMissionAppendOperation,
+  relayMissionReadOperation,
+  type RelayMissionAppendAccessInput,
+  type RelayMissionAppendAccessOutput,
+  type RelayMissionReadAccessInput,
+  type RelayMissionReadAccessOutput,
+} from "./relay/mission-access.js";
+
 // agentAccessHttp.authToken SecretRef resolution (issue #757). Exposed so
 // host-specific bootstrap code (the OpenClaw plugin in `src/index.ts`, the
 // standalone server, the CLI) can resolve a SecretRef to a literal bearer