@remnic/core 10.0.90 → 10.0.91

package/src/access-http.test.ts

@@ -22,6 +22,7 @@ import {
   type TokenCapabilities,
 } from "./access-token-capabilities.js";
 import { BriefingTimeoutError } from "./briefing-deadline.js";
+import { initLogger, resetLogger, type LoggerBackend } from "./logger.js";
 import { parseConfig } from "./config.js";
 import { readPair, writePair } from "./contradiction/contradiction-review.js";
 import { createChatSession } from "./chat/chat-session.js";
@@ -815,7 +816,16 @@ test("HTTP coding-context endpoint accepts projectTag shorthand", async () => {
   }
 });
 
-test("HTTP observe answers 503 buffer_admission_refused when durable capture hits the entry cap", async () => {
+test("HTTP observe answers 503 buffer_admission_refused when durable capture hits the entry cap", async (t) => {
+  const warns: string[] = [];
+  const backend: LoggerBackend = {
+    info() {},
+    warn(msg) { warns.push(msg); },
+    error() {},
+    debug() {},
+  };
+  initLogger(backend, false, { timestamps: false });
+  t.after(() => resetLogger());
   const refusal = new Error("buffer at session-entry cap");
   refusal.name = "ReplayAdmissionRefusedError";
   // SAFETY: this fixture drives only the observe route; the remaining service members are unreachable.
@@ -852,6 +862,58 @@ test("HTTP observe answers 503 buffer_admission_refused when durable capture hit
       error: "buffer at session-entry cap",
       code: "buffer_admission_refused",
     });
+    assert.equal(response.headers.get("retry-after"), "5", "503 must carry the advisory backpressure hint");
+    const requestId = response.headers.get("x-request-id");
+    assert.ok(requestId, "the response must expose the correlation id");
+    assert.ok(
+      warns.some((line) => line.includes(requestId) && line.includes("buffer admission refused")),
+      `capacity refusal must log a correlated warn, got ${JSON.stringify(warns)}`,
+    );
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP observe missing-storage-target refusal is a non-retryable request fault, not 503 backpressure", async () => {
+  const refusal = new Error(
+    "accepted capture requires an explicit storage target (writeNamespaceOverride or scopeProfileWritePlan.writeNamespace)",
+  );
+  refusal.name = "StorageTargetRequiredError";
+  // SAFETY: this fixture drives only the observe route; the remaining service members are unreachable.
+  const service = Object.assign({} as EngramAccessService, {
+    observe: async () => {
+      throw refusal;
+    },
+  });
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/observe`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          sessionKey: "missing-target-test-session",
+          messages: [{ role: "user", content: "no target" }],
+        }),
+      },
+    );
+    assert.equal(response.status, 400, "a request with no storage target cannot succeed on retry");
+    assert.deepEqual(await response.json(), {
+      error: refusal.message,
+      code: "storage_target_required",
+    });
+    assert.equal(response.headers.get("retry-after"), null, "no backpressure hint on a permanent fault");
   } finally {
     await server.stop();
   }

package/src/access-http.ts

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath, URL } from "node:url";
 import { gunzipSync } from "node:zlib";
 import { log } from "./logger.js";
+import { respondBufferAdmissionError } from "./access-http-admission.js";
 import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { WriteRateLimiter, type WriteRateLimitReservation } from "./write-rate-limiter.js";
 import { abortError, isAbortError } from "./abort-error.js";
@@ -81,149 +82,30 @@ import { ReviewDeckAccessHttpBase } from "./review/review-deck-http-base.js";
 import { serializeInlineScriptValue } from "./inline-script.js";
 import { toDottedRemnicName } from "./access-mcp-tool-names.js";
 import type { SupportPassportExternalRequestHandler } from "./support-passport/public-http.js";
-export interface AccessHttpReadinessState {
-  ready: boolean;
-  warmupAttempts: number;
-  lastError?: string | null;
-  /**
-   * True when the standalone init gate opened before search warm-up completed
-   * (issue #2215): the service is functional (recall serves via fallback
-   * retrieval), so health answers 200 with degraded info instead of 503.
-   */
-  degraded?: boolean;
-}
-export interface EngramAccessHttpServerOptions {
-  service: EngramAccessService;
-  host?: string;
-  port?: number;
-  authToken?: string;
-  /** Additional valid tokens (for multi-connector auth). Checked alongside authToken. */
-  authTokens?: string[];
-  /** Dynamic token loader — called on each auth check so new/revoked tokens take effect without restart. */
-  authTokensGetter?: () => string[];
-  /**
-   * Dynamic token-ENTRY loader ({token, connector} pairs from one coherent
-   * snapshot). Preferred over `authTokensGetter` when a `tokenPathPolicy`
-   * is set: the connector used for the policy decision comes from the SAME
-   * entry that validated, so identity can never lag validation.
-   */
-  authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string; capabilities?: TokenCapabilities }>;
-  /**
-   * Optional per-request scope policy for tokens sourced from
-   * `authTokenEntriesGetter`. Return false to deny the (validated) token
-   * for this pathname. Static `authToken`/`authTokens` (operator-supplied)
-   * bypass the policy. Entries whose connector is missing FAIL CLOSED when
-   * a policy is configured.
-   */
-  tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
-  principal?: string;
-  maxBodyBytes?: number;
-  /**
-   * Max non-replayed write requests per rolling window before 429
-   * `write_rate_limited` (issue #1937). Positive integer; defaults to 30.
-   */
-  writeRateLimitMaxRequests?: number;
-  /** Rolling window for the write rate limit, in ms. Positive integer; defaults to 60000. */
-  writeRateLimitWindowMs?: number;
-  adminConsoleEnabled?: boolean;
-  adminConsolePublicDir?: string;
-  /** Inject the primary auth token into the admin console shell for trusted launch surfaces. */
-  adminConsolePrefillToken?: boolean;
-  trustPrincipalHeader?: boolean;
-  /** Enable adapter-based identity resolution from request headers */
-  enableAdapters?: boolean;
-  /** Custom adapter registry (defaults to built-in adapters) */
-  adapterRegistry?: AdapterRegistry;
-  /** Enable oai-mem-citation blocks in recall responses (issue #379). */
-  citationsEnabled?: boolean;
-  /** Auto-enable citations for Codex adapter connections (issue #379). */
-  citationsAutoDetect?: boolean;
-  /** Advertise legacy engram.* tool aliases on tools/list (issue #1427). Default true. */
-  emitLegacyTools?: boolean;
-  /** Optional authenticated admin dashboard/config controls supplied by the host server. */
-  adminControls?: RemnicAdminControls;
-  /**
-   * Standalone readiness state. Defaults to ready so embedded hosts keep their
-   * existing health behavior.
-   */
-  readiness?: () => AccessHttpReadinessState;
-  /**
-   * When set, every 401 response includes
-   * `WWW-Authenticate: Bearer resource_metadata="<value>"` so MCP clients
-   * can discover the OAuth 2.0 protected-resource metadata document
-   * (RFC 9728). Must be an absolute http(s) URL; constructor throws on
-   * anything else. Unset → bare `Bearer`.
-   */
-  resourceMetadataUrl?: string;
-  /**
-   * Optional pre-auth request handler (e.g. OAuth facade mounted by
-   * `@remnic/server`). Runs after the admin-console handler and BEFORE
-   * bearer authorization. Return true if the request was fully handled
-   * (response ended). `ctx.authorized` reports whether the request
-   * carries a valid operator bearer token, so the handler can gate
-   * operator-only endpoints without owning token validation.
-   * Errors thrown by the handler flow into the existing error handling.
-   */
-  externalRequestHandler?: SupportPassportExternalRequestHandler;
-}
-
-export interface EngramAccessHttpServerStatus {
-  running: boolean;
-  host: string;
-  port: number;
-  maxBodyBytes: number;
-}
-
-export interface RemnicAdminHarnessStatus {
-  id: string;
-  label: string;
-  detected: boolean;
-  enabled: boolean;
-  source?: string;
-  detail?: string;
-}
-
-export interface RemnicAdminModelOption {
-  id: string;
-  label: string;
-  provider: string;
-  detected: boolean;
-  enabled: boolean;
-  default?: boolean;
-  source?: string;
-  endpoint?: string;
-}
-
-export interface RemnicAdminFeatureStatus {
-  key: string;
-  label: string;
-  enabled: boolean;
-  writable: boolean;
-  restartRequired?: boolean;
-}
-
-export interface RemnicAdminConfigStatus {
-  path: string;
-  exists: boolean;
-  writable: boolean;
-  restartRequired: boolean;
-  values: Record<string, string | number | boolean | null>;
-}
-
-export interface RemnicAdminDashboardStatus {
-  config: RemnicAdminConfigStatus;
-  harnesses: RemnicAdminHarnessStatus[];
-  providers?: RemnicAdminHarnessStatus[];
-  models: RemnicAdminModelOption[];
-  features: RemnicAdminFeatureStatus[];
-}
-
-export type RemnicAdminConfigPatch = Record<string, unknown>;
-
-export interface RemnicAdminControls {
-  status: () => Promise<RemnicAdminDashboardStatus>;
-  update?: (patch: RemnicAdminConfigPatch) => Promise<RemnicAdminDashboardStatus>;
-}
+import type {
+  AccessHttpReadinessState,
+  EngramAccessHttpServerOptions,
+  EngramAccessHttpServerStatus,
+  RemnicAdminHarnessStatus,
+  RemnicAdminModelOption,
+  RemnicAdminFeatureStatus,
+  RemnicAdminConfigStatus,
+  RemnicAdminDashboardStatus,
+  RemnicAdminConfigPatch,
+  RemnicAdminControls,
+} from "./access-http-types.js";
+export type {
+  AccessHttpReadinessState,
+  EngramAccessHttpServerOptions,
+  EngramAccessHttpServerStatus,
+  RemnicAdminHarnessStatus,
+  RemnicAdminModelOption,
+  RemnicAdminFeatureStatus,
+  RemnicAdminConfigStatus,
+  RemnicAdminDashboardStatus,
+  RemnicAdminConfigPatch,
+  RemnicAdminControls,
+} from "./access-http-types.js";
 
 export function resolveDefaultAdminConsolePublicDir(sourceUrl = import.meta.url): string {
   const thisDir = path.dirname(fileURLToPath(sourceUrl));
@@ -549,11 +431,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
             });
             return;
           }
-          if (err.name === "ReplayAdmissionRefusedError") {
-            // Durable-capture backpressure (#3251/#1908): the request was
-            // never accepted — the buffer is at entry capacity. Retryable,
-            // not a server fault (503, not 500).
-            this.respondJson(res, 503, { error: err.message, code: "buffer_admission_refused" });
+          if (respondBufferAdmissionError(err, res, correlationId, (status, body) => this.respondJson(res, status, body))) {
             return;
           }
           if (res.headersSent) {

package/src/access-mcp.test.ts

@@ -150,6 +150,30 @@ test("MCP reports buffer admission refusal as retryable and does not return succ
 });
 
 
+test("MCP reports a missing storage target as a non-retryable storage_target_required error", async () => {
+  const failure = new Error("accepted capture requires an explicit storage target");
+  failure.name = "StorageTargetRequiredError";
+  // SAFETY: the mock overrides only observe; every other MCP dispatch path is unreachable in this test.
+  const service = Object.assign({} as EngramAccessService, {
+    observe: async () => {
+      throw failure;
+    },
+  });
+  const server = new EngramMcpServer(service);
+  const response = await server.handleRequest(
+    makeToolRequest("engram.observe", {
+      sessionKey: "no-target-session",
+      messages: [{ role: "user", content: "cannot succeed on retry" }],
+    }),
+  );
+  // SAFETY: a tools/call request always resolves to a JSON-RPC result envelope; only isError and structuredContent are asserted.
+  const result = response as {
+    result?: { isError?: boolean; structuredContent?: { code?: string; retryable?: boolean } };
+  };
+  assert.equal(result.result?.isError, true);
+  assert.deepEqual(result.result?.structuredContent, { code: "storage_target_required", retryable: false }, JSON.stringify(response));
+});
+
 // ──────────────────────────────────────────────────────────────────────────
 // Finding 2 (#396 new): invalid MCP briefing format values must be rejected
 // ──────────────────────────────────────────────────────────────────────────

package/src/access-mcp.ts

@@ -2434,6 +2434,9 @@ export class EngramMcpServer {
         };
         if (admissionBackpressure) {
           result.structuredContent = { code: "buffer_admission_refused", retryable: true };
+        } else if (err instanceof Error && err.name === "StorageTargetRequiredError") {
+          // A permanent property of the request: tell clients not to retry it.
+          result.structuredContent = { code: "storage_target_required", retryable: false };
         }
         return { jsonrpc: "2.0", id, result };
       }

package/src/access-observe-replay-durability.test.ts

@@ -1600,7 +1600,10 @@ test("#3251 namespaced buffered admission without writeNamespaceOverride or plan
         [makeReplayTurn("no-target-sess", "capture without target")],
         bufferedObserveOptions({ sessionOwnerPrincipal: "alice" }),
       ),
-      /requires an explicit storage target/,
+      (err: Error) =>
+        err.name === "StorageTargetRequiredError" &&
+        /requires an explicit storage target/.test(err.message),
+      "the missing-target refusal must be its own non-retryable class, never ReplayAdmissionRefusedError",
     );
     assert.equal(lcmCalls.length, 0, "zero LCM archival on rejected admission");
     assert.equal(queued.length, 0, "zero extraction queued on rejected admission");

package/src/access-service-observe-idempotency.test.ts

@@ -22,6 +22,7 @@ import { EngramAccessService } from "./access-service.js";
 import { EngramAccessInputError } from "./access-service.js";
 import { initLogger } from "./logger.js";
 import { Orchestrator } from "./orchestrator.js";
+import { ReplayAdmissionRefusedError } from "./orchestration/turn-ingestion.js";
 import type { EngramAccessObserveRequest } from "./access-service.js";
 import type { CodingContext, PluginConfig } from "./types.js";
 
@@ -328,6 +329,49 @@ test("#2206 project-scope-off ignores ambient coding context in observe idempote
   }
 });
 
+test("#1649 a capacity-refused observe does not consume its idempotencyKey", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-cap-idem-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const orch: Orchestrator = probe.orch;
+    const realIngest = orch.ingestReplayBatch.bind(orch);
+    type IngestFn = Orchestrator["ingestReplayBatch"];
+    let armed = true;
+    orch.ingestReplayBatch = async (...args: Parameters<IngestFn>): Promise<void> => {
+      if (armed) {
+        armed = false;
+        throw new ReplayAdmissionRefusedError(
+          "durable observe capture refused: extraction buffer at entry capacity for batch containing pi-geek:abc123",
+        );
+      }
+      return realIngest(...args);
+    };
+    const key = "observe-capacity-pi-geek-abc123-#1";
+
+    // First attempt refuses at entry capacity — the key must stay unused.
+    await assert.rejects(
+      service.observe(observeRequest({ idempotencyKey: key })),
+      (err: Error) => err instanceof ReplayAdmissionRefusedError,
+      "the seeded first attempt must refuse with the capacity backpressure error",
+    );
+    assert.equal(probe.extractionCalls.length, 0, "refused attempt must not ingest");
+
+    // Identical retry, same key: a REAL miss once capacity exists, not a replay
+    // of a response that never happened.
+    const retry = await service.observe(observeRequest({ idempotencyKey: key }));
+    assert.equal(retry.idempotencyReplay, undefined, "refusal must not have cached a response");
+    assert.equal(probe.extractionCalls.length, 1, "retry is admitted exactly once");
+
+    // Third identical request replays — the success bound the key, not the refusal.
+    const replay = await service.observe(observeRequest({ idempotencyKey: key }));
+    assert.equal(replay.idempotencyReplay, true, "post-success identical request replays");
+    assert.equal(probe.extractionCalls.length, 1, "replay must not ingest again");
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("#1649 review fix: projectTag observe replays correctly despite scope resolution side effects", async () => {
   // The fingerprint folds in the RESOLVED writeNamespace (not the raw ambient
   // context). resolveMemoryScopePlan seeds the session context from projectTag

package/src/buffer-admission.ts

@@ -26,6 +26,19 @@ export class ReplayAdmissionRefusedError extends Error {
   }
 }
 
+/**
+ * Durable observe capture rejected because the request resolves to no storage
+ * target (namespaces ON with neither writeNamespaceOverride nor a plan's
+ * writeNamespace). A property of the request — retrying cannot fix it — so it
+ * must never be classified as retryable backpressure.
+ */
+export class StorageTargetRequiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StorageTargetRequiredError";
+  }
+}
+
 /**
  * Live-admission bound (#1908 policy, backlog-safe): a NEW session enters
  * only while under the cap or when an EMPTY entry can be reclaimed. Buffered

package/src/orchestration/turn-ingestion.ts

@@ -59,8 +59,8 @@ import {
 
 // The class lives in ../buffer-admission.js next to BufferAdmissionRefusedError;
 // re-exported here so existing importers keep their import path.
-import { ReplayAdmissionRefusedError } from "../buffer-admission.js";
-export { ReplayAdmissionRefusedError };
+import { ReplayAdmissionRefusedError, StorageTargetRequiredError } from "../buffer-admission.js";
+export { ReplayAdmissionRefusedError, StorageTargetRequiredError };
 
 export interface TurnIngestionDeps {
   readonly buffer: SmartBuffer;
@@ -428,7 +428,7 @@ export class TurnIngestionCoordinator {
         ? options.scopeProfileWritePlan?.writeNamespace
         : this.deps.config.defaultNamespace);
     if (!resolvedWriteTarget) {
-      throw new ReplayAdmissionRefusedError(
+      throw new StorageTargetRequiredError(
         "accepted capture requires an explicit storage target (writeNamespaceOverride or scopeProfileWritePlan.writeNamespace)",
       );
     }

package/dist/chunk-M3BEJJNV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/buffer-admission.ts"],"sourcesContent":["/** Buffer session-entry admission: refusal errors and the live-admission probe. */\n\nimport { selectEvictedBufferKeys, type BufferEvictionHooks } from \"./buffer-eviction.js\";\nimport type { BufferEntryState } from \"./types.js\";\n\n/**\n * Raised when a NEW live-capture session cannot be admitted because the\n * session-entry cap is full of non-evictable backlog. The turn was never\n * accepted; the request is retryable once extraction drains an entry.\n */\nexport class BufferAdmissionRefusedError extends Error {\n  constructor(bufferKey: string, maxSessionEntries: number) {\n    super(\n      `buffer[${bufferKey}]: live capture refused at the session-entry cap (${maxSessionEntries}); ` +\n        \"buffered backlog is no longer evicted to admit new sessions. Retry after extraction frees an entry\",\n    );\n    this.name = \"BufferAdmissionRefusedError\";\n  }\n}\n\n/** Durable observe capture refused at the entry cap; the request is retryable. */\nexport class ReplayAdmissionRefusedError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ReplayAdmissionRefusedError\";\n  }\n}\n\n/**\n * Live-admission bound (#1908 policy, backlog-safe): a NEW session enters\n * only while under the cap or when an EMPTY entry can be reclaimed. Buffered\n * backlog is never dropped for a live capture; the caller refuses instead.\n */\nexport function canAdmitNewEntryUnlocked(\n  entries: Readonly<Record<string, BufferEntryState>>,\n  bufferKey: string,\n  maxSessionEntries: number,\n  hooks: BufferEvictionHooks,\n): boolean {\n  const count = Object.keys(entries).length;\n  if (count < maxSessionEntries) return true;\n  // Probe post-admission (as if this key had landed): admission is safe\n  // exactly when an EMPTY entry could then be reclaimed.\n  return selectEvictedBufferKeys(entries, [bufferKey], Math.max(0, count - 1), hooks).length > 0;\n}\n"],"mappings":";;;;;AAUO,IAAM,8BAAN,cAA0C,MAAM;AAAA,EACrD,YAAY,WAAmB,mBAA2B;AACxD;AAAA,MACE,UAAU,SAAS,qDAAqD,iBAAiB;AAAA,IAE3F;AACA,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,8BAAN,cAA0C,MAAM;AAAA,EACrD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAOO,SAAS,yBACd,SACA,WACA,mBACA,OACS;AACT,QAAM,QAAQ,OAAO,KAAK,OAAO,EAAE;AACnC,MAAI,QAAQ,kBAAmB,QAAO;AAGtC,SAAO,wBAAwB,SAAS,CAAC,SAAS,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC,GAAG,KAAK,EAAE,SAAS;AAC/F;","names":[]}