@remnic/core 10.0.90 → 10.0.92

package/dist/who-knows.js

@@ -9,22 +9,22 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-IBDWYRDR.js";
-import "./chunk-CC4V7HNP.js";
-import "./chunk-UHVXE24Y.js";
+} from "./chunk-EXHXJETE.js";
+import "./chunk-FSO3G4JJ.js";
 import "./chunk-QGVCFVX6.js";
+import "./chunk-UHVXE24Y.js";
 import "./chunk-IGOW4TJE.js";
 import "./chunk-NT7F7WJQ.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-KVSOEVAF.js";
-import "./chunk-QEZ3DW5O.js";
+import "./chunk-UE6RRXMF.js";
+import "./chunk-65AUYLU3.js";
+import "./chunk-DOJBV6WR.js";
 import "./chunk-PFUXPTBT.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-DLZGSZVC.js";
 import "./chunk-OVZIYLBZ.js";
-import "./chunk-EXYT52NR.js";
-import "./chunk-DOJBV6WR.js";
 import "./chunk-WNEVEMJ3.js";
+import "./chunk-EXYT52NR.js";
 import "./chunk-Y5NLBXPV.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
@@ -33,16 +33,16 @@ import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-PPUNC7UX.js";
 import "./chunk-X3724WL4.js";
-import "./chunk-S2HLHAZ4.js";
 import "./chunk-MRPOZBJC.js";
+import "./chunk-S2HLHAZ4.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-FF6N7BXC.js";
 import "./chunk-QFEDITXM.js";
 import "./chunk-AAD2ZS6P.js";
-import "./chunk-S45INSV3.js";
 import "./chunk-FHGWKODN.js";
-import "./chunk-YXZG5TVN.js";
 import "./chunk-ZIKENA2C.js";
+import "./chunk-YXZG5TVN.js";
 import "./chunk-3OUGSOJP.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-3ONXXHQO.js";
@@ -50,7 +50,6 @@ import "./chunk-3WU7XOFN.js";
 import "./chunk-P4GUQSK3.js";
 import "./chunk-4LZ7SVKM.js";
 import "./chunk-YHTG64XV.js";
-import "./chunk-G7D6GZ5J.js";
 import "./chunk-ER7XANP3.js";
 import "./chunk-M5GVCJSJ.js";
 import "./chunk-RBOJCG4T.js";
@@ -58,12 +57,15 @@ import "./chunk-IAYUTGF2.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-ELHJK7LM.js";
-import "./chunk-IUM3VSHI.js";
+import "./chunk-G7D6GZ5J.js";
+import "./chunk-7VLBZKNB.js";
+import "./chunk-Y33KJ556.js";
+import "./chunk-5IYOKDM4.js";
 import "./chunk-NWA6IXR3.js";
+import "./chunk-OR42ZI54.js";
+import "./chunk-IUM3VSHI.js";
 import "./chunk-VILPVT4S.js";
 import "./chunk-AF2XMJKD.js";
-import "./chunk-OR42ZI54.js";
 import "./chunk-23G5P7TA.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
@@ -73,23 +75,13 @@ import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-ZU3NJNO7.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-7VLBZKNB.js";
-import "./chunk-Y33KJ556.js";
 import "./chunk-UXXK523X.js";
+import "./chunk-YCVB7X56.js";
+import "./chunk-PQVCH2AE.js";
 import "./chunk-PJKTFXE2.js";
 import "./chunk-W5BIQOAJ.js";
 import "./chunk-HADD45AR.js";
 import "./chunk-RNFMFC37.js";
-import "./chunk-YCVB7X56.js";
-import "./chunk-PQVCH2AE.js";
-import "./chunk-V4XE263I.js";
-import "./chunk-YBA52OKG.js";
-import "./chunk-QEYTRFR3.js";
-import "./chunk-BT7NVCML.js";
-import "./chunk-R6HMAIKM.js";
-import "./chunk-BJMBJZ2Y.js";
-import "./chunk-UKJAGEXH.js";
-import "./chunk-FP2373TW.js";
 import "./chunk-L272A5QW.js";
 import "./chunk-BNZAR6PO.js";
 import "./chunk-ZA53AZND.js";
@@ -97,17 +89,25 @@ import "./chunk-7RJUVTVF.js";
 import "./chunk-AL3UYZ5N.js";
 import "./chunk-RL6NEVXT.js";
 import "./chunk-YET735EZ.js";
