@remnic/core 9.45.3 → 9.45.5

package/dist/write-envelope.d.ts

@@ -1,7 +1,8 @@
-import { v as MemoryCategory } from './types-rEwubvim.js';
+import { w as MemoryCategory } from './types-yX_FwERf.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';
+import './external-wiki-config.js';
 import './types-continuity.js';
 
 /**

package/package.json

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

package/src/abort-error.ts

@@ -44,3 +44,20 @@ export function throwIfAborted(
     throw abortError(message);
   }
 }
+
+export function raceAbort<T>(
+  promise: Promise<T>,
+  signal?: AbortSignal,
+  message = "operation aborted",
+): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortError(message));
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(abortError(message));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  return Promise.race([promise, aborted]).finally(() => {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  });
+}

package/src/access-admin-ops-surface.ts

@@ -850,6 +850,7 @@ export class AccessAdminOpsSurface {
           lineage: memory.lineage,
           sourceMemoryId: memory.sourceMemoryId,
           actor: memory.actor,
+          ...(memory.toolScoped ? { toolScoped: true as const } : {}),
         });
         // #1645: a tombstone-blocked promotion lands pending_review (no active
         // copy in the target). Report it as a failed promotion so the admin

package/src/access-boundary.ts

@@ -37,6 +37,7 @@ import { expandTildePath } from "./utils/path.js";
 export const OPERATION_NAMES = [
   "memory_get",
   "memory_search",
+  "external_wiki_search",
   "memory_store",
   "coding_decision",
   "coding_architecture",

package/src/access-coding-context-resolution.ts

@@ -0,0 +1,42 @@
+import { projectTagProjectId } from "./coding/coding-namespace.js";
+import { resolveGitContext } from "./coding/git-context.js";
+import type { CodingContext } from "./types.js";
+
+export interface InterruptibleCodingScopeInput {
+  cwd?: string;
+  projectTag?: string;
+  abortSignal?: AbortSignal;
+  deadlineMs?: number;
+}
+
+export async function resolveCodingContextFromOptions(
+  options: InterruptibleCodingScopeInput,
+): Promise<CodingContext | null> {
+  if (typeof options.projectTag === "string" && options.projectTag.trim().length > 0) {
+    const projectId = projectTagProjectId(options.projectTag);
+    return { projectId, branch: null, rootPath: projectId, defaultBranch: null };
+  }
+  if (typeof options.cwd !== "string" || options.cwd.trim().length === 0) return null;
+
+  try {
+    const gitContext = await resolveGitContext(options.cwd, {
+      abortSignal: options.abortSignal,
+      deadlineMs: options.deadlineMs,
+    });
+    if (!gitContext) return null;
+    return {
+      projectId: gitContext.projectId,
+      branch: gitContext.branch,
+      rootPath: gitContext.rootPath,
+      defaultBranch: gitContext.defaultBranch,
+    };
+  } catch (error) {
+    if (
+      options.abortSignal?.aborted ||
+      (options.deadlineMs !== undefined && Date.now() >= options.deadlineMs)
+    ) {
+      throw error;
+    }
+    return null;
+  }
+}

package/src/access-extraction-force-flush.ts

@@ -5,6 +5,7 @@ import {
   type EngramAccessExtractionForceFlushRequest,
   type EngramAccessExtractionForceFlushResponse,
   EngramAccessInputError,
+  type MemoryScopePlan,
 } from "./access-service.js";
 import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { log } from "./logger.js";
@@ -58,9 +59,44 @@ export async function extractionForceFlush(
   };
   let abortHandler: (() => void) | undefined;
 
+  const reservationScopeHint = pendingObserveScopeHint(request);
+  const cancelBeforeScopeResolution = (): void => {
+    const explicitNamespace = request.namespace?.trim();
+    if (explicitNamespace) {
+      deps.cancelPendingObserveExtractions?.(
+        request.sessionKey,
+        authenticatedPrincipal ?? sessionPrincipal,
+        explicitNamespace,
+        reservationScopeHint,
+      );
+      return;
+    }
+    if (reservationScopeHint !== undefined) {
+      deps.cancelPendingObservePreparations?.(request.sessionKey, reservationScopeHint);
+      return;
+    }
+    if (!namespacesEnabled) {
+      deps.cancelPendingObserveExtractions?.(request.sessionKey);
+    }
+  };
+
   try {
-    const scope = await deps.resolveMemoryScopePlan(request);
-    const reservationScopeHint = pendingObserveScopeHint(request);
+    let scope: MemoryScopePlan;
+    try {
+      scope = await awaitSessionFlushPhase(
+        () => deps.resolveMemoryScopePlan(request),
+        {
+          abortSignal: request.abortSignal,
+          extractionDeadlineMs: request.deadlineMs,
+          reason: "access_force_flush",
+          deadlineStage: "scope_resolution",
+          onDeadline: cancelBeforeScopeResolution,
+        },
+      );
+    } catch (error) {
+      if (request.abortSignal?.aborted) cancelBeforeScopeResolution();
+      throw error;
+    }
     const cancelScopedPendingObserveExtractions = (): void => {
       deps.cancelPendingObserveExtractions?.(
         request.sessionKey,

package/src/access-http-lcm-compaction.ts

@@ -22,10 +22,13 @@ export interface LcmCompactionFlushHttpOptions {
   respondJson: JsonResponder;
 }
 
-export function respondLcmCompactionCapabilitiesHttp(response: ServerResponse): void {
+export function respondAccessCapabilitiesHttp(response: ServerResponse): void {
   response.statusCode = 200;
   response.setHeader("content-type", "application/json; charset=utf-8");
-  response.end(JSON.stringify({ lcmCompactionFlushBatch: true }, null, 2));
+  response.end(JSON.stringify({
+    lcmCompactionFlushBatch: true,
+    offlineSyncConvergenceComplete: true,
+  }, null, 2));
 }
 
 export interface LcmCompactionFlushRunnerOptions {

package/src/access-http-offline-stream.ts

@@ -0,0 +1,80 @@
+import type { ServerResponse } from "node:http";
+import type { OfflineSyncManifestStreamResponse } from "./access-offline-manifest.js";
+import type { EngramAccessOfflineSyncSnapshotStreamResponse } from "./access-service.js";
+
+async function respondOfflineNdjsonStream(
+  response: ServerResponse,
+  header: unknown,
+  files: AsyncIterable<unknown>,
+  requestId?: string,
+): Promise<void> {
+  response.statusCode = 200;
+  response.setHeader("content-type", "application/x-ndjson; charset=utf-8");
+  response.setHeader("cache-control", "no-store");
+  if (requestId) response.setHeader("x-request-id", requestId);
+  const waitForDrainOrClose = async (): Promise<boolean> => {
+    const { promise, resolve, reject } = Promise.withResolvers<boolean>();
+    const cleanup = () => {
+      response.off("drain", onDrain);
+      response.off("close", onClose);
+      response.off("error", onError);
+    };
+    const onDrain = () => {
+      cleanup();
+      resolve(true);
+    };
+    const onClose = () => {
+      cleanup();
+      resolve(false);
+    };
+    const onError = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+    response.once("drain", onDrain);
+    response.once("close", onClose);
+    response.once("error", onError);
+    return promise;
+  };
+  const writeLine = async (payload: unknown): Promise<boolean> => {
+    if (response.destroyed || response.writableEnded) return false;
+    if (response.write(`${JSON.stringify(payload)}\n`)) return true;
+    if (response.destroyed || response.writableEnded) return false;
+    return waitForDrainOrClose();
+  };
+  if (!await writeLine(header)) return;
+  for await (const file of files) {
+    if (!await writeLine({ type: "file", file })) return;
+  }
+  if (!response.destroyed && !response.writableEnded) response.end();
+}
+
+export async function respondOfflineSnapshotStream(
+  response: ServerResponse,
+  snapshot: EngramAccessOfflineSyncSnapshotStreamResponse,
+  requestId?: string,
+): Promise<void> {
+  await respondOfflineNdjsonStream(response, {
+    type: "snapshot",
+    namespace: snapshot.namespace,
+    format: snapshot.format,
+    schemaVersion: snapshot.schemaVersion,
+    createdAt: snapshot.createdAt,
+    sourceId: snapshot.sourceId,
+    includeTranscripts: snapshot.includeTranscripts,
+    deletions: snapshot.deletions,
+  }, snapshot.files, requestId);
+}
+
+export async function respondOfflineManifestStream(
+  response: ServerResponse,
+  manifest: OfflineSyncManifestStreamResponse,
+  requestId?: string,
+): Promise<void> {
+  await respondOfflineNdjsonStream(response, {
+    type: "manifest",
+    namespace: manifest.namespace,
+    format: manifest.format,
+    schemaVersion: manifest.schemaVersion,
+  }, manifest.files, requestId);
+}

package/src/access-http.test.ts

@@ -1,12 +1,12 @@
 import assert from "node:assert/strict";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { gzipSync } from "node:zlib";
 
 import { EngramAccessHttpServer, type RemnicAdminControls, type RemnicAdminDashboardStatus } from "./access-http.js";
-import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError, type EngramAccessRecallRequest, type EngramAccessService } from "./access-service.js";
 import { tokenCapabilityStore, type TokenCapabilities } from "./access-token-capabilities.js";
 import { parseConfig } from "./config.js";
 import { readPair, writePair } from "./contradiction/contradiction-review.js";
@@ -858,6 +858,7 @@ test("HTTP offline snapshot forwards namespace and transfer options", async () =
         createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
         sourceId: "remote:test",
         includeTranscripts: options.includeTranscripts !== false,
+        deletions: [{ path: "facts/deleted.md", mtimeMs: 1235 }],
         files: [],
       };
     },
@@ -876,12 +877,18 @@ test("HTTP offline snapshot forwards namespace and transfer options", async () =
       `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/snapshot?namespace=team&include_transcripts=false&content=false`,
       { headers: { authorization: "Bearer test-token" } },
     );
-    const body = await response.json() as { namespace?: string; includeTranscripts?: boolean; files?: unknown[] };
+    const body = await response.json() as {
+      namespace?: string;
+      includeTranscripts?: boolean;
+      files?: unknown[];
+      deletions?: unknown[];
+    };
 
     assert.equal(response.status, 200);
     assert.equal(body.namespace, "team");
     assert.equal(body.includeTranscripts, false);
     assert.deepEqual(body.files, []);
+    assert.deepEqual(body.deletions, [{ path: "facts/deleted.md", mtimeMs: 1235 }]);
     assert.deepEqual(calls, [{
       namespace: "team",
       principal: "reader",
@@ -1016,6 +1023,7 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
         createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
         sourceId: "remote:test",
         includeTranscripts: options.includeTranscripts !== false,
+        deletions: [{ path: "facts/deleted.md", mtimeMs: 1235 }],
         files: (async function* () {
           yield {
             path: "facts/a.md",
@@ -1050,6 +1058,7 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
     assert.equal(response.headers.get("content-type"), "application/x-ndjson; charset=utf-8");
     assert.equal(lines[0]?.type, "snapshot");
     assert.equal(lines[0]?.namespace, "team");
+    assert.deepEqual(lines[0]?.deletions, [{ path: "facts/deleted.md", mtimeMs: 1235 }]);
     assert.equal(lines[1]?.type, "file");
     assert.deepEqual((lines[1]?.file as { path?: string }).path, "facts/a.md");
     assert.deepEqual(calls, [{
@@ -1062,6 +1071,120 @@ test("HTTP offline snapshot stream emits metadata records as NDJSON", async () =
     await server.stop();
   }
 });
+test("HTTP offline manifest stream preserves snapshot-stream auth and emits body-free rows", async () => {
+  const calls: Array<Record<string, unknown>> = [];
+  const service = {
+    offlineSyncManifestStream: async (options: Record<string, unknown>) => {
+      calls.push(options);
+      return {
+        namespace: options.namespace ?? "default",
+        format: "remnic-reconcile-manifest",
+        schemaVersion: 1,
+        files: (async function* () {
+          yield {
+            path: "facts/a.md",
+            sha256: "a".repeat(64),
+            bytes: 12,
+            mtimeMs: 1234,
+            memory: {
+              id: "fact-a",
+              status: "active",
+              category: "fact",
+              contentHash: "b".repeat(64),
+            },
+          };
+        })(),
+      };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    principal: "reader",
+    authTokenEntriesGetter: () => [
+      { token: "wrong-op", capabilities: { version: 1, ops: ["offline_sync_snapshot"] } },
+      {
+        token: "wrong-namespace",
+        capabilities: { version: 1, ops: ["offline_sync_snapshot_stream"], namespaces: ["other"] },
+      },
+      {
+        token: "reader",
+        capabilities: { version: 1, ops: ["offline_sync_snapshot_stream"], namespaces: ["team"] },
+      },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const request = (token: string, query = "namespace=team&include_transcripts=false") =>
+    fetch(`http://127.0.0.1:${status.port}/remnic/v1/offline-sync/manifest-stream?${query}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+  try {
+    assert.equal((await request("wrong-op")).status, 403);
+    assert.equal((await request("wrong-namespace")).status, 403);
+    assert.equal(calls.length, 0);
+    assert.equal((await request("reader", "namespace=team&include_transcripts=invalid")).status, 400);
+    assert.equal((await request("reader", "namespace=team&content=true")).status, 400);
+    assert.equal(calls.length, 0);
+
+    const response = await request("reader");
+    const text = await response.text();
+    const lines = text.trim().split("\n").map((line) => JSON.parse(line) as Record<string, unknown>);
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get("content-type"), "application/x-ndjson; charset=utf-8");
+    assert.equal(lines[0]?.type, "manifest");
+    assert.equal(lines[1]?.type, "file");
+    assert.deepEqual(lines[1]?.file, {
+      path: "facts/a.md",
+      sha256: "a".repeat(64),
+      bytes: 12,
+      mtimeMs: 1234,
+      memory: {
+        id: "fact-a",
+        status: "active",
+        category: "fact",
+        contentHash: "b".repeat(64),
+      },
+    });
+    assert.doesNotMatch(text, /contentBase64|rawContent|memory body/);
+    assert.deepEqual({
+      namespace: calls[0]?.namespace,
+      principal: calls[0]?.principal,
+      includeTranscripts: calls[0]?.includeTranscripts,
+    }, {
+      namespace: "team",
+      principal: "reader",
+      includeTranscripts: false,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP offline sync capabilities advertise manifest streaming", async () => {
+  const server = new EngramAccessHttpServer({
+    service: {} as EngramAccessService,
+    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/offline-sync/capabilities`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), {
+      version: 1,
+      convergenceFinalization: true,
+      manifestStream: true,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 
 test("HTTP offline files forwards namespace and requested paths", async () => {
   const calls: Array<{
@@ -2960,6 +3083,42 @@ test("HTTP chat/message gates the NEW session's namespace — scoped token canno
   }
 });
 
+test("HTTP recall forwards the connector from the authorized token entry", async () => {
+  let captured: EngramAccessRecallRequest | undefined;
+  const service = {
+    recall: (request: EngramAccessRecallRequest) => {
+      captured = request;
+      return Promise.resolve({ context: "", count: 0, memoryIds: [], results: [] });
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authTokenEntriesGetter: () => [
+      { token: "connector-token", connector: "chatgpt" },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/recall`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer connector-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ query: "shared namespace query" }),
+      },
+    );
+    assert.equal(response.status, 200);
+    assert.equal(captured?.sourceConnector, "chatgpt");
+  } finally {
+    await server.stop();
+  }
+});
+
 // ---------------------------------------------------------------------------
 // PR #1852: token-rotation race — authorized entry must be reused for provenance
 // ---------------------------------------------------------------------------
@@ -3649,6 +3808,34 @@ test("HTTP authorization probe verifies requested operation grants without invok
   }
 });
 
+test("HTTP capabilities explicitly advertise receiver convergence finalization", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const route = `http://127.0.0.1:${status.port}/engram/v1/capabilities`;
+    const denied = await fetch(route);
+    assert.equal(denied.status, 401);
+
+    const response = await fetch(route, {
+      headers: { authorization: "Bearer test-token" },
+    });
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), {
+      lcmCompactionFlushBatch: true,
+      offlineSyncConvergenceComplete: true,
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP convergence completion forwards one authenticated namespace batch refresh", async () => {
   const calls: Array<{ namespaces: string[]; principal?: string; sourceId: string }> = [];
   const service = {
@@ -3701,6 +3888,50 @@ test("HTTP convergence completion forwards one authenticated namespace batch ref
   }
 });
 
+test("HTTP convergence completion accepts either receiver mutation grant", async () => {
+  let completions = 0;
+  const service = {
+    offlineSyncFinalizeConvergence: async () => {
+      completions += 1;
+      return { namespaces: ["team"], refreshed: true as const };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authTokenEntriesGetter: () => [
+      { token: "file-token", capabilities: { version: 1, ops: ["offline_sync_apply_file_content"] } },
+      { token: "delete-token", capabilities: { version: 1, ops: ["offline_sync_apply"] } },
+      { token: "read-token", capabilities: { version: 1, ops: ["offline_sync_snapshot"] } },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const route = `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/convergence-complete?namespace=team`;
+  const complete = (token: string) => fetch(route, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "x-remnic-source-id": encodeURIComponent("remnic-converge"),
+    },
+  });
+
+  try {
+    const fileResponse = await complete("file-token");
+    assert.equal(fileResponse.status, 200);
+    await fileResponse.text();
+    const deleteResponse = await complete("delete-token");
+    assert.equal(deleteResponse.status, 200);
+    await deleteResponse.text();
+    const deniedResponse = await complete("read-token");
+    assert.equal(deniedResponse.status, 403);
+    await deniedResponse.text();
+    assert.equal(completions, 2);
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP convergence completion enforces the per-principal write rate limit", async () => {
   let completions = 0;
   const service = {
@@ -3784,3 +4015,79 @@ test("HTTP convergence completion denies scoped tokens that omit the namespace",
     await server.stop();
   }
 });
+
+test("HTTP external wiki search aliases return the same cited result", async () => {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "remnic-http-external-wiki-"));
+  await mkdir(path.join(rootDir, "wiki"), { recursive: true });
+  await writeFile(
+    path.join(rootDir, "INDEX.md"),
+    "- [[wiki/planning|Planning Systems]] - deterministic planner fan-out\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(rootDir, "wiki", "planning.md"),
+    "# Planning Systems\n\nDeterministic planner fan-out keeps cited evidence.\n",
+    "utf8",
+  );
+  const service = {
+    configRef: {
+      externalWikis: [{
+        id: "planning",
+        rootDir,
+        enabled: true,
+        pagesDir: "wiki",
+        indexFile: "INDEX.md",
+        indexInQmd: false,
+        includeInDefaultRecall: false,
+      }],
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    let canonicalBody: unknown;
+    for (const prefix of ["remnic", "engram"]) {
+      const response = await fetch(`http://127.0.0.1:${status.port}/${prefix}/v1/external-wikis/search`, {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          query: "deterministic planner",
+          wikiId: "planning",
+          limit: 2,
+          maxCharsPerHit: 200,
+        }),
+      });
+      assert.equal(response.status, 200);
+      const body: unknown = await response.json();
+      if (canonicalBody === undefined) canonicalBody = body;
+      else assert.deepEqual(body, canonicalBody);
+    }
+    assert.ok(canonicalBody && typeof canonicalBody === "object" && "hits" in canonicalBody);
+    assert.ok(Array.isArray(canonicalBody.hits));
+    const firstHit = canonicalBody.hits[0];
+    assert.ok(firstHit && typeof firstHit === "object" && "path" in firstHit);
+    assert.equal(firstHit.path, "wiki/planning.md");
+
+    const invalid = await fetch(`http://127.0.0.1:${status.port}/remnic/v1/external-wikis/search`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ query: "  " }),
+    });
+    assert.equal(invalid.status, 400);
+  } finally {
+    await server.stop();
+    await rm(rootDir, { recursive: true, force: true });
+  }
+});