@remnic/core 9.21.0 → 9.22.1

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

@@ -215,6 +215,53 @@ export class AccessAdminOpsSurface {
     };
   }
 
+  /**
+   * Operator-triggered bulk drain of the entity synthesis queue (issue #2136).
+   * Every automatic call site processes at most 5 entities per event, which a
+   * busy deployment's queue inflow outruns; this surface drains a bounded
+   * batch on demand. `maxEntities` is clamped to 200 per call so a single
+   * request stays bounded; loop until `processed < requested` to drain fully.
+   */
+  async entitySynthesisRun(
+    request: {
+      namespace?: string;
+      maxEntities?: number;
+      authenticatedPrincipal?: string;
+    },
+    principal?: string,
+  ): Promise<{
+    namespace: string;
+    requested: number;
+    processed: number;
+    remaining: number;
+  }> {
+    const resolvedNamespace = this.deps.writableNamespaceFor(
+      request.namespace,
+      undefined,
+      request.authenticatedPrincipal ?? principal,
+    );
+    let requested = 25;
+    if (request.maxEntities !== undefined) {
+      if (
+        typeof request.maxEntities !== "number"
+        || !Number.isInteger(request.maxEntities)
+        || request.maxEntities < 1
+      ) {
+        throw new Error(
+          `Invalid maxEntities: ${String(request.maxEntities)} (expected an integer >= 1)`,
+        );
+      }
+      requested = Math.min(200, request.maxEntities);
+    }
+    const processed = await this.deps.orchestrator.entitySynthesisCoordinator.processQueue(
+      resolvedNamespace,
+      requested,
+    );
+    const storage = await this.deps.orchestrator.getStorage(resolvedNamespace);
+    const remaining = (await storage.readEntitySynthesisQueue()).length;
+    return { namespace: resolvedNamespace, requested, processed, remaining };
+  }
+
   async conversationIndexUpdate(
     request: {
       sessionKey?: string;

package/src/access-boundary.ts

@@ -75,6 +75,9 @@ export const OPERATION_NAMES = [
   "transcript_day",
   "transcript_search",
   "transcript_memories",
+  "meetings_list",
+  "meetings_get",
+  "meetings_build",
   "action_confidence",
   "chatgpt_memory_inspector",
   "day_summary",
@@ -82,6 +85,7 @@ export const OPERATION_NAMES = [
   "capsule_import",
   "capsule_list",
   "memory_governance_run",
+  "entity_synthesis_run",
   "procedure_mining_run",
   "pattern_reinforcement_run",
   "procedural_stats",

package/src/access-http.test.ts

@@ -2895,3 +2895,66 @@ test("HTTP namespace/writable preflight admits write-scoped tokens and rejects r
     await server.stop();
   }
 });
+
+test("HTTP meetings build enforces the per-principal write rate limit (issue #1937)", async () => {
+  let builds = 0;
+  const service = {
+    meetingsBuild: async (date: string) => {
+      builds += 1;
+      return { enabled: true, date, meetings: [] };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  try {
+    const build = () =>
+      fetch(`http://127.0.0.1:${status.port}/engram/v1/meetings/build`, {
+        method: "POST",
+        headers: { authorization: "Bearer test-token", "content-type": "application/json" },
+        body: JSON.stringify({ date: "2026-03-10" }),
+      });
+    const first = await build();
+    assert.equal(first.status, 200, "the first build is within the write quota");
+    const second = await build();
+    assert.equal(second.status, 429, "the second build exceeds the per-principal write quota");
+    const rateLimited = await second.json() as { code?: string };
+    assert.equal(rateLimited.code, "write_rate_limited");
+    assert.equal(builds, 1, "the rate-limited build never reached the service (no persist/reindex)");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP meetings get returns 400 (not 500) for a malformed percent-encoded id (issue #1900)", async () => {
+  let called = 0;
+  const service = {
+    meetingsGet: async () => {
+      called += 1;
+      return { enabled: true, found: false, id: "x", record: null };
+    },
+  } as unknown as EngramAccessService;
+  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/meetings/%E0%A4%A`, {
+      headers: { authorization: "Bearer test-token" },
+    });
+    assert.equal(response.status, 400, "a malformed id is a client error, not an internal 500");
+    const errorBody = await response.json() as { code?: string };
+    assert.equal(errorBody.code, "invalid_request");
+    assert.equal(called, 0, "the malformed id never reached the service");
+  } finally {
+    await server.stop();
+  }
+});

package/src/access-http.ts

@@ -13,11 +13,12 @@ import { EngramAccessForbiddenError } from "./access-errors.js";
 import {
   EngramAccessInputError,
   type EngramAccessService,
+  type WearablesMeetingsScope,
   type EngramAccessMemoryResponse,
   type EngramAccessWriteResponse,
 } from "./access-service.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
-import { WearablesInputError } from "./wearables/errors.js";
+import { WearablesInputError } from "./wearables/errors.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js";
 import { EngramMcpServer, MCP_SUPPORTED_PROTOCOL_VERSIONS } from "./access-mcp.js";
 import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-schema.js";
 import {
@@ -349,9 +350,7 @@ function decodeRelayMissionIdSegment(raw: string): string {
   try {
     return decodeURIComponent(raw);
   } catch {
-    throw new EngramAccessInputError(
-      "missionId path segment is not valid percent-encoded input",
-    );
+    throw new EngramAccessInputError("missionId path segment is not valid percent-encoded input");
   }
 }
 
@@ -713,6 +712,13 @@ export class EngramAccessHttpServer {
     return this.resolveRequestIdentity(req).principal;
   }
 
+  /** Caller scope for wearables/meetings ops (issue #2123): request principal +
+   *  gated namespace + optional sessionKey, so reads/writes resolve to the caller
+   *  namespace instead of the machine default. */
+  private wearablesScope(req: IncomingMessage, namespace?: string, sessionKey?: string): WearablesMeetingsScope {
+    return { authenticatedPrincipal: this.resolveRequestPrincipal(req), namespace: this.resolveNamespace(req, namespace), ...(sessionKey ? { sessionKey } : {}) };
+  }
+
   /** Resolve namespace: only use the explicit body value. Adapter-inferred namespace
    *  is intentionally NOT used as a fallback for REST requests — omitting namespace
    *  should default to the server's global namespace, not silently scope to an adapter. */
@@ -725,11 +731,7 @@ export class EngramAccessHttpServer {
     // and the id-loaded contradiction routes — one rule, every surface. The
     // effective namespace (explicit OR server default) must be a member; fail
     // closed. No-op for unrestricted tokens (no namespaces allow-list).
-    enforceNamespaceAllowList(
-      tokenCapabilityStore.getStore(),
-      namespace,
-      this.service.configRef?.defaultNamespace,
-    );
+    enforceNamespaceAllowList(tokenCapabilityStore.getStore(), namespace, this.service.configRef?.defaultNamespace);
     return namespace;
   }
 
@@ -1351,11 +1353,7 @@ export class EngramAccessHttpServer {
         req,
         namespaceParam && namespaceParam.length > 0 ? namespaceParam : undefined,
       );
-      const payload = await this.service.recallTierExplain(
-        sessionKey,
-        namespace,
-        this.resolveRequestPrincipal(req),
-      );
+      const payload = await this.service.recallTierExplain(sessionKey, namespace, this.resolveRequestPrincipal(req));
       this.respondJson(res, 200, payload);
       return;
     }
@@ -1493,7 +1491,7 @@ export class EngramAccessHttpServer {
       (pathname === "/engram/v1/wearables/status" || pathname === "/remnic/v1/wearables/status")
     ) {
       this.enforceTokenOp("wearables_status"); // boundary dispatch (issue #1525)
-      this.respondJson(res, 200, await this.service.wearablesStatus());
+      this.respondJson(res, 200, await this.service.wearablesStatus(this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)));
       return;
     }
 
@@ -1524,12 +1522,7 @@ export class EngramAccessHttpServer {
         );
       }
       try {
-        const summaries = await this.service.wearablesSync({
-          source,
-          date,
-          days,
-          forceMemories: body.forceMemories === true,
-        });
+        const summaries = await this.service.wearablesSync({ source, date, days, forceMemories: body.forceMemories === true, ...this.wearablesScope(req, optionalQueryString(body.namespace, "namespace"), optionalQueryString(body.sessionKey, "sessionKey")) });
         this.respondJson(res, 200, { summaries });
       } catch (err) {
         if (this.respondWearablesError(res, err)) return;
@@ -1551,10 +1544,7 @@ export class EngramAccessHttpServer {
       }
       const sourceParam = parsed.searchParams.get("source");
       try {
-        const transcripts = await this.service.wearablesTranscriptDay({
-          date,
-          source: sourceParam && sourceParam.length > 0 ? sourceParam : undefined,
-        });
+        const transcripts = await this.service.wearablesTranscriptDay({ date, source: sourceParam && sourceParam.length > 0 ? sourceParam : undefined, ...this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined) });
         this.respondJson(res, 200, { transcripts });
       } catch (err) {
         if (this.respondWearablesError(res, err)) return;
@@ -1576,13 +1566,7 @@ export class EngramAccessHttpServer {
         );
       }
       try {
-        const results = await this.service.wearablesTranscriptSearch({
-          query: queryParam,
-          source: nonEmptyQueryParam(parsed.searchParams.get("source")),
-          from: nonEmptyQueryParam(parsed.searchParams.get("from")),
-          to: nonEmptyQueryParam(parsed.searchParams.get("to")),
-          limit: positiveIntQueryParam(parsed.searchParams.get("limit"), "limit"),
-        });
+        const results = await this.service.wearablesTranscriptSearch({ query: queryParam, source: nonEmptyQueryParam(parsed.searchParams.get("source")), from: nonEmptyQueryParam(parsed.searchParams.get("from")), to: nonEmptyQueryParam(parsed.searchParams.get("to")), limit: positiveIntQueryParam(parsed.searchParams.get("limit"), "limit"), ...this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined) });
         this.respondJson(res, 200, { results });
       } catch (err) {
         if (this.respondWearablesError(res, err)) return;
@@ -1597,11 +1581,7 @@ export class EngramAccessHttpServer {
     ) {
       this.enforceTokenOp("transcript_memories"); // boundary dispatch (issue #1525)
       try {
-        const memories = await this.service.wearablesTranscriptMemories({
-          source: nonEmptyQueryParam(parsed.searchParams.get("source")),
-          date: nonEmptyQueryParam(parsed.searchParams.get("date")),
-          limit: positiveIntQueryParam(parsed.searchParams.get("limit"), "limit"),
-        });
+        const memories = await this.service.wearablesTranscriptMemories({ source: nonEmptyQueryParam(parsed.searchParams.get("source")), date: nonEmptyQueryParam(parsed.searchParams.get("date")), limit: positiveIntQueryParam(parsed.searchParams.get("limit"), "limit"), ...this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined) });
         this.respondJson(res, 200, { memories });
       } catch (err) {
         if (this.respondWearablesError(res, err)) return;
@@ -1610,6 +1590,15 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (req.method === "GET" && (pathname === "/engram/v1/meetings" || pathname === "/remnic/v1/meetings")) {
+      this.enforceTokenOp("meetings_list"); await respondMeetingsList(res, this.respondJson.bind(this), this.service, nonEmptyQueryParam(parsed.searchParams.get("date")), this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
+    if (req.method === "POST" && (pathname === "/engram/v1/meetings/build" || pathname === "/remnic/v1/meetings/build")) {
+      this.enforceTokenOp("meetings_build"); await respondMeetingsBuild(req, res, this.respondJson.bind(this), this.readJsonBody.bind(this), this.service, { enforceQuota: () => this.ensureWriteRateLimitAvailable(req), recordHit: () => this.recordWriteRateLimitHit(req) }, (ns, sk) => this.wearablesScope(req, ns, sk)); return; }
+    const meetingGetEngram = /^\/engram\/v1\/meetings\/([^/]+)$/.exec(pathname);
+    if (req.method === "GET" && meetingGetEngram) { this.enforceTokenOp("meetings_get"); await respondMeetingsGet(res, this.respondJson.bind(this), this.service, meetingGetEngram[1] ?? "", this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
+    const meetingGetRemnic = /^\/remnic\/v1\/meetings\/([^/]+)$/.exec(pathname);
+    if (req.method === "GET" && meetingGetRemnic) { this.enforceTokenOp("meetings_get"); await respondMeetingsGet(res, this.respondJson.bind(this), this.service, meetingGetRemnic[1] ?? "", this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
+
     if (req.method === "POST" && pathname === "/engram/v1/observe") {
       this.enforceTokenOp("observe"); // boundary dispatch (issue #1525)
       const body = await this.readValidatedBody(req, "observe");
@@ -3224,6 +3213,7 @@ export class EngramAccessHttpServer {
         toolName === "remnic.capsule_export" ||
         toolName === "engram.capsule_import" ||
         toolName === "remnic.capsule_import" ||
+        toolName === "engram.entity_synthesis_run" || toolName === "remnic.entity_synthesis_run" ||
         (
           !dreamsRunDryRun &&
           (toolName === "engram.dreams_run" || toolName === "remnic.dreams_run")

package/src/access-mcp-admin-tools.ts

@@ -0,0 +1,171 @@
+/**
+ * MCP tool-listing entries for the admin/maintenance operation surface
+ * (capsules, governance, entity synthesis, procedure mining, pattern
+ * reinforcement, procedural stats). Extracted from access-mcp.ts (#2136)
+ * to keep the transport file under its structural-ratchet ceiling; the
+ * dispatch name map and operation handlers stay in their existing homes.
+ */
+/** Git-context schema props accepted-and-ignored by every tool (issue #569
+ * compatibility surface) — defined here so the tool tables and the transport
+ * share one copy without an import cycle. */
+export const MCP_GIT_CONTEXT_SCHEMA_PROPS_IGNORED: Record<string, unknown> = {
+  cwd: {
+    type: "string",
+    description: "Accepted for MCP client compatibility (git-context auto-injection); ignored by this tool.",
+  },
+  projectTag: {
+    type: "string",
+    description: "Accepted for MCP client compatibility; ignored by this tool.",
+  },
+};
+
+export const MCP_ADMIN_OPS_TOOLS: Array<{
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}> = [
+{
+  name: "engram.capsule_export",
+  description: "Export a portable Remnic capsule archive from the namespace-scoped memory store.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Capsule id (alphanumeric with single dashes, max 64 characters).",
+      },
+      namespace: { type: "string" },
+      since: {
+        type: "string",
+        description: "Only include files modified on or after this ISO 8601 timestamp.",
+      },
+      includeKinds: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional top-level directory allow-list.",
+      },
+      peerIds: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional peer id allow-list for the peers/ subtree.",
+      },
+      includeTranscripts: { type: "boolean" },
+      encrypt: { type: "boolean" },
+      ...MCP_GIT_CONTEXT_SCHEMA_PROPS_IGNORED,
+    },
+    required: ["name"],
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.capsule_import",
+  description: "Import a Remnic capsule archive into the namespace-scoped memory store.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      archivePath: {
+        type: "string",
+        description: "Path to a .capsule.json.gz or .capsule.json.gz.enc archive.",
+      },
+      namespace: { type: "string" },
+      mode: {
+        type: "string",
+        enum: ["skip", "overwrite", "fork"],
+        description: "Conflict handling mode. Defaults to skip.",
+      },
+      passphrase: {
+        type: "string",
+        description: "Passphrase for encrypted capsule archives.",
+      },
+      ...MCP_GIT_CONTEXT_SCHEMA_PROPS_IGNORED,
+    },
+    required: ["archivePath"],
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.capsule_list",
+  description: "List capsule archives in the namespace-scoped capsule store.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      sessionKey: {
+        type: "string",
+        description:
+          "Optional session key used to derive namespace principal when no trusted transport principal is present.",
+      },
+      ...MCP_GIT_CONTEXT_SCHEMA_PROPS_IGNORED,
+    },
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.memory_governance_run",
+  description: "Run Remnic memory governance in a bounded shadow/apply pass.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      mode: { type: "string", enum: ["shadow", "apply"] },
+      recentDays: { type: "number" },
+      maxMemories: { type: "number" },
+      batchSize: { type: "number" },
+    },
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.entity_synthesis_run",
+  description:
+    "Bulk-drain the entity synthesis queue (issue #2136). Processes up to maxEntities (default 25, max 200) queued entity names into canonical syntheses; loop until processed < requested to drain fully.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      maxEntities: { type: "number" },
+    },
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.procedure_mining_run",
+  description:
+    "Run procedural memory mining from causal trajectories (issue #519). Respects procedural.enabled; writes under procedures/ when clusters qualify.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.pattern_reinforcement_run",
+  description:
+    "Run the pattern-reinforcement maintenance job (issue #687 PR 2/4). Clusters duplicate non-procedural memories by normalized content, promotes the most-recent member to canonical, and supersedes the older duplicates. Gated on patternReinforcementEnabled and the patternReinforcementCadenceMs floor — pass force=true to bypass the cadence for an ad-hoc operator run.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      force: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+},
+{
+  // The canonical `remnic.procedural_stats` alias is added automatically
+  // by `withToolAliases` — the dual-naming invariant keeps both names
+  // alive for the legacy surface.
+  name: "engram.procedural_stats",
+  description:
+    "Procedural memory stats (issue #567): counts by status, recent write activity, and the active procedural.* config. Read-only, namespace-scoped.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+},
+];

package/src/access-mcp-output-schemas.ts

@@ -56,6 +56,16 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
   transcript_day: T_ARRAY,
   transcript_search: T_ARRAY,
   transcript_memories: T_ARRAY,
+  meetings_list: objectSchema({ enabled: T_BOOLEAN, days: T_ARRAY }),
+  meetings_get: objectSchema({ enabled: T_BOOLEAN, found: T_BOOLEAN, id: T_STRING, record: T_NULLABLE_STRING }),
+  meetings_build: objectSchema({
+    date: T_STRING,
+    enabled: T_BOOLEAN,
+    meetings: T_ARRAY,
+    built: T_NUMBER,
+    skipped: T_NUMBER,
+    removed: T_ARRAY,
+  }),
   action_confidence: objectSchema({
     schemaVersion: T_NUMBER,
     decision: T_STRING,
@@ -85,6 +95,12 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
   }),
   capsule_import: objectSchema({ imported: T_ARRAY, skipped: T_ARRAY, manifest: T_OBJECT }),
   capsule_list: objectSchema({ namespace: T_STRING, capsulesDir: T_STRING, capsules: T_ARRAY }),
+  entity_synthesis_run: objectSchema({
+    namespace: T_STRING,
+    requested: T_NUMBER,
+    processed: T_NUMBER,
+    remaining: T_NUMBER,
+  }),
   memory_governance_run: objectSchema({
     namespace: T_STRING,
     runId: T_STRING,