-import "./chunk-PWPIERBM.js";
+import "./chunk-43AA5FVD.js";
+import "./chunk-YBA52OKG.js";
+import "./chunk-YCNIGRRF.js";
+import "./chunk-VUFL7X3H.js";
+import "./chunk-C5LWPYS3.js";
+import "./chunk-QEYTRFR3.js";
+import "./chunk-BT7NVCML.js";
+import "./chunk-R6HMAIKM.js";
+import "./chunk-BJMBJZ2Y.js";
+import "./chunk-UKJAGEXH.js";
+import "./chunk-FP2373TW.js";
 import "./chunk-UDKWFDV2.js";
 import "./chunk-5FVVY2EB.js";
 import "./chunk-BTNNL7ZW.js";
+import "./chunk-EBV6VXKF.js";
 import "./chunk-JDSVLVCG.js";
 import "./chunk-5GKPFL3S.js";
 import "./chunk-JAKIDQB2.js";
-import "./chunk-EBV6VXKF.js";
 import "./chunk-P7FMDTKL.js";
-import "./chunk-VUFL7X3H.js";
-import "./chunk-C5LWPYS3.js";
 import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-6KH5NLQS.js";

package/dist/write-envelope.js

@@ -17,10 +17,10 @@ import "./chunk-BT7NVCML.js";
 import "./chunk-R6HMAIKM.js";
 import "./chunk-UDKWFDV2.js";
 import "./chunk-5FVVY2EB.js";
+import "./chunk-EBV6VXKF.js";
 import "./chunk-JDSVLVCG.js";
 import "./chunk-5GKPFL3S.js";
 import "./chunk-JAKIDQB2.js";
-import "./chunk-EBV6VXKF.js";
 import "./chunk-P7FMDTKL.js";
 import "./chunk-X4OZMANG.js";
 import "./chunk-R2MBW2S4.js";

package/package.json

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

package/src/access-http-admission.ts

@@ -0,0 +1,33 @@
+import type { ServerResponse } from "node:http";
+
+import { log } from "./logger.js";
+
+/** Advisory backpressure hint for 503 buffer_admission_refused (optional; removable without a contract change). */
+const BUFFER_ADMISSION_RETRY_AFTER_SECONDS = 5;
+
+type AdmissionErrorBody = { error: string; code: "storage_target_required" | "buffer_admission_refused" };
+
+/**
+ * Map durable-capture admission failures to HTTP answers. Returns true when the
+ * error was answered. A missing storage target is a permanent client fault (400,
+ * never retryable); a full buffer is retryable backpressure (503) that is logged
+ * with the request correlation id, not as a server fault.
+ */
+export function respondBufferAdmissionError(
+  err: Error,
+  res: ServerResponse,
+  correlationId: string,
+  respond: (status: number, body: AdmissionErrorBody) => void,
+): boolean {
+  if (err.name === "StorageTargetRequiredError") {
+    respond(400, { error: err.message, code: "storage_target_required" });
+    return true;
+  }
+  if (err.name === "ReplayAdmissionRefusedError") {
+    log.warn(`engram access HTTP buffer admission refused [${correlationId}]: ${err.message}`);
+    res.setHeader("retry-after", String(BUFFER_ADMISSION_RETRY_AFTER_SECONDS));
+    respond(503, { error: err.message, code: "buffer_admission_refused" });
+    return true;
+  }
+  return false;
+}

package/src/access-http-types.ts

@@ -0,0 +1,153 @@
+import type { AdapterRegistry } from "./adapters/index.js";
+import type { EngramAccessService } from "./access-service.js";
+import type { TokenCapabilities } from "./access-token-capabilities.js";
+import type { SupportPassportExternalRequestHandler } from "./support-passport/public-http.js";
+
+/** Public option, status and admin-control types for the access HTTP server (split out of access-http.ts for the file-size ratchet, #1995). */
+
+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[];
+}
+
+// Moved unchanged from access-http.ts (public admin API, consumed by @remnic/server): the patch
+// payload is validated by the host's admin controls, so the value type is intentionally open here.
+// oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type
+export type RemnicAdminConfigPatch = Record<string, unknown>;
+
+export interface RemnicAdminControls {
+  status: () => Promise<RemnicAdminDashboardStatus>;
+  update?: (patch: RemnicAdminConfigPatch) => Promise<RemnicAdminDashboardStatus>;
+}

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 };
       }