@remnic/core 9.45.3 → 9.45.5

package/src/extraction-source-grounding.test.ts

@@ -2112,39 +2112,6 @@ test("grounding scopes nested entity facts to the enclosing entity", () => {
   }]);
 });
 
-test("grounding preserves punctuation in technology identifiers", () => {
-  const cppResult = filterExtractionResultBySource(
-    {
-      facts: [{
-        category: "fact",
-        content: "Alice uses C++.",
-        confidence: 0.9,
-        tags: [],
-      }],
-      profileUpdates: [],
-      entities: [],
-      questions: [],
-    },
-    "Alice uses C.",
-  );
-  const plainCResult = filterExtractionResultBySource(
-    {
-      facts: [{
-        category: "fact",
-        content: "Alice uses C.",
-        confidence: 0.9,
-        tags: [],
-      }],
-      profileUpdates: [],
-      entities: [],
-      questions: [],
-    },
-    "Alice uses C++.",
-  );
-
-  assert.deepEqual(cppResult.facts, []);
-  assert.deepEqual(plainCResult.facts, []);
-});
 
 test("grounding requires unresolved questions on the asserted target turn", () => {
   const result = filterExtractionResultBySource(
@@ -2321,6 +2288,214 @@ test("grounding aligns predicates after medial source modifiers", () => {
   }
 });
 
+test("grounding normalizes regular third-person verb inflections", () => {
+  for (const [source, content] of [
+    ["Alice deploys Acme.", "Alice deployed Acme."],
+    ["Alice designs Atlas.", "Alice designed Atlas."],
+    ["Alice manages Beacon.", "Alice managed Beacon."],
+    ["Alice plans Atlas.", "Alice planned Atlas."],
+    ["Alice stops Beacon.", "Alice stopped Beacon."],
+    ["Alice tries again.", "Alice tried again."],
+    ["They add tags.", "They added tags."],
+    ["They call Alice.", "They called Alice."],
+    ["They fill forms.", "They filled forms."],
+    ["Alice Smith plans Atlas.", "Alice Smith planned Atlas."],
+    ["Alice King works at Acme.", "Alice King worked at Acme."],
+  ]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts.map((fact) => fact.content), [content]);
+  }
+});
+
+test("grounding keeps silent-e compatibility out of proper identifiers", () => {
+  for (const [source, content] of [
+    ["Alice works at Strip.", "Alice works at Stripe."],
+    ["Alice met Kat.", "Alice met Kate."],
+    ["Alice owns Plan.", "Alice planned."],
+  ]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts, []);
+  }
+});
+
+test("grounding preserves lowercase identifier tokens ending in s", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [{ category: "fact", content: "alice deployed atla.", confidence: 0.9, tags: [] }],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+    },
+    "alice deployed atlas.",
+  );
+
+  assert.deepEqual(result.facts, []);
+});
+
+test("grounding role normalization matches exact-marked identifiers case-insensitively", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [],
+      profileUpdates: ["User works at Stripe."],
+      entities: [],
+      questions: [],
+    },
+    "I work at stripe.",
+    undefined,
+    { profile: "I work at stripe.", identity: "" },
+  );
+
+  assert.deepEqual(result.profileUpdates, ["User works at Stripe."]);
+});
+
+test("grounding does not stem role-source identifiers ending in s", () => {
+  for (const content of ["User uses Redi.", "User uses Redis."]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [],
+        profileUpdates: [content],
+        entities: [],
+        questions: [],
+      },
+      "I use redis.",
+      undefined,
+      { profile: "I use redis.", identity: "" },
+    );
+    assert.deepEqual(
+      result.profileUpdates,
+      content.endsWith("Redis.") ? [content] : [],
+    );
+  }
+});
+
+test("grounding does not treat role-source object plurals as predicates", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [],
+      profileUpdates: ["User planned."],
+      entities: [],
+      questions: [],
+    },
+    "I own plans.",
+    undefined,
+    { profile: "I own plans.", identity: "" },
+  );
+
+  assert.deepEqual(result.profileUpdates, []);
+});
+
+test("grounding falls back to explicitly role-labeled source sentences", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [],
+      profileUpdates: ["User prefers tea."],
+      entities: [],
+      questions: [],
+    },
+    "User prefers tea.",
+    undefined,
+    { profile: "", identity: "" },
+  );
+
+  assert.deepEqual(result.profileUpdates, ["User prefers tea."]);
+});
+
+test("grounding uses the main source when a role source is omitted", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [],
+      profileUpdates: ["User prefers tea."],
+      entities: [],
+      questions: [],
+    },
+    "I prefer tea.",
+    undefined,
+    { identity: "" },
+  );
+
+  assert.deepEqual(result.profileUpdates, ["User prefers tea."]);
+});
+
+test("grounding keeps C, C++, and C# identifiers pairwise distinct", () => {
+  const identifiers = ["C", "C++", "C#"];
+  for (const sourceIdentifier of identifiers) {
+    for (const candidateIdentifier of identifiers) {
+      const content = `Alice uses ${candidateIdentifier}.`;
+      const result = filterExtractionResultBySource(
+        {
+          facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+          profileUpdates: [],
+          entities: [],
+          questions: [],
+        },
+        `Alice uses ${sourceIdentifier}.`,
+      );
+      assert.deepEqual(
+        result.facts.map((fact) => fact.content),
+        sourceIdentifier === candidateIdentifier ? [content] : [],
+      );
+    }
+  }
+});
+
+
+test("grounding inherits coordinated subjects and predicates", () => {
+  for (const [source, content] of [
+    ["Alice works at Acme and owns Mars.", "Alice owns Mars."],
+    ["Alice uses PostgreSQL, Redis, and Kafka.", "Alice uses Kafka."],
+  ]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts.map((fact) => fact.content), [content]);
+  }
+});
+
+test("grounding does not inherit across explicit coordinated subjects", () => {
+  for (const [source, content] of [
+    ["Alice works at Acme and Bob owns Mars.", "Alice owns Mars."],
+    ["Alice works at Acme and Bob sleeps.", "Alice sleeps."],
+    ["Alice works at Acme, Bob called Alice, and designed Mars.", "Alice designed Mars."],
+    ["Alice works at Acme and Bob can swim.", "Alice can swim."],
+    ["Acme works with Alice, Acme Labs called Bob, and designed Mars.", "Acme designed Mars."],
+    ["Alice works at Acme and Bob went home.", "Alice went home."],
+    ["Alice works at Acme and Bob ate lunch.", "Alice ate lunch."],
+  ]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts, []);
+  }
+});
+
 test("grounding requires causal evidence before removing why questions", () => {
   const question = { question: "Why did Alice deploy Acme?", context: "", priority: 0.5 };
   const unanswered = filterExtractionResultBySource(
@@ -2335,3 +2510,158 @@ test("grounding requires causal evidence before removing why questions", () => {
   );
   assert.deepEqual(answered.questions, []);
 });
+
+test("grounding rejects partial assertions from source disjunctions", () => {
+  for (const source of [
+    "Alice uses Redis or PostgreSQL.",
+    "Does Alice use Redis or PostgreSQL?\nYes.",
+  ]) {
+    for (const content of ["Alice uses Redis.", "Alice uses PostgreSQL."]) {
+      const result = filterExtractionResultBySource(
+        {
+          facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+          profileUpdates: [],
+          entities: [],
+          questions: [],
+        },
+        source,
+      );
+      assert.deepEqual(result.facts, []);
+    }
+  }
+
+  for (const source of [
+    "Alice uses Redis or PostgreSQL.",
+    "Does Alice use Redis or PostgreSQL?\nYes.",
+  ]) {
+    const content = "Alice uses Redis or PostgreSQL.";
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts.map((fact) => fact.content), [content]);
+  }
+
+  const commonPrefix = filterExtractionResultBySource(
+    {
+      facts: [{
+        category: "fact",
+        content: "Alice uses Redis.",
+        confidence: 0.9,
+        tags: [],
+      }],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+    },
+    "Alice uses Redis for cache hits or misses.",
+  );
+  assert.deepEqual(
+    commonPrefix.facts.map((fact) => fact.content),
+    ["Alice uses Redis."],
+  );
+});
+
+test("grounding aligns object wh-question answers by subject and predicate", () => {
+  for (const [questionText, answer, roleReversedAnswer] of [
+    [
+      "What database does Alice use?",
+      "Alice uses PostgreSQL as the database.",
+      "PostgreSQL uses Alice as the database.",
+    ],
+    ["Who does Alice employ?", "Alice employs Bob.", "Bob employs Alice."],
+    ["Whom does Alice employ?", "Alice employs Bob.", "Bob employs Alice."],
+    ["Who does Alice work with?", "Alice works with Bob.", "Bob works with Alice."],
+    ["Whom does Alice connect to?", "Alice connects to Bob.", "Bob connects to Alice."],
+  ]) {
+    const question = { question: questionText, context: "", priority: 0.5 };
+    const answered = filterExtractionResultBySource(
+      { facts: [], profileUpdates: [], entities: [], questions: [question] },
+      `${questionText}\n${answer}`,
+    );
+    assert.deepEqual(answered.questions, []);
+
+    const roleReversed = filterExtractionResultBySource(
+      { facts: [], profileUpdates: [], entities: [], questions: [question] },
+      `${questionText}\n${roleReversedAnswer}`,
+    );
+    assert.deepEqual(roleReversed.questions, [question]);
+  }
+});
+
+test("grounding does not stem verb-like object plurals", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [{
+        category: "fact",
+        content: "Alice sells the plan.",
+        confidence: 0.9,
+        tags: [],
+      }],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+    },
+    "Alice sells plans.",
+  );
+
+  assert.deepEqual(result.facts, []);
+});
+
+test("grounding recognizes capitalized predicates in subjectless role fragments", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [],
+      profileUpdates: ["User uses Redis."],
+      entities: [],
+      questions: [],
+    },
+    "Uses Redis.",
+    undefined,
+    { profile: "Uses Redis.", identity: "" },
+  );
+
+  assert.deepEqual(result.profileUpdates, ["User uses Redis."]);
+});
+
+test("grounding keeps sentence-initial plural subjects distinct", () => {
+  const result = filterExtractionResultBySource(
+    {
+      facts: [{
+        category: "fact",
+        content: "Plan is active.",
+        confidence: 0.9,
+        tags: [],
+      }],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+    },
+    "Plans are active.",
+  );
+
+  assert.deepEqual(result.facts, []);
+});
+
+test("grounding preserves plural identifiers after a proper-name copular subject", () => {
+  for (const [source, content] of [
+    ["Alice is atlas.", "Alice is atla."],
+    ["Alice is the atlas.", "Alice is the atla."],
+  ]) {
+    const result = filterExtractionResultBySource(
+      {
+        facts: [{ category: "fact", content, confidence: 0.9, tags: [] }],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+      },
+      source,
+    );
+    assert.deepEqual(result.facts, []);
+  }
+});

