@remnic/core 9.3.719 → 9.3.721

package/src/lifecycle/tombstones.ts

@@ -40,7 +40,7 @@
 //   - Semantic tier (4) ships dark, off by default (rule 48).
 // ---------------------------------------------------------------------------
 
-import { serializeMutations } from "../utils/serialize-mutations.js";
+import { serializeMutations, withHeldFileLock } from "../utils/serialize-mutations.js";
 
 /** Why a tombstone was emitted. */
 export type TombstoneReason =
@@ -129,6 +129,20 @@ export interface TombstoneStoreOptions {
    * skipped entirely.
    */
   semanticSimilarity?: (a: string, b: string) => number;
+  /**
+   * Cross-process write-lock timings for the tombstone JSONL mutation lock
+   * (issue #1639). The secure-store append is a read-merge-write (read
+   * encrypted → decrypt → concat → re-encrypt → atomic rename), so two
+   * Remnic processes appending concurrently can each read the same contents
+   * and the last writer drops the other's entry — breaking the
+   * non-resurrection invariant. The lock serializes the mutation across
+   * processes. When omitted, defaults that fit the short tombstone critical
+   * section (mirroring the summary-snapshot lock): staleMs 30s, maxWaitMs 5s,
+   * heartbeatMs floor(staleMs/3).
+   */
+  readonly lockStaleMs?: number;
+  readonly lockMaxWaitMs?: number;
+  readonly lockHeartbeatMs?: number;
 }
 
 /** Injected file I/O — the StorageManager wires its secure-store-aware
@@ -261,7 +275,33 @@ export class TombstoneStore {
     private readonly namespace: string,
     private readonly options: TombstoneStoreOptions,
     private readonly io: TombstoneFileIo,
-  ) {}
+  ) {
+    this.lockStaleMs = this.options.lockStaleMs ?? 30_000;
+    this.lockMaxWaitMs = this.options.lockMaxWaitMs ?? 5_000;
+    this.lockHeartbeatMs =
+      this.options.lockHeartbeatMs ?? Math.max(100, Math.floor(this.lockStaleMs / 3));
+  }
+
+  /**
+   * Resolved cross-process write-lock timings (issue #1639). Defaults mirror
+   * the summary-snapshot lock: a tombstone append critical section is
+   * sub-second, so a stale lock older than 30s is a crashed holder; bounded
+   * acquisition gives up after 5s and strict-fails rather than clobbering a
+   * concurrent writer (which would reintroduce the lost-write race this lock
+   * closes).
+   */
+  private readonly lockStaleMs: number;
+  private readonly lockMaxWaitMs: number;
+  private readonly lockHeartbeatMs: number;
+
+  /**
+   * Sibling advisory lockfile: `<tombstones>.jsonl` → `<tombstones>.lock`.
+   * Shared by append, revoke, and rebuild so every JSONL mutation serializes
+   * against the others across processes (issue #1639: "shared with rebuilds").
+   */
+  private get lockPath(): string {
+    return this.filePath.replace(/\.jsonl$/i, "") + ".lock";
+  }
 
   /** Lazy load + build the in-memory index. Idempotent. */
   async load(): Promise<void> {
@@ -473,10 +513,48 @@ export class TombstoneStore {
 
   private serializeAppend(entry: TombstoneEntry): Promise<void> {
     const line = JSON.stringify(entry) + "\n";
-    // serializeMutations recovers after rejection (rule 40): a failed append
-    // surfaces to THIS caller but the next append is not poisoned.
+    // serializeMutations (in-process, rule 40 rejection recovery) wraps the
+    // cross-process lock: within one process appends are queued, and across
+    // processes the advisory lockfile serializes the read-merge-write so two
+    // Remnic processes appending concurrently cannot drop each other's entry
+    // (issue #1639). Under the lock we re-sync the in-memory index against
+    // disk first, so indexEntry builds on the peer's just-appended entries.
     return serializeMutations(`tombstone:${this.filePath}`, () =>
-      this.io.append(this.filePath, line),
+      this.withWriteLock(async () => {
+        await this.ensureFreshAgainstDisk();
+        await this.io.append(this.filePath, line);
+      }),
+    );
+  }
+
+  /**
+   * Acquire the cross-process tombstone write lock and run `task` under it
+   * (issue #1639). Strict-fail on acquisition timeout: the secure-store append
+   * is a read-merge-write, so a best-effort unlocked run would clobber a
+   * concurrent writer — reintroducing the lost-write race this lock closes.
+   * The thrown error surfaces to the caller (rule 34: never silently drop);
+   * rebuild recovers the tombstone on the next maintenance cycle.
+   *
+   * In-process callers are already serialized by serializeMutations (one key
+   * for append/revoke/rebuild), so this lock only contends across processes —
+   * the single-process daemon (default deployment) acquires it immediately.
+   */
+  private withWriteLock<T>(task: () => Promise<T>): Promise<T> {
+    return withHeldFileLock(
+      this.lockPath,
+      {
+        staleMs: this.lockStaleMs,
+        maxWaitMs: this.lockMaxWaitMs,
+        heartbeatMs: this.lockHeartbeatMs,
+      },
+      async (acquired) => {
+        if (!acquired) {
+          throw new Error(
+            "could not acquire tombstone write lock (contention timeout or filesystem error)",
+          );
+        }
+        return task();
+      },
     );
   }
 
@@ -595,72 +673,81 @@ export class TombstoneStore {
    * Returns the count of tombstone entries written.
    */
   async rebuild(retiredMemories: ReadonlyArray<RetiredMemoryRecord>): Promise<number> {
-    // Preserve existing revocations (all namespaces — ids are globally
-    // unique) so a rebuild does not silently un-revoke.
-    const existingRevocations = this.entries.filter((e) => e.kind === "revocation");
-    // Preserve tombstone entries from OTHER namespaces when the backing file
-    // is shared (issue #1579 thread Oc2MJ). rebuild rewrites the entire file;
-    // without preserving foreign entries, rebuilding namespace A would
-    // silently delete namespace B's tombstones, allowing resurrection in B.
-    const foreignTombstones = this.entries.filter(
-      (e) => e.kind === "tombstone" && e.namespace !== this.namespace,
-    );
-    // Reuse existing tombstone ids for source-equivalent entries so a prior
-    // revocation (which references the tombstone id) survives rebuild — minting
-    // fresh ids would orphan the revocation and silently un-revoke the content.
-    // Issue #1579 thread Oci-T: key the reuse map by (sourceMemoryId,
-    // supersessionKey), not just sourceMemoryId. A retired fact with multiple
-    // structured-attribute keys emits one record per key (see
-    // collectRetiredMemoriesForRebuild); keying only by sourceMemoryId made
-    // every rebuilt record share one id, so a revocation of key A silently
-    // revoked key B (over-revoke) — or, if a prior single-key tombstone was
-    // revoked, the new multi-key records all inherited a revoked id and
-    // silently un-blocked (orphan). Including the supersession-key
-    // discriminator keeps each keyed tombstone's id (and thus its revocation)
-    // independent. Records without a supersession key fall back to a stable
-    // empty-string discriminator so they still reuse by sourceMemoryId alone.
-    const existingBySource = new Map<string, string>();
-    for (const e of this.entries) {
-      if (e.kind === "tombstone") {
-        existingBySource.set(`${e.sourceMemoryId}\u{0000}${e.supersessionKey ?? ""}`, e.id);
-      }
-    }
-    const rebuilt: TombstoneEntry[] = retiredMemories.map((m) => ({
-      id:
-        existingBySource.get(`${m.memoryId}\u{0000}${m.supersessionKey ?? ""}`) ??
-        newTombstoneId(),
-      kind: "tombstone" as const,
-      reason: m.reason,
-      sourceMemoryId: m.memoryId,
-      contentHash: m.contentHash ?? this.options.hashContent(m.rawContent),
-      normalizedText: this.options.normalizeText(m.rawContent),
-      ...(m.entityRef ? { entityRef: m.entityRef } : {}),
-      ...(m.supersessionKey ? { supersessionKey: m.supersessionKey } : {}),
-      namespace: this.namespace,
-      createdAt: m.createdAt,
-      createdBy: m.createdBy,
-    }));
-    // Sort deterministically (rule 38): createdAt, then id for stability.
-    rebuilt.sort((a, b) =>
-      a.createdAt === b.createdAt
-        ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
-        : a.createdAt < b.createdAt ? -1 : 1,
-    );
-    const all = [...rebuilt, ...existingRevocations, ...foreignTombstones].sort((a, b) =>
-      a.createdAt === b.createdAt
-        ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
-        : a.createdAt < b.createdAt ? -1 : 1,
-    );
-    const serialized = all.map((e) => JSON.stringify(e)).join("\n") + (all.length > 0 ? "\n" : "");
-    await serializeMutations(`tombstone-rebuild:${this.filePath}`, () =>
-      this.io.write(this.filePath, serialized),
+    // The full read-merge-write runs UNDER the cross-process lock (issue #1639,
+    // cursor/codex review): we ensureFreshAgainstDisk() first so the in-memory
+    // index reflects any peer append/revoke that landed while we waited for the
+    // lock, THEN compute the payload. Rebuild rewrites the entire JSONL, so a
+    // payload built from a stale this.entries would overwrite a peer's just-
+    // written entry and resurrect a retired fact — the exact invariant this
+    // store exists to enforce. serializeMutations (in-process) wraps the
+    // cross-process lock; the key is unified with append/revoke so they cannot
+    // interleave in-process either.
+    const rebuiltCount = await serializeMutations(`tombstone:${this.filePath}`, () =>
+      this.withWriteLock(async () => {
+        await this.ensureFreshAgainstDisk();
+        // Preserve existing revocations (all namespaces — ids are globally
+        // unique) so a rebuild does not silently un-revoke.
+        const existingRevocations = this.entries.filter((e) => e.kind === "revocation");
+        // Preserve tombstone entries from OTHER namespaces when the backing
+        // file is shared (issue #1579 thread Oc2MJ). rebuild rewrites the
+        // entire file; without preserving foreign entries, rebuilding
+        // namespace A would silently delete namespace B's tombstones, allowing
+        // resurrection in B.
+        const foreignTombstones = this.entries.filter(
+          (e) => e.kind === "tombstone" && e.namespace !== this.namespace,
+        );
+        // Reuse existing tombstone ids for source-equivalent entries so a prior
+        // revocation (which references the tombstone id) survives rebuild —
+        // minting fresh ids would orphan the revocation and silently un-revoke.
+        // Issue #1579 thread Oci-T: key the reuse map by (sourceMemoryId,
+        // supersessionKey). See the append path above for the full rationale.
+        const existingBySource = new Map<string, string>();
+        for (const e of this.entries) {
+          if (e.kind === "tombstone") {
+            existingBySource.set(`${e.sourceMemoryId}\u{0000}${e.supersessionKey ?? ""}`, e.id);
+          }
+        }
+        const rebuilt: TombstoneEntry[] = retiredMemories.map((m) => ({
+          id:
+            existingBySource.get(`${m.memoryId}\u{0000}${m.supersessionKey ?? ""}`) ??
+            newTombstoneId(),
+          kind: "tombstone" as const,
+          reason: m.reason,
+          sourceMemoryId: m.memoryId,
+          contentHash: m.contentHash ?? this.options.hashContent(m.rawContent),
+          normalizedText: this.options.normalizeText(m.rawContent),
+          ...(m.entityRef ? { entityRef: m.entityRef } : {}),
+          ...(m.supersessionKey ? { supersessionKey: m.supersessionKey } : {}),
+          namespace: this.namespace,
+          createdAt: m.createdAt,
+          createdBy: m.createdBy,
+        }));
+        // Sort deterministically (rule 38): createdAt, then id for stability.
+        rebuilt.sort((a, b) =>
+          a.createdAt === b.createdAt
+            ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+            : a.createdAt < b.createdAt ? -1 : 1,
+        );
+        const all = [...rebuilt, ...existingRevocations, ...foreignTombstones].sort((a, b) =>
+          a.createdAt === b.createdAt
+            ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+            : a.createdAt < b.createdAt ? -1 : 1,
+        );
+        const serialized =
+          all.map((e) => JSON.stringify(e)).join("\n") + (all.length > 0 ? "\n" : "");
+        await this.io.write(this.filePath, serialized);
+        // Update the in-memory index under the same lock so it stays consistent
+        // with the file we just wrote (no window for a lookup to see a stale
+        // index that misses a just-rebuilt entry).
+        this.resetIndex();
+        for (const entry of all) this.indexEntry(entry);
+        this.corruptedLines = 0;
+        this.loaded = true;
+        this.markWritten();
+        return rebuilt.length;
+      }),
     );
-    this.resetIndex();
-    for (const entry of all) this.indexEntry(entry);
-    this.corruptedLines = 0;
-    this.loaded = true;
-    this.markWritten();
-    return rebuilt.length;
+    return rebuiltCount;
   }
 }
 

package/src/local-model-endpoint.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for the local model-lab endpoint resolver + openai-compatible caller
+ * (issue #1585). Pure unit tests — the fetch caller takes an injected
+ * `fetchImpl`, so no network, no GPU, no live server.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  resolveFaithfulnessGateEndpoint,
+  resolveCorrectionIntentEndpoint,
+  callOpenAiCompatibleChat,
+  type EndpointChatMessage,
+} from "./local-model-endpoint.js";
+
+// ---------------------------------------------------------------------------
+// Resolvers
+// ---------------------------------------------------------------------------
+
+test("resolveFaithfulnessGateEndpoint: null when either key empty (default = no pointer)", () => {
+  assert.equal(resolveFaithfulnessGateEndpoint({ extractionFaithfulnessModel: "", extractionFaithfulnessBaseUrl: "" }), null);
+  assert.equal(resolveFaithfulnessGateEndpoint({ extractionFaithfulnessModel: "m", extractionFaithfulnessBaseUrl: "" }), null);
+  assert.equal(resolveFaithfulnessGateEndpoint({ extractionFaithfulnessModel: "", extractionFaithfulnessBaseUrl: "http://x/v1" }), null);
+  // whitespace-only counts as empty.
+  assert.equal(resolveFaithfulnessGateEndpoint({ extractionFaithfulnessModel: "  ", extractionFaithfulnessBaseUrl: "http://x/v1" }), null);
+});
+
+test("resolveFaithfulnessGateEndpoint: returns trimmed endpoint when both keys set", () => {
+  const ep = resolveFaithfulnessGateEndpoint({
+    extractionFaithfulnessModel: "  remnic-faithfulness-gate-v1  ",
+    extractionFaithfulnessBaseUrl: "http://localhost:11434/v1",
+  });
+  assert.deepEqual(ep, { baseUrl: "http://localhost:11434/v1", model: "remnic-faithfulness-gate-v1" });
+});
+
+test("resolveCorrectionIntentEndpoint: same contract as the gate resolver", () => {
+  assert.equal(resolveCorrectionIntentEndpoint({ correctionIntentModel: "", correctionIntentBaseUrl: "" }), null);
+  assert.equal(resolveCorrectionIntentEndpoint({ correctionIntentModel: "m", correctionIntentBaseUrl: "" }), null);
+  assert.deepEqual(
+    resolveCorrectionIntentEndpoint({ correctionIntentModel: "ci-v1", correctionIntentBaseUrl: "http://localhost:8000/v1" }),
+    { baseUrl: "http://localhost:8000/v1", model: "ci-v1" },
+  );
+});
+
+// ---------------------------------------------------------------------------
+// callOpenAiCompatibleChat — injected fetch, no network
+// ---------------------------------------------------------------------------
+
+/** Build a minimal Response-shaped object the caller reads (ok, json, .json). */
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+const MESSAGES: EndpointChatMessage[] = [
+  { role: "system", content: "verifier" },
+  { role: "user", content: "fact vs quote" },
+];
+
+test("callOpenAiCompatibleChat: happy path — first choice content + reported model", async () => {
+  let calledUrl = "";
+  let calledBody: Record<string, unknown> | undefined;
+  const fakeFetch = (url: string, init: RequestInit): Promise<Response> => {
+    calledUrl = url;
+    calledBody = JSON.parse(String(init.body));
+    return Promise.resolve(
+      jsonResponse(200, {
+        model: "remnic-faithfulness-gate-v1",
+        choices: [{ message: { content: '[{"index":0,"verdict":"entailed"}]' } }],
+      }),
+    );
+  };
+  const result = await callOpenAiCompatibleChat(
+    { baseUrl: "http://localhost:11434/v1", model: "remnic-faithfulness-gate-v1" },
+    MESSAGES,
+    { timeoutMs: 5000, temperature: 0.1, maxTokens: 2048, responseFormatJson: true },
+    fakeFetch as typeof fetch,
+  );
+  assert.equal(result?.content, '[{"index":0,"verdict":"entailed"}]');
+  assert.equal(result?.modelUsed, "remnic-faithfulness-gate-v1");
+  // URL joined correctly (no double slash), body carries model + json_object format.
+  assert.equal(calledUrl, "http://localhost:11434/v1/chat/completions");
+  assert.equal(calledBody?.model, "remnic-faithfulness-gate-v1");
+  assert.deepEqual(calledBody?.response_format, { type: "json_object" });
+  assert.equal(calledBody?.max_tokens, 2048);
+});
+
+test("callOpenAiCompatibleChat: trailing slash on baseUrl is tolerated", async () => {
+  const seen = (await callOpenAiCompatibleChat(
+    { baseUrl: "http://localhost:11434/v1/", model: "m" },
+    MESSAGES,
+    { timeoutMs: 1000 },
+    ((url: string) => {
+      assert.equal(url, "http://localhost:11434/v1/chat/completions");
+      return Promise.resolve(jsonResponse(200, { choices: [{ message: { content: "ok" } }] }));
+    }) as typeof fetch,
+  ))!;
+  assert.equal(seen.content, "ok");
+  assert.equal(seen.modelUsed, "m"); // server reported no model → falls back to requested name
+});
+
+test("callOpenAiCompatibleChat: returns null on non-2xx (fail closed)", async () => {
+  const result = await callOpenAiCompatibleChat(
+    { baseUrl: "http://x/v1", model: "m" },
+    MESSAGES,
+    { timeoutMs: 1000 },
+    (() => Promise.resolve(jsonResponse(500, { error: "boom" }))) as typeof fetch,
+  );
+  assert.equal(result, null);
+});
+
+test("callOpenAiCompatibleChat: returns null on network error (fail closed)", async () => {
+  const result = await callOpenAiCompatibleChat(
+    { baseUrl: "http://x/v1", model: "m" },
+    MESSAGES,
+    { timeoutMs: 1000 },
+    (() => Promise.reject(new Error("ECONNREFUSED"))) as typeof fetch,
+  );
+  assert.equal(result, null);
+});
+
+test("callOpenAiCompatibleChat: returns null on malformed body (no fabricated shape)", async () => {
+  for (const body of [
+    null,
+    {},
+    { choices: [] },
+    { choices: [{ message: {} }] },
+    { choices: [{ message: { content: 42 } }] }, // non-string content
+    { choices: "not-an-array" },
+  ]) {
+    const result = await callOpenAiCompatibleChat(
+      { baseUrl: "http://x/v1", model: "m" },
+      MESSAGES,
+      { timeoutMs: 1000 },
+      (() => Promise.resolve(jsonResponse(200, body))) as typeof fetch,
+    );
+    assert.equal(result, null, `body ${JSON.stringify(body)} should yield null`);
+  }
+});
+
+test("callOpenAiCompatibleChat: returns null on .json() throw", async () => {
+  const result = await callOpenAiCompatibleChat(
+    { baseUrl: "http://x/v1", model: "m" },
+    MESSAGES,
+    { timeoutMs: 1000 },
+    (() =>
+      Promise.resolve(
+        new Response("not-json", { status: 200, headers: { "content-type": "application/json" } }),
+      )) as typeof fetch,
+  );
+  assert.equal(result, null);
+});

package/src/local-model-endpoint.ts

@@ -0,0 +1,189 @@
+/**
+ * Local fine-tuned model endpoint resolver + openai-compatible caller
+ * (issue #1585 model-lab integration).
+ *
+ * Remnic's two classification workloads — the extraction faithfulness gate
+ * (#1576) and passive-correction intent detection (#1581) — can run on small
+ * fine-tuned models served locally (Ollama / vLLM) instead of prompted
+ * frontier LLMs. The model-lab (`model-lab/`) produces those models; this
+ * module is the config-side half: it resolves the optional local endpoint
+ * pointer from config and, when set, makes a minimal openai-compatible
+ * chat-completions call to it.
+ *
+ * Design:
+ *   - **Pointers are optional.** Empty defaults preserve the existing routing
+ *     chain exactly (rule 39 / byte-identical pre-feature). A resolver returns
+ *     `null` when the pointer is unset, so callers short-circuit before any
+ *     network.
+ *   - **Graceful degradation.** A local-endpoint failure (network, non-2xx,
+ *     malformed body, timeout) returns `null`; callers fall back to the
+ *     configured chain (checklist §4 — never block writes on a classifier).
+ *   - **No inline casts.** The fetch JSON is narrowed with `in` / `typeof`
+ *     guards (project rule: never assert a shape to read one property).
+ *   - **Injectable fetch.** `callOpenAiCompatibleChat` takes an optional
+ *     `fetchImpl` so the caller is unit-testable without a live server.
+ */
+
+import type { PluginConfig } from "./types.js";
+
+/** A resolved local endpoint: where to call + which model to name. */
+export interface LocalModelEndpoint {
+  /** Base URL, e.g. `http://localhost:11434/v1` (no trailing slash required). */
+  baseUrl: string;
+  /** Model name the server expects, e.g. `remnic-faithfulness-gate-v1`. */
+  model: string;
+}
+
+/** A chat message in the openai-compatible shape this caller sends. */
+export interface EndpointChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+/** Options for a single local-endpoint chat call. */
+export interface EndpointChatOptions {
+  /** Per-call timeout in ms. The caller's batch AbortSignal is NOT forwarded
+   *  (matches the local-LLM precedent: each attempt is bounded by its own
+   *  timer so one slow server can't starve the batch). */
+  timeoutMs: number;
+  /** Sampling temperature — classification wants low entropy (0.0–0.2). */
+  temperature?: number;
+  /** Max output tokens. */
+  maxTokens?: number;
+  /** Request JSON-object output (the gate emits a JSON verdict array). */
+  responseFormatJson?: boolean;
+}
+
+/** Result of a local-endpoint chat call. */
+export interface EndpointChatResult {
+  content: string;
+  /** The model the server reports it used (falls back to the requested name). */
+  modelUsed: string;
+}
+
+/**
+ * Resolve the faithfulness-gate local endpoint from config (issue #1585).
+ *
+ * Returns the endpoint only when BOTH a base URL and a model name are
+ * configured; otherwise `null` (gate uses its existing routing chain). The
+ * gate's verifier needs a model identity, so a base URL alone is intentionally
+ * insufficient — silently calling whatever the server's default model is would
+ * be an unreviewed behavioral change.
+ */
+export function resolveFaithfulnessGateEndpoint(
+  config: Pick<PluginConfig, "extractionFaithfulnessModel" | "extractionFaithfulnessBaseUrl">,
+): LocalModelEndpoint | null {
+  const baseUrl = config.extractionFaithfulnessBaseUrl.trim();
+  const model = config.extractionFaithfulnessModel.trim();
+  if (!baseUrl || !model) return null;
+  return { baseUrl, model };
+}
+
+/**
+ * Resolve the correction-intent local endpoint from config (issue #1581/#1585).
+ *
+ * Same contract as the gate resolver. Consumption by the model-backed
+ * detector is the consuming child's job — the rule-based
+ * `detectPassiveCorrections` remains the default path; this pointer lets a
+ * future model-backed detector route to a fine-tuned local classifier when an
+ * operator configures one.
+ */
+export function resolveCorrectionIntentEndpoint(
+  config: Pick<PluginConfig, "correctionIntentModel" | "correctionIntentBaseUrl">,
+): LocalModelEndpoint | null {
+  const baseUrl = config.correctionIntentBaseUrl.trim();
+  const model = config.correctionIntentModel.trim();
+  if (!baseUrl || !model) return null;
+  return { baseUrl, model };
+}
+
+type FetchLike = typeof fetch;
+
+/**
+ * Make an openai-compatible chat-completions call to a local endpoint.
+ *
+ * POSTs to `${baseUrl}/chat/completions` with `{ model, messages, ... }` and
+ * returns the first choice's content. Any failure (non-2xx, network error,
+ * malformed body, timeout) returns `null` so callers fall back gracefully.
+ *
+ * The response is narrowed with runtime guards — never an unchecked cast — so
+ * a surprising server response fails closed (`null`) rather than reading a
+ * fabricated field.
+ */
+export async function callOpenAiCompatibleChat(
+  endpoint: LocalModelEndpoint,
+  messages: EndpointChatMessage[],
+  options: EndpointChatOptions,
+  fetchImpl: FetchLike = fetch,
+): Promise<EndpointChatResult | null> {
+  const url = joinBaseUrl(endpoint.baseUrl, "/chat/completions");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const body: Record<string, unknown> = {
+      model: endpoint.model,
+      messages,
+      temperature: options.temperature ?? 0.1,
+    };
+    if (typeof options.maxTokens === "number") {
+      body.max_tokens = options.maxTokens;
+    }
+    if (options.responseFormatJson) {
+      body.response_format = { type: "json_object" };
+    }
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch {
+      // Network error or abort — fail closed, let the caller fall back.
+      return null;
+    }
+    if (!response.ok) return null;
+    const parsed: unknown = await response.json().catch(() => null);
+    const content = extractFirstChoiceContent(parsed);
+    if (content === null) return null;
+    return { content, modelUsed: extractModel(parsed) ?? endpoint.model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Join a base URL and a path, tolerating a trailing slash on the base. */
+function joinBaseUrl(base: string, path: string): string {
+  return base.endsWith("/") ? `${base.slice(0, -1)}${path}` : `${base}${path}`;
+}
+
+/**
+ * Narrow the openai-compatible response and pull the first choice's content.
+ *
+ * `in` / `typeof` guards only — no `as` cast (project rule). Returns `null`
+ * for any shape that isn't `{ choices: [{ message: { content: string } }, …] }`.
+ */
+function extractFirstChoiceContent(data: unknown): string | null {
+  if (!data || typeof data !== "object") return null;
+  // After `in`, TS narrows the property to `unknown` — read it directly, no cast.
+  if (!("choices" in data) || !Array.isArray(data.choices)) return null;
+  const choices: unknown[] = data.choices;
+  for (const choice of choices) {
+    if (!choice || typeof choice !== "object") continue;
+    if (!("message" in choice)) continue;
+    const message = choice.message;
+    if (!message || typeof message !== "object") continue;
+    if (!("content" in message)) continue;
+    const content = message.content;
+    if (typeof content === "string" && content.length > 0) return content;
+  }
+  return null;
+}
+
+/** Narrow the `model` field from the response (best-effort, may be absent). */
+function extractModel(data: unknown): string | null {
+  if (!data || typeof data !== "object" || !("model" in data)) return null;
+  const model = data.model;
+  return typeof model === "string" && model.length > 0 ? model : null;
+}