@remnic/core 9.69.37 → 9.69.39

package/src/access-schema.ts

@@ -3,7 +3,7 @@
 // field-level detail so consumers get clear feedback on malformed requests.
 
 import { z } from "zod";
-import { isMemoryCategory, MEMORY_CATEGORY_NAMES } from "./write-envelope.js";
+
 import type { MemoryCategory } from "./types.js";
 import {
   ACTION_CONFIDENCE_CONTEXT_READINESS,
@@ -267,86 +267,114 @@ export const deepRecallRequestSchema = z.object({
 // ---------------------------------------------------------------------------
 
 const writeContentSchema = z.string().min(1, "content is required").max(50000);
+// ---------------------------------------------------------------------------
+// Category wire contract (issue #2829): truthful input/output modeling.
+// ---------------------------------------------------------------------------
+
+/** Canonical input spellings — exactly the `MemoryCategory` union. */
+const MEMORY_CATEGORY_CANONICAL_INPUT = [
+  "fact", "preference", "correction", "entity", "decision",
+  "relationship", "principle", "commitment", "moment", "skill", "rule", "procedure",
+  "reasoning_trace",
+] as const satisfies readonly MemoryCategory[];
+
 /**
- * #2780: the canonical category set stays authoritative (`isMemoryCategory`),
- * with exactly four admitted input-compat aliases — the project-shaped
- * spellings fleet telemetry actually shows (`project`, `project_state`,
- * `project-state`, `project_update`) — for a project-shaped category that
- * does not exist. Exact match only, no case folding: `Project_State` and
- * near-misses like `projection` reject like any other invalid category.
- * Aliases are NOT enum members: the write-surface funnel coerces them to
- * "fact" and reports the coercion on the response. Everything else rejects
- * naming the full valid set plus a "use fact" hint so callers learn the
- * canonical name.
+ * Compatibility alias spellings admitted on input. The four project-shaped
+ * categories fleet telemetry actually shows do not exist in the taxonomy;
+ * they parse to the canonical "fact". Exact match only — no trimming, no
+ * case folding, so near-misses like `projection` or `Project_State` reject
+ * like any other invalid category, with the full valid list in the error.
  */
-const PROJECT_CATEGORY_ALIASES: Record<string, true> = {
-  project: true,
-  project_state: true,
-  "project-state": true,
-  project_update: true,
+const MEMORY_CATEGORY_ALIAS_INPUT = [
+  "project",
+  "project_state",
+  "project-state",
+  "project_update",
+] as const;
+
+export type MemoryCategoryAlias = (typeof MEMORY_CATEGORY_ALIAS_INPUT)[number];
+
+const MEMORY_CATEGORY_ALIAS_TO_CANONICAL: Readonly<
+  Record<MemoryCategoryAlias, Extract<MemoryCategory, "fact">>
+> = {
+  project: "fact",
+  project_state: "fact",
+  "project-state": "fact",
+  project_update: "fact",
 };
 
+export function isMemoryCategoryAlias(value: string): value is MemoryCategoryAlias {
+  return Object.prototype.hasOwnProperty.call(MEMORY_CATEGORY_ALIAS_TO_CANONICAL, value);
+}
+
+/** Coercion diagnostic for a write whose input category was a compat alias. */
 export interface CategoryAliasCoercion {
-  from: string;
+  from: MemoryCategoryAlias;
   to: "fact";
 }
 
-export function coerceProjectCategoryAlias<T extends { category?: string }>(
-  request: T,
-): { request: T; categoryCoercion?: CategoryAliasCoercion } {
-  const category = request.category;
-  if (category === undefined || PROJECT_CATEGORY_ALIASES[category] !== true) {
-    return { request };
-  }
-  return { request: { ...request, category: "fact" }, categoryCoercion: { from: category, to: "fact" } };
+/** Boundary-derived coercion note for a retained raw spelling. */
+export function categoryAliasCoercion(rawCategory: string | undefined): CategoryAliasCoercion | undefined {
+  return rawCategory !== undefined && isMemoryCategoryAlias(rawCategory)
+    ? { from: rawCategory, to: "fact" }
+    : undefined;
+}
+
+/**
+ * Recover the retained alias spelling from a pre-parse raw envelope: the
+ * `rawCategory` minted by a previous parse of the same schema (the HTTP/MCP
+ * validate-then-dispatch double pass) or an as-yet-untransformed alias
+ * `category` (single-parse callers like the CLI store command).
+ */
+export function retainedCategoryAlias(rawInput: unknown): MemoryCategoryAlias | undefined {
+  if (!rawInput || typeof rawInput !== "object") return undefined;
+  const spelling = (rawInput as Record<string, unknown>).rawCategory;
+  return typeof spelling === "string" && isMemoryCategoryAlias(spelling) ? spelling : undefined;
 }
 
 /**
- * #2780 fix B: an idempotent replay returns the FIRST request's stored
- * response, whose coercion note names that request's spelling. Rewrite the
- * note from the CURRENT raw request so every response identifies what its
+ * An idempotent replay returns the FIRST request's stored response, whose
+ * coercion note names that request's spelling. Rewrite the note from the
+ * CURRENT request's retained spelling so every response identifies what its
  * caller actually sent; the stored idempotent result is reused untouched.
  */
-export function reapplyCategoryCoercion<T extends { categoryCoercion?: CategoryAliasCoercion }>(
+export function reapplyCategoryCoercion<T extends object>(
   response: T,
   categoryCoercion: CategoryAliasCoercion | undefined,
-): T {
+): T & { categoryCoercion?: CategoryAliasCoercion } {
+  const restamped: T & { categoryCoercion?: CategoryAliasCoercion } = { ...response };
   if (categoryCoercion !== undefined) {
-    return { ...response, categoryCoercion };
-  }
-  if (response.categoryCoercion === undefined) {
-    return response;
+    restamped.categoryCoercion = categoryCoercion;
+  } else {
+    delete restamped.categoryCoercion;
   }
-  const { categoryCoercion: _stored, ...rest } = response;
-  return rest as T;
+  return restamped;
 }
 
-const categorySchema = (
-  z
-    .string()
-    .superRefine((value, ctx) => {
-      if (isMemoryCategory(value)) return;
-      if (PROJECT_CATEGORY_ALIASES[value] === true) return;
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `category must be one of: ${MEMORY_CATEGORY_NAMES.join(", ")}; for project state/facts use "fact"`,
-      });
-    })
-    .optional() as unknown as z.ZodType<MemoryCategory | undefined, z.ZodTypeDef, MemoryCategory | undefined>
+const categoryWireSchema = z.enum(
+  [...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT],
+  {
+    errorMap: () => ({
+      message:
+        `category must be one of: ${[...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT].join(", ")}; ` +
+        'for project state/facts use "fact"',
+    }),
+  },
 );
+
 const confidenceSchema = z.number().min(0).max(1).optional();
 const tagsSchema = z.array(z.string().max(256)).max(50).optional();
 const entityRefSchema = z.string().trim().max(512).optional();
 const ttlSchema = z.string().trim().max(128).optional();
 const sourceReasonSchema = z.string().trim().max(2000).optional();
 
-export const memoryStoreRequestSchema = z.object({
+const memoryStoreRequestShape = z.object({
   schemaVersion: schemaVersionSchema,
   idempotencyKey: idempotencyKeySchema,
   dryRun: dryRunSchema,
   sessionKey: sessionKeySchema,
   content: writeContentSchema,
-  category: categorySchema,
+  category: categoryWireSchema.optional(),
   confidence: confidenceSchema,
   namespace: namespaceSchema,
   tags: tagsSchema,
@@ -361,6 +389,34 @@ export const memoryStoreRequestSchema = z.object({
   projectTag: projectTagSchema,
 });
 
+/**
+ * Parsed memory-store request (issue #2829): the category transform maps
+ * compat aliases to the canonical "fact" DURING parsing, so the output type
+ * stays the finite `MemoryCategory` union — never an alias spelling. The raw
+ * spelling travels separately on `rawCategory`, minted only by the transform
+ * (zod strips it from client bodies), for the write surface's coercion note
+ * and idempotent-replay rebuild.
+ */
+export type MemoryStoreParsedRequest = Omit<z.infer<typeof memoryStoreRequestShape>, "category"> & {
+  category?: MemoryCategory;
+  rawCategory?: MemoryCategoryAlias;
+};
+
+export const memoryStoreRequestSchema = memoryStoreRequestShape.transform(
+  (request): MemoryStoreParsedRequest => {
+    if (request.category === undefined || !isMemoryCategoryAlias(request.category)) {
+      // Spread so the narrowed canonical category, not the wide wire union,
+      // becomes the output type.
+      return { ...request, category: request.category };
+    }
+    return {
+      ...request,
+      category: MEMORY_CATEGORY_ALIAS_TO_CANONICAL[request.category],
+      rawCategory: request.category,
+    };
+  },
+);
+
 export const suggestionSubmitRequestSchema = memoryStoreRequestSchema;
 
 // ---------------------------------------------------------------------------

package/src/access-service.ts

@@ -290,8 +290,8 @@ import {
   recordMemoryOutcome,
 } from "./memory-worth-outcomes.js";
 import type { LcmMessagePartInput, MessagePartSourceFormat } from "./message-parts/index.js";
-import type { ObserveRequest, RecallRequest } from "./access-schema.js";
-import { coerceProjectCategoryAlias, type CategoryAliasCoercion } from "./access-schema.js";
+import type { CategoryAliasCoercion, ObserveRequest, RecallRequest } from "./access-schema.js";
+import { splitCanonicalWriteRequest } from "./access-observe-write-category.js";
 import { recordObjectiveStateSnapshotsFromObservedMessages } from "./objective-state-writers.js";
 import { objectiveStateStoreOverrideForNamespace } from "./objective-state.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
@@ -959,15 +959,29 @@ export interface MemoryScopePlan {
   warnings: string[];
 }
 
+/**
+ * Raw `category` spelling retained at the request boundary when the wire
+ * schema's canonicalizing transform mapped a compat alias to "fact"
+ * (issue #2829). Diagnostic only: drives the response's `categoryCoercion`
+ * note and survives quarantine parking for replay. Never reaches the write
+ * candidate or the idempotency fingerprint, and never parses from client
+ * input (the wire schema strips it).
+ */
+export interface RetainedCategorySpelling {
+  rawCategory?: string;
+}
+
 export interface EngramAccessMemoryStoreRequest
   extends EngramAccessWriteEnvelope,
     ExplicitCaptureInput,
-    CodingScopedWriteInput {}
+    CodingScopedWriteInput,
+    RetainedCategorySpelling {}
 
 export interface EngramAccessSuggestionSubmitRequest
   extends EngramAccessWriteEnvelope,
     ExplicitCaptureInput,
-    CodingScopedWriteInput {}
+    CodingScopedWriteInput,
+    RetainedCategorySpelling {}
 
 export interface EngramAccessWriteResponse {
   schemaVersion: 1;
@@ -981,7 +995,7 @@ export interface EngramAccessWriteResponse {
   duplicateOf?: string;
   idempotencyKey?: string;
   idempotencyReplay?: boolean;
-  /** #2780: set when a project-shaped category alias was coerced to "fact". */
+  /** Present when a project-shaped category alias was coerced to "fact" (#2780/#2829). */
   categoryCoercion?: CategoryAliasCoercion;
 }
 
@@ -2941,8 +2955,8 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   async peekMemoryStoreIdempotency(
     rawRequest: EngramAccessMemoryStoreRequest
   ): Promise<EngramAccessIdempotencyStatus> {
-    // #2780: fingerprint the COERCED category so peek never diverges from the write it predicts.
-    const { request } = coerceProjectCategoryAlias(rawRequest);
+    // #2780/#2829: fingerprint the canonical category (schema transform already mapped aliases).
+    const { canonical: request } = splitCanonicalWriteRequest(rawRequest);
     const namespace = await this.resolveCodingScopedWriteNamespace(request);
     const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
     if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
@@ -2979,8 +2993,8 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   async peekSuggestionSubmitIdempotency(
     rawRequest: EngramAccessSuggestionSubmitRequest
   ): Promise<EngramAccessIdempotencyStatus> {
-    // #2780: fingerprint the COERCED category so peek never diverges from the write it predicts.
-    const { request } = coerceProjectCategoryAlias(rawRequest);
+    // #2780/#2829: fingerprint the canonical category (schema transform already mapped aliases).
+    const { canonical: request } = splitCanonicalWriteRequest(rawRequest);
     const namespace = await this.resolveCodingScopedWriteNamespace(request);
     const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
     if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {

package/src/background-generation-config.ts

@@ -0,0 +1,79 @@
+import { isLoopbackHost } from "./runtime/http-transport.js";
+
+export interface BackgroundGenerationConfig {
+  /** Full chat-completions URL. Never used as the global OpenAI base URL. */
+  endpoint: string;
+  /** Loopback bearer from the generated client file. */
+  token: string;
+  timeoutSeconds: number;
+}
+
+function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
+
+function parseBackgroundEndpoint(value: string, keyName: string): string {
+  const trimmed = stripTrailingSlashes(value.trim());
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`${keyName} must be an absolute HTTP or HTTPS URL`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`${keyName} must use HTTP or HTTPS`);
+  }
+  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
+    throw new Error(`${keyName} must use HTTPS unless the host is loopback`);
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error(
+      `${keyName} must not include credentials, query parameters, or fragments`,
+    );
+  }
+  return trimmed;
+}
+
+function parseBackgroundGenerationObject(
+  raw: unknown,
+  keyName: string,
+): BackgroundGenerationConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${keyName} must be an object`);
+  }
+  const record = raw as Record<string, unknown>;
+  const endpointRaw = record.endpoint;
+  if (typeof endpointRaw !== "string" || endpointRaw.trim().length === 0) {
+    throw new Error(`${keyName} must include an endpoint URL`);
+  }
+  const tokenRaw = record.token;
+  if (typeof tokenRaw !== "string" || tokenRaw.length === 0) {
+    throw new Error(`${keyName} must include a token`);
+  }
+  const timeoutRaw = record.timeoutSeconds;
+  let timeoutSeconds = 120;
+  if (timeoutRaw !== undefined) {
+    const parsed = typeof timeoutRaw === "number" ? timeoutRaw : Number(timeoutRaw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      throw new Error(`${keyName} timeoutSeconds must be a finite number > 0`);
+    }
+    timeoutSeconds = parsed;
+  }
+  return {
+    endpoint: parseBackgroundEndpoint(endpointRaw, `${keyName}.endpoint`),
+    token: tokenRaw,
+    timeoutSeconds,
+  };
+}
+
+export function parseBackgroundGeneration(
+  cfg: Record<string, unknown>,
+): BackgroundGenerationConfig | undefined {
+  const explicitRaw = cfg.backgroundGeneration;
+  if (explicitRaw === undefined || explicitRaw === null) return undefined;
+  return parseBackgroundGenerationObject(explicitRaw, "backgroundGeneration");
+}

package/src/background-generation.test.ts

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  completeBackgroundGeneration,
+  parseBackgroundGenerationJson,
+} from "./background-generation.js";
+import { parseConfig } from "./config.js";
+import { HourlySummarizer } from "./summarizer.js";
+
+test("completeBackgroundGeneration posts to the dedicated endpoint with the bearer", async () => {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const fetchImpl: typeof fetch = async (url, init) => {
+    calls.push({ url: String(url), init: init ?? {} });
+    return new Response(
+      JSON.stringify({
+        choices: [{ message: { content: '{"bullets":["one"]}' } }],
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    );
+  };
+
+  const text = await completeBackgroundGeneration(
+    {
+      backgroundGeneration: {
+        endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+        token: "bridge-token-fixture",
+        timeoutSeconds: 12,
+      },
+    },
+    [{ role: "user", content: "summarize" }],
+    fetchImpl,
+  );
+
+  assert.equal(text, '{"bullets":["one"]}');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.url, "http://127.0.0.1:8765/v1/chat/completions");
+  const headers = new Headers(calls[0]?.init.headers);
+  assert.equal(headers.get("authorization"), "Bearer bridge-token-fixture");
+  assert.equal(headers.get("content-type"), "application/json");
+  assert.equal(
+    calls[0]?.init.body,
+    JSON.stringify({ messages: [{ role: "user", content: "summarize" }] }),
+  );
+});
+
+test("completeBackgroundGeneration refuses an unconfigured client", async () => {
+  await assert.rejects(
+    () => completeBackgroundGeneration({}, [{ role: "user", content: "x" }]),
+    /not configured/,
+  );
+});
+
+test("parseBackgroundGenerationJson keeps the first valid candidate", () => {
+  const parsed = parseBackgroundGenerationJson(
+    'preamble {"bullets":["kept"]} trailing',
+    (value) => {
+      const record = value as { bullets?: string[] };
+      if (!Array.isArray(record.bullets)) throw new Error("no bullets");
+      return record.bullets;
+    },
+  );
+  assert.deepEqual(parsed, ["kept"]);
+});
+
+test("HourlySummarizer uses backgroundGeneration and not openaiBaseUrl", async () => {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-bg-summary-"));
+  const previousFetch = globalThis.fetch;
+  const previousXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = memoryDir;
+  const calls: string[] = [];
+  try {
+    const config = parseConfig({
+      memoryDir,
+      openaiApiKey: "keep-me",
+      openaiBaseUrl: "http://127.0.0.1:9999/v1",
+      backgroundGeneration: {
+        endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+        token: "bridge-token-fixture",
+        timeoutSeconds: 12,
+      },
+    });
+    globalThis.fetch = (async (url) => {
+      calls.push(String(url));
+      if (String(url) !== "http://127.0.0.1:8765/v1/chat/completions") {
+        return new Response("not the bridge", { status: 404 });
+      }
+      return new Response(
+        JSON.stringify({
+          choices: [{ message: { content: '{"bullets":["bridge-only"]}' } }],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const summarizer = new HourlySummarizer(config);
+    const summary = await summarizer.generateSummary(
+      "session-bridge",
+      new Date("2026-08-23T10:00:00.000Z"),
+      [
+        {
+          timestamp: "2026-08-23T10:01:00.000Z",
+          role: "user",
+          content: "ship the bridge",
+          sessionKey: "session-bridge",
+          turnId: "t1",
+        },
+      ],
+    );
+
+    assert.deepEqual(summary?.bullets, ["bridge-only"]);
+    assert.deepEqual(calls, ["http://127.0.0.1:8765/v1/chat/completions"]);
+    assert.equal(config.openaiBaseUrl, "http://127.0.0.1:9999/v1");
+  } finally {
+    globalThis.fetch = previousFetch;
+    if (previousXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = previousXdg;
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/background-generation.ts

@@ -0,0 +1,52 @@
+import { extractJsonCandidates } from "./json-extract.js";
+import type { PluginConfig } from "./types.js";
+
+export type BackgroundGenerationMessage = {
+  role: string;
+  content: string;
+};
+
+export async function completeBackgroundGeneration(
+  config: Pick<PluginConfig, "backgroundGeneration">,
+  messages: BackgroundGenerationMessage[],
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  const background = config.backgroundGeneration;
+  if (!background) {
+    throw new Error("backgroundGeneration is not configured");
+  }
+  const response = await fetchImpl(background.endpoint, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${background.token}`,
+    },
+    body: JSON.stringify({ messages }),
+    signal: AbortSignal.timeout(Math.max(1, background.timeoutSeconds) * 1000),
+  });
+  if (!response.ok) {
+    throw new Error(`background generation failed (${response.status})`);
+  }
+  const payload = (await response.json()) as {
+    choices?: Array<{ message?: { content?: string } }>;
+  };
+  const text = payload.choices?.[0]?.message?.content;
+  if (typeof text !== "string" || text.length === 0) {
+    throw new Error("background generation returned no content");
+  }
+  return text;
+}
+
+export function parseBackgroundGenerationJson<T>(
+  text: string,
+  parse: (value: unknown) => T,
+): T | null {
+  for (const candidate of extractJsonCandidates(text)) {
+    try {
+      return parse(JSON.parse(candidate));
+    } catch {
+      // keep trying candidates
+    }
+  }
+  return null;
+}

package/src/cli-fallback.ts

@@ -59,6 +59,11 @@ export function isCodexCliFallbackRunnerRegistered(): boolean {
   return processRunner !== undefined;
 }
 
+/** Current process-local Codex CLI runner, if any. */
+export function getCodexCliFallbackRunnerForProcess(): CodexCliFallbackRunner | undefined {
+  return processRunner;
+}
+
 /**
  * Registers the process-local Codex CLI transport. Core itself stays free of
  * child_process here; hosts and benchmark runtimes opt in, and the
@@ -79,14 +84,15 @@ export async function callCodexCliFallback(
   modelId: string,
   messages: CodexCliFallbackMessage[],
   options: CodexCliFallbackOptions = {},
+  runner: CodexCliFallbackRunner | undefined = processRunner,
 ): Promise<CodexCliFallbackResult> {
-  if (!processRunner) {
+  if (!runner) {
     throw new Error(
       'codex-cli fallback transport is not registered; install a runner with setCodexCliFallbackRunnerForProcess() before using api: "codex-cli"',
     );
   }
 
-  return await processRunner({
+  return await runner({
     config: normalizeCodexCliFallbackConfig(config),
     modelId: normalizeCodexCliModel(modelId),
     messages,