@remnic/core 9.3.712 → 9.3.713

package/src/access-mcp.test.ts

@@ -477,6 +477,7 @@ test("MCP session override is injected only into tools that accept sessionKey",
     namespace: undefined,
     authenticatedPrincipal: undefined,
     skipExtraction: false,
+    idempotencyKey: undefined,
     cwd: undefined,
     projectTag: undefined,
   });

package/src/access-mcp.ts

@@ -50,6 +50,12 @@ type McpRequestOptions = {
   sessionKeyOverride?: string;
   sessionId?: string;
   correlationId?: string;
+  /**
+   * Write-quota enforcer forwarded into observe's idempotency lock
+   * (issue #1649). Only the MCP-over-HTTP transport supplies this (it owns
+   * the write-rate-limit window); the standalone MCP server has no quota.
+   */
+  enforceWriteQuota?: () => void | Promise<void>;
 };
 
 type McpTool = {
@@ -1156,6 +1162,11 @@ export class EngramMcpServer {
               },
               description: "Conversation messages to observe",
             },
+            idempotencyKey: {
+              type: "string",
+              description:
+                "Optional idempotency key (issue #1649). Deduplicates a retried observe POST server-side so the batch is ingested once even when the HTTP response is lost. Reusing the key with a different payload is rejected.",
+            },
             namespace: { type: "string" },
             skipExtraction: { type: "boolean" },
             cwd: { type: "string", description: "Working directory for auto git-context resolution." },
@@ -2374,7 +2385,7 @@ export class EngramMcpServer {
           argumentsObject = { ...argumentsObject, sessionKey: options.sessionKeyOverride };
         }
         const effectivePrincipal = options?.principalOverride ?? this.authenticatedPrincipal;
-        const result = await this.callTool(name, argumentsObject, effectivePrincipal, options?.sessionId);
+        const result = await this.callTool(name, argumentsObject, effectivePrincipal, options?.sessionId, options?.enforceWriteQuota);
         return {
           jsonrpc: "2.0",
           id,
@@ -2562,7 +2573,7 @@ export class EngramMcpServer {
       }));
   }
 