package/src/extraction-timeout.test.ts

@@ -205,6 +205,7 @@ test("extraction skips mechanical action telemetry without durable memory cues",
     profileUpdates: [],
     entities: [],
     questions: [],
+    extractionSkippedReason: "mechanical_telemetry",
   });
 });
 

package/src/extraction-watermark.test.ts

@@ -64,6 +64,49 @@ test("aggregate watermark selects the most recent extraction across distinct nam
   }
 });
 
+test("aggregate stats sum extraction counts and select the newest consolidation", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: {
+        dir: fixture.memoryDir,
+        loadMeta: async () => ({
+          lastExtractionAt: "2026-07-20T12:00:00.000Z",
+          extractionCount: 2,
+          lastConsolidationAt: "2026-07-20T13:00:00.000Z",
+        }),
+      },
+      storageForNamespace: async (namespace, rootDir) => ({
+        dir: rootDir,
+        loadMeta: async () => ({
+          lastExtractionAt:
+            namespace === "team-a"
+              ? "2026-07-21T12:00:00.000Z"
+              : "2026-07-22T12:00:00.000Z",
+          extractionCount:
+            namespace === "team-a"
+              ? 3
+              : namespace === fixture.config.sharedNamespace
+                ? 7
+                : 5,
+          lastConsolidationAt:
+            namespace === "team-a"
+              ? "2026-07-23T13:00:00.000Z"
+              : "2026-07-21T13:00:00.000Z",
+        }),
+      }),
+    });
+
+    assert.deepEqual(result.rootStats, {
+      extractionCount: 17,
+      lastConsolidationAt: "2026-07-23T13:00:00.000Z",
+    });
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("a namespace-isolated extraction advances the daemon aggregate watermark", async () => {
   const fixture = await namespacedFixture();
   try {
@@ -89,7 +132,14 @@ test("a partial namespace read returns readFailed instead of a survivor's fresh
   try {
     const result = await readAggregateExtractionWatermark({
       config: fixture.config,
-      rootStorage: storage(fixture.memoryDir, async () => "2026-07-23T12:00:00.000Z"),
+      rootStorage: {
+        dir: fixture.memoryDir,
+        loadMeta: async () => ({
+          lastExtractionAt: "2026-07-23T12:00:00.000Z",
+          extractionCount: 2,
+          lastConsolidationAt: null,
+        }),
+      },
       storageForNamespace: async (namespace) =>
         storage(fixture.namespaceDirs[namespace], async () => {
           if (namespace === "team-b") throw new Error("meta store unavailable");
@@ -101,6 +151,7 @@ test("a partial namespace read returns readFailed instead of a survivor's fresh
     assert.equal(result.readFailed, true);
     assert.match(result.readError ?? "", /namespace watermark unreadable/);
     assert.match(result.readError ?? "", /meta store unavailable/);
+    assert.equal(result.rootStats, undefined, "partial aggregate counters must not be reported");
   } finally {
     await rm(fixture.memoryDir, { recursive: true, force: true });
   }
@@ -136,17 +187,27 @@ test("default root capability check uses normalized aliases for migrated storage
       rootStorage: storage(fixture.memoryDir, async () => {
         throw new Error("inactive legacy root is unreadable");
       }),
-      storageForNamespace: async (_namespace, rootDir) =>
-        storage(rootDir, async () =>
-          path.resolve(rootDir) === path.resolve(migratedDefaultDir)
-            ? "2026-07-26T12:00:00.000Z"
-            : "2026-07-24T12:00:00.000Z",
-        ),
+      storageForNamespace: async (_namespace, rootDir) => ({
+        dir: rootDir,
+        loadMeta: async () => ({
+          lastExtractionAt:
+            path.resolve(rootDir) === path.resolve(migratedDefaultDir)
+              ? "2026-07-26T12:00:00.000Z"
+              : "2026-07-24T12:00:00.000Z",
+          extractionCount:
+            path.resolve(rootDir) === path.resolve(migratedDefaultDir) ? 7 : 11,
+          lastConsolidationAt: null,
+        }),
+      }),
       caps: { version: TOKEN_CAPABILITIES_VERSION, namespaces: ["default"] },
     });
 
     assert.equal(result.lastExtractionAt, "2026-07-26T12:00:00.000Z");
     assert.equal(result.readFailed, false);
+    assert.deepEqual(result.rootStats, {
+      extractionCount: 7,
+      lastConsolidationAt: null,
+    });
   } finally {
     await rm(fixture.memoryDir, { recursive: true, force: true });
   }
@@ -169,6 +230,88 @@ test("unparsable non-null timestamp in namespace store fails the aggregate read"
   }
 });
 
+test("overflowed calendar timestamp in namespace store fails the aggregate read", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-20T12:00:00.000Z"),
+      storageForNamespace: async (namespace) =>
+        storage(
+          fixture.namespaceDirs[namespace],
+          async () =>
+            namespace === "team-a"
+              ? "2026-02-30T12:00:00.000Z"
+              : "2026-07-25T12:00:00.000Z",
+        ),
+    });
+
+    assert.equal(result.lastExtractionAt, null);
+    assert.equal(result.readFailed, true);
+    assert.match(result.readError ?? "", /watermark timestamp invalid/);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("valid ISO timestamp variants remain eligible for aggregate watermark selection", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-19t24:00:00z"),
+      storageForNamespace: async (namespace) =>
+        storage(
+          fixture.namespaceDirs[namespace],
+          async () =>
+            namespace === "team-a"
+              ? "2026-07-20t12:00:00z"
+              : "2026-07-20T08:00:00-0500",
+        ),
+    });
+
+    assert.equal(result.lastExtractionAt, "2026-07-20T08:00:00-0500");
+    assert.equal(result.readFailed, false);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("overflowed consolidation timestamp in namespace store fails the aggregate read", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: {
+        dir: fixture.memoryDir,
+        loadMeta: async () => ({
+          lastExtractionAt: "2026-07-20T12:00:00.000Z",
+          extractionCount: 2,
+          lastConsolidationAt: "2026-07-20T13:00:00.000Z",
+        }),
+      },
+      storageForNamespace: async (namespace) => ({
+        dir: fixture.namespaceDirs[namespace],
+        loadMeta: async () => ({
+          lastExtractionAt: "2026-07-21T12:00:00.000Z",
+          extractionCount: 3,
+          lastConsolidationAt:
+            namespace === "team-a"
+              ? "2026-02-30T13:00:00.000Z"
+              : "2026-07-21T13:00:00.000Z",
+        }),
+      }),
+    });
+
+    assert.equal(result.lastExtractionAt, null);
+    assert.equal(result.readFailed, true);
+    assert.equal(result.rootStats, undefined);
+    assert.match(result.readError ?? "", /consolidation timestamp invalid/);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("namespace discovery I/O failure is an explicit incomplete read", async () => {
   const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-extraction-watermark-enumeration-"));
   try {

package/src/extraction.ts

@@ -1161,7 +1161,13 @@ export class ExtractionEngine {
     };
     if (renderedConversation.trim().length === 0) {
       log.debug("extraction skipped — conversation only contained non-memory work-layer context");
-      return { facts: [], profileUpdates: [], entities: [], questions: [] };
+      return {
+        facts: [],
+        profileUpdates: [],
+        entities: [],
+        questions: [],
+        extractionSkippedReason: "conversation_only_non_memory",
+      };
     }
     if (
       lifecycleCaps.extractionTelemetryPrefilter &&
@@ -1173,6 +1179,7 @@ export class ExtractionEngine {
         profileUpdates: [],
         entities: [],
         questions: [],
+        extractionSkippedReason: "mechanical_telemetry",
       };
     }
 

package/src/index.ts

@@ -9,11 +9,6 @@
  * This package has ZERO OpenClaw imports — it can be consumed by
  * any host adapter (CLI, HTTP server, MCP server, etc.).
  *
- * Usage:
- *   import { Orchestrator, parseConfig } from "@remnic/core";
- *   const config = parseConfig({ memoryDir: "/tmp/mem" });
- *   const orch = new Orchestrator(config);
- *   await orch.initialize();
  */
 
 // ---------------------------------------------------------------------------
@@ -28,6 +23,8 @@ export { resolvePluginEntry, type PluginEntryResolverOptions } from "./plugin-en
 
 export { parseConfig, isOpenaiApiKeyDisabled, resolveEnvVars } from "./config.js";
 export { resolveRemnicConfigRecord } from "./config-record.js";
+export * from "./external-wiki.js";
+export * from "./external-wiki-cli.js";
 export {
   parseFlexibleIsoTimestamp,
   parseIsoOffsetTimestamp,
@@ -111,6 +108,7 @@ export {
   serializeEntityFile,
   type MemoryWriteResult,
 } from "./storage.js";
+export { withRawEntityPageMutation } from "./storage/entity-canonical-id-lock.js";
 export {
   composeMemoryEnvelope,
   buildAccessWriteRequestFingerprint,
@@ -836,6 +834,7 @@ export {
   OFFLINE_SYNC_CHANGESET_FORMAT,
   OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES,
+  OFFLINE_SYNC_MAX_MTIME_MS,
   OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
   OFFLINE_SYNC_SNAPSHOT_FORMAT,
   OFFLINE_SYNC_STATE_VERSION,
@@ -850,8 +849,10 @@ export {
   compileOfflineSyncExcludeGlobs,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
+  filterOfflineSyncDeletionRevisions,
   globToRegExp,
   iterateOfflineSyncSnapshotFileRecords,
+  isInternalRemnicStatePath,
   normalizeOfflineSyncChangeset,
   normalizeOfflineSyncSnapshot,
   offlineSyncStateFromSnapshot,
@@ -868,9 +869,12 @@ export {
   type OfflineSyncChange,
   type OfflineSyncChangeset,
   type OfflineSyncConflict,
+  type OfflineSyncDeletionRevision,
+  type OfflineSyncFileDeleteTarget,
   type OfflineSyncFileDigest,
   type OfflineSyncFileRecord,
   type OfflineSyncFileContentChunk,
+  type OfflineSyncRecordDeletionRevision,
   type OfflineSyncFileState,
   type OfflineSyncFileTarget,
   type OfflineSyncFileWriteTarget,