-  private async callTool(name: string, args: Record<string, unknown>, effectivePrincipal?: string, mcpSessionId?: string): Promise<unknown> {
+  private async callTool(name: string, args: Record<string, unknown>, effectivePrincipal?: string, mcpSessionId?: string, enforceWriteQuota?: () => void | Promise<void>): Promise<unknown> {
     // Migrated operations dispatch through the access boundary (issue #1525):
     // one registry entry owns schema validation, normalization (rules
     // 17/28/36/48/51), and error mapping for every surface. The switch
@@ -3104,21 +3115,27 @@ export class EngramMcpServer {
         );
       case "engram.observe": {
         const body = parseMcpRequest("observe", args);
-        return this.service.observe({
-          sessionKey: body.sessionKey,
-          messages: body.messages.map((message) => ({
-            role: message.role,
-            content: message.content,
-            parts: message.parts ?? undefined,
-            rawContent: message.rawContent ?? undefined,
-            sourceFormat: message.sourceFormat ?? undefined,
-          })),
-          namespace: body.namespace,
-          authenticatedPrincipal: effectivePrincipal,
-          skipExtraction: body.skipExtraction === true,
-          cwd: body.cwd,
-          projectTag: body.projectTag,
-        });
+        return this.service.observe(
+          {
+            sessionKey: body.sessionKey,
+            messages: body.messages.map((message) => ({
+              role: message.role,
+              content: message.content,
+              parts: message.parts ?? undefined,
+              rawContent: message.rawContent ?? undefined,
+              sourceFormat: message.sourceFormat ?? undefined,
+            })),
+            skipExtraction: body.skipExtraction === true,
+            idempotencyKey: body.idempotencyKey,
+            namespace: body.namespace,
+            authenticatedPrincipal: effectivePrincipal,
+            cwd: body.cwd,
+            projectTag: body.projectTag,
+          },
+          // Forward the transport's write-quota enforcer into observe's
+          // idempotency lock so a replay is never 429'd (issue #1649).
+          enforceWriteQuota ? { enforceWriteQuota } : undefined,
+        );
       }
       case "engram.lcm_search":
         return this.service.lcmSearch({

package/src/access-schema.ts

@@ -216,6 +216,14 @@ export const observeRequestSchema = z.object({
   messages: z.array(messageSchema).min(1, "messages must be a non-empty array"),
   namespace: namespaceSchema,
   skipExtraction: z.boolean().optional(),
+  /**
+   * Optional idempotency key for server-side dedup of retried observe POSTs
+   * (issue #1649). A retry that reaches the daemon after the first attempt
+   * already processed is replayed from cache instead of re-ingested. When the
+   * key is reused with a DIFFERENT payload the request is rejected as a
+   * conflict (same contract as memory_store/suggestion_submit).
+   */
+  idempotencyKey: idempotencyKeySchema,
   /** Working directory for auto git-context resolution (issue #569). */
   cwd: z.string().trim().min(1, "cwd must be non-empty when provided").max(2048).optional(),
   /**

package/src/access-service-observe-idempotency.test.ts

@@ -0,0 +1,308 @@
+/**
+ * #1649: a retried observe POST (same `idempotencyKey`) must be deduplicated
+ * server-side — the batch is ingested exactly once even when the HTTP response
+ * is lost and the client replays the request. Without the key the daemon
+ * re-runs every side effect under `skipDedupeCheck: true` and the turn is
+ * queued for extraction twice.
+ *
+ * Verified here against the `EngramAccessService.observe` path with a stub
+ * orchestrator that records every namespace-bearing side effect (LCM enqueue +
+ * extraction replay), the same probe shape used by the #1495 observe-scope
+ * tests. The idempotency store is filesystem-backed, so `memoryDir` is a real
+ * temp directory (not the synthetic path the scope tests use, which never touch
+ * the store because they omit the key).
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError } from "./access-service.js";
+import { Orchestrator } from "./orchestrator.js";
+import type { EngramAccessObserveRequest } from "./access-service.js";
+import type { CodingContext, PluginConfig } from "./types.js";
+
+interface ObserveProbe {
+  orch: Orchestrator;
+  contexts: Map<string, CodingContext>;
+  lcmCalls: Array<{ sessionKey: string }>;
+  extractionCalls: Array<{
+    sessionKeys: string[];
+    writeNamespaceOverride?: string;
+    principalOverride?: string;
+  }>;
+}
+
+function makeObserveProbe(memoryDir: string): ObserveProbe {
+  const contexts = new Map<string, CodingContext>();
+  const lcmCalls: ObserveProbe["lcmCalls"] = [];
+  const extractionCalls: ObserveProbe["extractionCalls"] = [];
+
+  const config = {
+    namespacesEnabled: true,
+    defaultNamespace: "default",
+    sharedNamespace: "shared",
+    namespacePolicies: [
+      { name: "pi-geek", readPrincipals: ["pi-geek"], writePrincipals: ["pi-geek"] },
+    ],
+    codingMode: { projectScope: true },
+    memoryDir,
+    // Disable objective-state snapshots so the probe doesn't need a writable
+    // storage backend — the idempotency contract under test is LCM + extraction.
+    objectiveStateMemoryEnabled: false,
+    objectiveStateSnapshotWritesEnabled: false,
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [{ match: "pi-geek:", principal: "pi-geek" }],
+    recallCrossNamespaceBudgetEnabled: false,
+    recallCrossNamespaceBudgetWindowMs: 60_000,
+    recallCrossNamespaceBudgetSoftLimit: 10,
+    recallCrossNamespaceBudgetHardLimit: 30,
+  } as unknown as PluginConfig;
+
+  const orch = {
+    config,
+    getCodingContextForSession: (sk: string | undefined) =>
+      (sk ? contexts.get(sk) : null) ?? null,
+    setCodingContextForSession: (sk: string, ctx: CodingContext | null) => {
+      if (ctx === null) contexts.delete(sk);
+      else contexts.set(sk, ctx);
+    },
+    applyCodingNamespaceOverlay: (sk: string | undefined, base: string) =>
+      Orchestrator.prototype.applyCodingNamespaceOverlay.call(orch, sk, base),
+    getStorage: async (ns: string) => ({ dir: join(memoryDir, "storage", ns) }),
+    lcmEngine: {
+      enabled: true,
+      enqueueObserveMessages: (sessionKey: string) => {
+        lcmCalls.push({ sessionKey });
+      },
+    },
+    ingestReplayBatch: async (
+      turns: Array<{ sessionKey: string }>,
+      options: { writeNamespaceOverride?: string; principalOverride?: string } = {},
+    ) => {
+      extractionCalls.push({
+        sessionKeys: turns.map((t) => t.sessionKey),
+        writeNamespaceOverride: options.writeNamespaceOverride,
+        principalOverride: options.principalOverride,
+      });
+    },
+  } as unknown as Orchestrator;
+
+  return { orch, contexts, lcmCalls, extractionCalls };
+}
+
+function observeRequest(
+  overrides: Partial<EngramAccessObserveRequest>,
+): EngramAccessObserveRequest {
+  return {
+    sessionKey: "pi-geek:abc123",
+    messages: [
+      { role: "user", content: "what database are we using?" },
+      { role: "assistant", content: "we use postgres for the primary store" },
+    ],
+    ...overrides,
+  } as EngramAccessObserveRequest;
+}
+
+test("#1649 a retried observe with the same idempotencyKey is deduplicated to a single ingest", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-idem-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-pi-geek-abc123-#1";
+
+    const first = await service.observe(observeRequest({ idempotencyKey: key }));
+    // First attempt is a real ingest.
+    assert.equal(first.idempotencyReplay, undefined, "first attempt is not a replay");
+    assert.equal(probe.extractionCalls.length, 1, "first attempt ingests once");
+    assert.equal(probe.lcmCalls.length, 1, "first attempt archives LCM once");
+
+    // Retry: same key, same payload — the daemon already processed the body, so
+    // this is the response-lost-after-process case the issue describes.
+    const second = await service.observe(observeRequest({ idempotencyKey: key }));
+    assert.equal(second.idempotencyReplay, true, "retry is served from the cache");
+    assert.equal(second.accepted, first.accepted, "retry reports the same accepted count");
+    assert.equal(
+      second.effectiveNamespace,
+      first.effectiveNamespace,
+      "retry reports the same effective namespace",
+    );
+
+    // The defining contract: NO second ingest, NO second LCM archive.
+    assert.equal(probe.extractionCalls.length, 1, "retry must not queue extraction a second time");
+    assert.equal(probe.lcmCalls.length, 1, "retry must not archive LCM a second time");
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 observe without an idempotencyKey is never deduplicated (backward compatible)", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-nokey-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+
+    await service.observe(observeRequest({}));
+    await service.observe(observeRequest({}));
+
+    assert.equal(probe.extractionCalls.length, 2, "no key ⇒ both calls ingest");
+    assert.equal(probe.lcmCalls.length, 2, "no key ⇒ both calls archive LCM");
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 reusing an idempotencyKey with a divergent payload is rejected as a conflict", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-conflict-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-pi-geek-abc123-#2";
+
+    await service.observe(observeRequest({ idempotencyKey: key }));
+
+    // Same key, DIFFERENT messages — a stale key must never silently mask a
+    // unrelated batch. Same contract as memory_store/suggestion_submit.
+    await assert.rejects(
+      service.observe(
+        observeRequest({
+          idempotencyKey: key,
+          messages: [
+            { role: "user", content: "completely different question" },
+            { role: "assistant", content: "completely different answer" },
+          ],
+        }),
+      ),
+      (err: unknown) =>
+        err instanceof EngramAccessInputError &&
+        /idempotencyKey reuse conflict/.test(err.message),
+      "divergent payload under a reused key must throw a conflict",
+    );
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 review fix: enforceWriteQuota runs only on a cache miss, never on a replay", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-quota-hook-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-pi-geek-abc123-#3";
+    let quotaChecks = 0;
+    const enforceWriteQuota = () => {
+      quotaChecks += 1;
+    };
+
+    await service.observe(observeRequest({ idempotencyKey: key }), { enforceWriteQuota });
+    assert.equal(quotaChecks, 1, "quota is enforced exactly once on the real ingest");
+
+    const replay = await service.observe(observeRequest({ idempotencyKey: key }), { enforceWriteQuota });
+    assert.equal(replay.idempotencyReplay, true, "second call is a replay");
+    assert.equal(quotaChecks, 1, "quota is NOT re-checked on a replay (response-lost retry must not 429)");
+    assert.equal(probe.extractionCalls.length, 1, "replay did not re-ingest");
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 review fix: the same idempotencyKey under a different principal is a conflict, not a silent replay", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-principal-conflict-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-shared-key-#4";
+
+    // Principal alice ingests under the key.
+    await service.observe(
+      observeRequest({ idempotencyKey: key, authenticatedPrincipal: "alice" }),
+    );
+
+    // A different principal reusing the same key + same body must NOT replay
+    // alice's cached response — the fingerprint folds in authenticatedPrincipal,
+    // so this is a conflict (defends against cross-identity replay when the
+    // principal is supplied out-of-band via HTTP/MCP auth).
+    await assert.rejects(
+      service.observe(
+        observeRequest({ idempotencyKey: key, authenticatedPrincipal: "bob" }),
+      ),
+      (err: unknown) =>
+        err instanceof EngramAccessInputError &&
+        /idempotencyKey reuse conflict/.test(err.message),
+      "cross-principal key reuse must throw a conflict",
+    );
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 review fix: rebinding the session's ambient coding context makes the same key a conflict", async () => {
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-ambient-scope-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-ambient-scope-#5";
+    const req = observeRequest({ idempotencyKey: key });
+
+    // No explicit namespace/cwd/projectTag and no ambient context yet — the
+    // scope resolves to the default store. This caches the response.
+    await service.observe(req);
+    assert.equal(probe.extractionCalls.length, 1, "first observe ingests once");
+
+    // The session is now rebound to a coding project by an external caller
+    // (e.g. a memory_store with cwd, or a direct setCodingContextForSession).
+    // The resolved writeNamespace changed, so reusing the same key + same body
+    // must NOT silently replay — it is a conflict.
+    probe.contexts.set(req.sessionKey, {
+      projectId: "tag:remnic",
+      branch: null,
+      rootPath: "/projects/remnic",
+      defaultBranch: null,
+    });
+
+    await assert.rejects(
+      service.observe(req),
+      (err: unknown) =>
+        err instanceof EngramAccessInputError &&
+        /idempotencyKey reuse conflict/.test(err.message),
+      "key reuse after ambient scope rebind must throw a conflict, not silently replay",
+    );
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1649 review fix: projectTag observe replays correctly despite scope resolution side effects", async () => {
+  // The fingerprint folds in the RESOLVED writeNamespace (not the raw ambient
+  // context). resolveMemoryScopePlan seeds the session context from projectTag
+  // on the first call; the replay reads the SAME seeded context and resolves the
+  // SAME writeNamespace. This proves the fingerprint is stable across replays
+  // even though the scope resolution mutates session state on the first call.
+  const memoryDir = mkdtempSync(join(tmpdir(), "remnic-observe-tag-replay-"));
+  try {
+    const probe = makeObserveProbe(memoryDir);
+    const service = new EngramAccessService(probe.orch);
+    const key = "observe-batch-tag-replay-#6";
+    const req = observeRequest({ idempotencyKey: key, projectTag: "remnic" });
+
+    const first = await service.observe(req);
+    assert.equal(first.idempotencyReplay, undefined, "first attempt is a real ingest");
+
+    // The first observe's resolveMemoryScopePlan seeded a coding context for
+    // this session. Verify it was actually set (the side effect we depend on).
+    assert.ok(
+      probe.contexts.get(req.sessionKey),
+      "first observe seeded a coding context via resolveMemoryScopePlan",
+    );
+
+    // Retry with the same key + same body + same projectTag — the pre-resolved
+    // writeNamespace matches because the seeded context produces the same scope.
+    const replay = await service.observe(req);
+    assert.equal(replay.idempotencyReplay, true, "projectTag observe replays despite scope-resolution side effects");
+    assert.equal(probe.extractionCalls.length, 1, "replay did not re-ingest");
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/access-service.ts

@@ -1008,6 +1008,8 @@ export interface EngramAccessObserveRequest {
   namespace?: string;
   authenticatedPrincipal?: string;
   skipExtraction?: boolean;
+  /** Optional idempotency key (issue #1649): a retried POST with the same key is deduplicated server-side; divergent reuse is a conflict. */
+  idempotencyKey?: string;
   /**
    * Working directory of the calling agent session (issue #569 wiring).
    * When provided and no `codingContext` is attached for this session,
@@ -1067,6 +1069,8 @@ export interface EngramAccessObserveResponse {
   scopeDebug?: EngramAccessScopeDebug;
   lcmArchived: boolean;
   extractionQueued: boolean;
+  /** True when replayed from the idempotency cache (issue #1649); lets the HTTP surface skip the write-quota slot, matching memory_store replay semantics. */
+  idempotencyReplay?: boolean;
 }
 
 export interface EngramAccessLcmSearchRequest {
@@ -2523,8 +2527,8 @@ export class EngramAccessService {
     }
   }
 
-  private async handleIdempotentWrite<T extends EngramAccessWriteResponse>(options: {
-    operation: T["operation"];
+  private async handleIdempotentWrite<T extends { idempotencyReplay?: boolean }>(options: {
+    operation: string;
     idempotencyKey?: string;
     requestFingerprint: unknown;
     skip?: boolean;
@@ -5700,7 +5704,63 @@ export class EngramAccessService {
     return shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts);
   }
 
-  async observe(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse> {
+  async observe(
+    request: EngramAccessObserveRequest,
+    hooks?: { enforceWriteQuota?: () => void | Promise<void> },
+  ): Promise<EngramAccessObserveResponse> {
+    // Issue #1649: dedup retried observe POSTs server-side. A retry with the
+    // same `idempotencyKey` replays the cached response and skips every side
+    // effect (LCM/extraction/objective-state); divergent payload OR principal
+    // reuse is a conflict (fingerprint folds in authenticatedPrincipal, so a
+    // cross-identity replay can never be silent). `enforceWriteQuota` runs as
+    // `beforeExecute` inside the lock — only on a real miss — so a response-lost
+    // retry never 429s even when the first attempt filled the window (#1434).
+    //
+    // The fingerprint folds in the EFFECTIVE coding context (#1649 codex P2):
+    // runObserve's scope can be derived from the session's ATTACHED coding
+    // context (which takes PRECEDENCE over per-call cwd/projectTag per
+    // resolveMemoryScopePlan), so neither cwd/projectTag NOR the raw ambient
+    // context alone fully captures the effective scope. The effective context
+    // is computed the SAME way resolveMemoryScopePlan does — session-attached
+    // first, per-call cwd/projectTag fallback — but READ-ONLY: it does NOT seed
+    // the session, so a conflict/quota-rejection path leaves no orphaned binding.
+    // The value is stable across replays because resolveMemoryScopePlan's
+    // seeding writes the IDENTICAL context that resolveCodingContextFromOptions
+    // derives — so getCodingContextForSession returns the same object on the
+    // replay as resolveCodingContextFromOptions returned on the first call.
+    // Only computed when a key is present; non-keyed observes skip the work.
+    const idempotencyKey = request.idempotencyKey?.trim();
+    let effectiveCodingContext: CodingContext | null | undefined;
+    if (idempotencyKey && !(typeof request.namespace === "string" && request.namespace.trim().length > 0)) {
+      // Explicit namespace pins the scope (resolveMemoryScopePlan returns early),
+      // so the coding context is irrelevant — skip it to avoid false conflicts
+      // when the session context changes under a namespace-pinned observe.
+      // resolveCodingContextFromOptions self-gates on projectScope (no scattered
+      // config read here).
+      effectiveCodingContext =
+        (typeof this.orchestrator.getCodingContextForSession === "function"
+          ? this.orchestrator.getCodingContextForSession(request.sessionKey)
+          : null) ?? (await this.resolveCodingContextFromOptions(request));
+    }
+    return this.handleIdempotentWrite<EngramAccessObserveResponse>({
+      operation: "observe",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        sessionKey: request.sessionKey,
+        messages: request.messages,
+        namespace: request.namespace,
+        skipExtraction: request.skipExtraction,
+        authenticatedPrincipal: request.authenticatedPrincipal,
+        cwd: request.cwd,
+        projectTag: request.projectTag,
+        effectiveCodingContext: effectiveCodingContext ?? null,
+      },
+      beforeExecute: hooks?.enforceWriteQuota,
+      execute: () => this.runObserve(request),
+    });
+  }
+
+  private async runObserve(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse> {
     if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
       throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
     }