@remnic/core 9.7.15 → 9.9.0

package/src/wearables/memory-gen.ts

@@ -29,6 +29,13 @@
 
 import { scoreImportance } from "../importance.js";
 import type { MemoryWriteResult } from "../storage.js";
+import {
+  composeMemoryEnvelope,
+  type MemoryWriteInput,
+  type SealedMemoryEnvelope,
+  type WriteContext,
+} from "../write-envelope.js";
+import { log } from "../logger.js";
 import type { JudgeBatchResult, JudgeCandidate } from "../extraction-judge.js";
 import { getVerdictKind } from "../extraction-judge.js";
 import { describeErrorForOperator } from "./errors.js";
@@ -61,6 +68,23 @@ import type {
  * anything that is not explicitly "auto" lands in the review queue
  * rather than active recall.
  */
+/**
+ * Compose a wearable-side envelope in salvage mode (issue #1989 PR4):
+ * wearable transcripts and provider-native memories are MACHINE input —
+ * one malformed field must not abort a whole day's sync. Drops are
+ * warn-logged, never silent.
+ */
+function composeSalvagedWearableEnvelope(
+  input: MemoryWriteInput,
+  ctx: WriteContext,
+): SealedMemoryEnvelope {
+  const envelope = composeMemoryEnvelope(input, ctx, { salvage: true });
+  if (envelope.salvageNotes.length > 0) {
+    log.warn(`wearable write salvaged invalid fields: ${envelope.salvageNotes.join("; ")}`);
+  }
+  return envelope;
+}
+
 export function memoryStatusForMode(
   mode: WearableMemoryMode,
 ): Extract<MemoryStatus, "active" | "pending_review"> {
@@ -69,16 +93,14 @@ export function memoryStatusForMode(
 
 /** Narrow writer interface satisfied by `StorageManager`. */
 export interface WearableMemoryWriter {
-  writeMemory(
-    category: MemoryCategory,
-    content: string,
-    options: {
-      confidence?: number;
-      tags?: string[];
-      source?: string;
+  /**
+   * Sealed-envelope write entry point (issue #1989 PR4): cross-cutting
+   * fields ride the composed envelope; per-write extras stay explicit.
+   */
+  writeSealedMemory(
+    envelope: SealedMemoryEnvelope,
+    extras: {
       importance?: ImportanceScore;
-      validAt?: string;
-      structuredAttributes?: Record<string, string>;
       contentHashSource?: string;
       status?: MemoryStatus;
       memoryKind?: "episode" | "note" | "box" | "dream" | "procedural";
@@ -573,22 +595,28 @@ export async function generateWearableMemories(
         wearableDayTag(date),
       ]),
     ];
-    const writeResult = await deps.writer.writeMemory(candidate.fact.category, candidate.fact.content, {
-      confidence:
-        settings.memoryMode === "smart"
-          ? trustById.get(index)?.trust
-          : candidate.fact.confidence,
-      tags,
-      source: wearableSourceLabel(sourceId),
-      importance: candidate.importance,
-      validAt: candidate.conversation.startIso,
-      structuredAttributes: {
-        ...(candidate.fact.structuredAttributes ?? {}),
-        wearableSource: sourceId,
-        wearableDate: date,
-        wearableConversationId: candidate.conversation.id,
-        ...trustAttributes,
+    const factEnvelope = composeSalvagedWearableEnvelope(
+      {
+        content: candidate.fact.content,
+        category: candidate.fact.category,
+        confidence:
+          settings.memoryMode === "smart"
+            ? trustById.get(index)?.trust
+            : candidate.fact.confidence,
+        tags,
+        validAt: candidate.conversation.startIso,
+        structuredAttributes: {
+          ...(candidate.fact.structuredAttributes ?? {}),
+          wearableSource: sourceId,
+          wearableDate: date,
+          wearableConversationId: candidate.conversation.id,
+          ...trustAttributes,
+        },
       },
+      { source: wearableSourceLabel(sourceId) },
+    );
+    const writeResult = await deps.writer.writeSealedMemory(factEnvelope, {
+      importance: candidate.importance,
       contentHashSource: candidate.fact.content,
       status,
     });
@@ -633,21 +661,27 @@ export async function writeDailyDigestMemory(
     `${conversations.length} recorded conversation${conversations.length === 1 ? "" : "s"}.\n` +
     lines.join("\n");
   if (await writer.hasFactContentHash(content)) return false;
-  await writer.writeMemory("moment", content, {
-    confidence: 0.9,
-    tags: [
-      WEARABLE_SOURCE_PREFIX,
-      wearableSourceLabel(sourceId),
-      wearableDayTag(date),
-      "daily-digest",
-    ],
-    source: wearableSourceLabel(sourceId),
-    importance: scoreImportance(content, "moment", ["daily-digest"]),
-    validAt: `${date}T00:00:00.000Z`,
-    structuredAttributes: {
-      wearableSource: sourceId,
-      wearableDate: date,
+  const digestEnvelope = composeSalvagedWearableEnvelope(
+    {
+      content,
+      category: "moment",
+      confidence: 0.9,
+      tags: [
+        WEARABLE_SOURCE_PREFIX,
+        wearableSourceLabel(sourceId),
+        wearableDayTag(date),
+        "daily-digest",
+      ],
+      validAt: `${date}T00:00:00.000Z`,
+      structuredAttributes: {
+        wearableSource: sourceId,
+        wearableDate: date,
+      },
     },
+    { source: wearableSourceLabel(sourceId) },
+  );
+  await writer.writeSealedMemory(digestEnvelope, {
+    importance: scoreImportance(content, "moment", ["daily-digest"]),
     contentHashSource: content,
     status: memoryStatusForMode(settings.memoryMode),
     memoryKind: "episode",
@@ -759,24 +793,30 @@ export async function importNativeMemories(
           : {}),
       };
     }
-    const nativeWriteResult = await deps.writer.writeMemory("fact", content, {
-      confidence,
-      tags: [
-        ...new Set([
-          ...(memory.tags ?? []),
-          WEARABLE_SOURCE_PREFIX,
-          wearableSourceLabel(sourceId),
-          "native-import",
-        ]),
-      ],
-      source: `${wearableSourceLabel(sourceId)}:native`,
-      importance: scoreImportance(content, "fact", memory.tags ?? []),
-      validAt: memory.createdIso,
-      structuredAttributes: {
-        wearableSource: sourceId,
-        wearableNativeId: memory.id,
-        ...trustAttributes,
+    const nativeEnvelope = composeSalvagedWearableEnvelope(
+      {
+        content,
+        category: "fact",
+        confidence,
+        tags: [
+          ...new Set([
+            ...(memory.tags ?? []),
+            WEARABLE_SOURCE_PREFIX,
+            wearableSourceLabel(sourceId),
+            "native-import",
+          ]),
+        ],
+        validAt: memory.createdIso,
+        structuredAttributes: {
+          wearableSource: sourceId,
+          wearableNativeId: memory.id,
+          ...trustAttributes,
+        },
       },
+      { source: `${wearableSourceLabel(sourceId)}:native` },
+    );
+    const nativeWriteResult = await deps.writer.writeSealedMemory(nativeEnvelope, {
+      importance: scoreImportance(content, "fact", memory.tags ?? []),
       contentHashSource: content,
       status,
     });

package/src/wearables/pipeline.test.ts

@@ -8,6 +8,7 @@ import type { ExtractionResult } from "../types.js";
 import { hashTranscriptBody, parseDayTranscript } from "./day-store.js";
 import { saveCorrectionsFile } from "./corrections.js";
 import type { WearableMemoryWriter } from "./memory-gen.js";
+import { sealedWriteToLegacyArgs } from "../write-envelope.js";
 import {
   dateInTimezone,
   resolveSyncDates,
@@ -104,9 +105,11 @@ function makeDeps(memoryDir: string): {
   const memoryWrites: Array<{ category: string; content: string; options: Record<string, unknown> }> = [];
   const files = new Map<string, string>();
   const writer: WearableMemoryWriter = {
-    async writeMemory(category, content, options) {
-      memoryWrites.push({ category, content, options: options as Record<string, unknown> });
-      return { id: `mem-${memoryWrites.length}`, tombstoneBlocked: false };
+    // Production mapper keeps the legacy-shaped recorder faithful (§21).
+    writeSealedMemory: (envelope, extras) => {
+      const { category, content, options } = sealedWriteToLegacyArgs(envelope, extras as Record<string, unknown>);
+      memoryWrites.push({ category, content, options });
+      return Promise.resolve({ id: `mem-${memoryWrites.length}`, tombstoneBlocked: false });
     },
     async hasFactContentHash() {
       return false;
@@ -186,8 +189,8 @@ test("a fact-write failure warns and retries instead of aborting the sync", asyn
     };
     const { deps, memoryWrites } = makeDeps(memoryDir);
     assert.ok(deps.memoryGen);
-    const healthyWrite = deps.memoryGen.writer.writeMemory;
-    deps.memoryGen.writer.writeMemory = async () => {
+    const healthyWrite = deps.memoryGen.writer.writeSealedMemory;
+    deps.memoryGen.writer.writeSealedMemory = async (_envelope, _extras) => {
       throw new Error("storage write exploded");
     };
     const first = await syncWearableSource(fakeConnector(byDate), settings(), config(), { days: 1 }, deps);
@@ -203,7 +206,7 @@ test("a fact-write failure warns and retries instead of aborting the sync", asyn
       "no completion record for a failed pass",
     );
 
-    deps.memoryGen.writer.writeMemory = healthyWrite;
+    deps.memoryGen.writer.writeSealedMemory = healthyWrite;
     const second = await syncWearableSource(fakeConnector(byDate), settings(), config(), { days: 1 }, deps);
     assert.equal(second.memoriesCreated, 1, "retried on the next sync");
     assert.equal(memoryWrites.length, 1);
@@ -318,7 +321,7 @@ test("#1645: a tombstone-blocked wearable write propagates to summary.memoriesBl
     assert.ok(deps.memoryGen, "memory-gen deps wired");
     // Force every extraction write to be tombstone-blocked (#1579): the
     // write lands pending_review with no active copy.
-    deps.memoryGen.writer.writeMemory = async () => ({
+    deps.memoryGen.writer.writeSealedMemory = async (_envelope, _extras) => ({
       id: "blocked-mem-1",
       tombstoneBlocked: true,
       blockedBy: "tomb-1",

package/src/wearables/service.test.ts

@@ -29,6 +29,7 @@ import {
   WearablesService,
   type WearableStorageIo,
 } from "./service.js";
+import { sealedWriteToLegacyArgs } from "../write-envelope.js";
 import { defaultWearablesConfig, defaultWearableSourceSettings } from "./config.js";
 import type { WearableConversation, WearablesConfig } from "./types.js";
 
@@ -124,7 +125,7 @@ function makeStorage(memoryDir: string): WearableStorageIo & {
     async readAllMemories() {
       return storage.memories;
     },
-    async writeMemory() {
+    async writeSealedMemory() {
       return { id: "mem-1", tombstoneBlocked: false };
     },
     async hasFactContentHash() {
@@ -479,14 +480,11 @@ test("support corpus includes pending_review rows and excludes terminal statuses
     const storage = makeStorage(mkdtempSync(path.join(tmpdir(), "remnic-service-mem-")));
     storage.memories.push(...rows);
     const writes: Array<{ options: Record<string, unknown> }> = [];
-    storage.writeMemory = (async (
-      _category: string,
-      _content: string,
-      options: Record<string, unknown>,
-    ) => {
+    storage.writeSealedMemory = ((envelope: Parameters<WearableStorageIo["writeSealedMemory"]>[0], extras: Record<string, unknown>) => {
+      const { options } = sealedWriteToLegacyArgs(envelope, extras);
       writes.push({ options });
-      return { id: `mem-${writes.length}`, tombstoneBlocked: false };
-    }) as WearableStorageIo["writeMemory"];
+      return Promise.resolve({ id: `mem-${writes.length}`, tombstoneBlocked: false });
+    }) as WearableStorageIo["writeSealedMemory"];
     try {
       registerWearableConnector({
         id: "testsource",

package/src/wearables/service.ts

@@ -93,7 +93,7 @@ export interface WearableStorageIo {
       content: string;
     }>
   >;
-  writeMemory: WearableMemoryGenDeps["writer"]["writeMemory"];
+  writeSealedMemory: WearableMemoryGenDeps["writer"]["writeSealedMemory"];
   hasFactContentHash(content: string): Promise<boolean>;
   findWearableMemoryByContent(
     content: string,
@@ -176,7 +176,7 @@ export function createWearableMemoryWriter(
   storage: WearableStorageIo,
 ): WearableMemoryGenDeps["writer"] {
   return {
-    writeMemory: storage.writeMemory.bind(storage),
+    writeSealedMemory: storage.writeSealedMemory.bind(storage),
     findWearableMemoryByContent: async (content: string) =>
       (await storage.findWearableMemoryByContent(content)) as
         | { id: string; status: import("../types.js").MemoryStatus | undefined }

package/src/write-envelope.extension.test.ts

@@ -0,0 +1,111 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  buildWriteIdempotencyPayload,
+  composeMemoryEnvelope,
+  FINGERPRINT_EXEMPT_FIELDS,
+  WRITE_FINGERPRINT_FIELDS,
+  type MemoryWriteInput,
+} from "./write-envelope.js";
+
+/**
+ * Issue #1989 (umbrella #1988) — the LIVING demonstration of the invariant
+ * this series exists to establish:
+ *
+ *   Adding a cross-cutting memory-write field is a ONE-MODULE change
+ *   (write-envelope.ts) plus a registry entry — never a scattered
+ *   call-site hunt.
+ *
+ * The success metric (umbrella decision D) is that the next cross-cutting
+ * envelope change (location tagging, #1976, is queued) merges with ≤5
+ * missed-path review threads, versus 25+ on #1852. This test documents and
+ * mechanically enforces the recipe such a change follows:
+ *
+ *   1. Add the field to `MemoryWriteInput` (input) and `SealedMemoryEnvelope`
+ *      (output) in write-envelope.ts, with normalization in the composer.
+ *   2. Classify it in EXACTLY ONE registry: `WRITE_FINGERPRINT_FIELDS`
+ *      (identity — changes dedup) or `FINGERPRINT_EXEMPT_FIELDS`
+ *      (provenance/scoring — never identity). The type-level assertions in
+ *      write-envelope.ts REFUSE to compile an unclassified or
+ *      doubly-classified field.
+ *   3. Map it in `sealedWriteToLegacyArgs` (one mapper, storage + stubs) —
+ *      and decide its access-surface representation, which the
+ *      `UncoveredAccessFingerprintField` assertion forces explicitly.
+ *
+ * Every write path then carries the field automatically: extraction,
+ * promotions, wearables, coding/correction/admin surfaces, tools — all
+ * compose through this module, enforced by scripts/check-envelope-belt.mjs.
+ *
+ * The synthetic-field walkthrough below exercises the same machinery a real
+ * field would ride, WITHOUT modifying production interfaces: it proves the
+ * fingerprint payload derives from the registry (not from hand-listed
+ * fields), so a registry entry IS the propagation.
+ */
+
+test("fingerprint payloads derive from the registry - a registry entry propagates without call-site edits", () => {
+  const input: MemoryWriteInput = {
+    content: "User prefers dark mode",
+    category: "preference",
+    tags: ["ui"],
+    entityRef: "person-test",
+    ttl: "2027-01-01T00:00:00.000Z",
+    validAt: "2026-06-01T00:00:00.000Z",
+    sourceConnector: "cli",
+    structuredAttributes: { theme: "dark" },
+    confidence: 0.9,
+    sourceReason: "unit demo",
+  };
+  const envelope = composeMemoryEnvelope(input, { source: "extension-demo" });
+  const payload = buildWriteIdempotencyPayload(envelope, { surface: "memory_store" });
+  const fields = payload.fields;
+  assert.ok(fields && typeof fields === "object" && !Array.isArray(fields), "payload carries a fields map");
+  const fieldNames = Object.keys(fields);
+
+  // Every registry field present on the envelope appears in the payload…
+  for (const field of WRITE_FINGERPRINT_FIELDS) {
+    assert.ok(fieldNames.includes(field), `registry field ${field} missing from payload`);
+  }
+  // …and every exempt field is absent. The payload builder iterates the
+  // REGISTRY - it has no hand-written field list to forget.
+  for (const field of FINGERPRINT_EXEMPT_FIELDS) {
+    assert.equal(fieldNames.includes(field), false, `exempt field ${field} leaked into the payload`);
+  }
+});
+
+test("the registry is exhaustive by construction: source text carries the compile-time assertions", () => {
+  // The type-level guards cannot be observed at runtime, so pin their
+  // presence in the source: deleting them would silently re-open the
+  // unclassified-field gap this series closed.
+  const source = readFileSync(
+    path.resolve(import.meta.dirname, "write-envelope.ts"),
+    "utf8",
+  );
+  assert.match(
+    source,
+    /UnclassifiedField extends never \? true : never/,
+    "the every-field-classified assertion must remain",
+  );
+  assert.match(
+    source,
+    /DoublyClassifiedField extends never \? true : never/,
+    "the no-double-classification assertion must remain",
+  );
+  assert.match(
+    source,
+    /UncoveredAccessFingerprintField extends never\s*\?\s*true\s*:\s*never/,
+    "the access-surface coverage assertion must remain",
+  );
+});
+
+test("scope fields ride beside registry fields: a new surface names itself, not the fields", () => {
+  const envelope = composeMemoryEnvelope(
+    { content: "scoped demo", category: "fact" },
+    { source: "extension-demo" },
+  );
+  const a = buildWriteIdempotencyPayload(envelope, { surface: "memory_store", namespace: "default" });
+  const b = buildWriteIdempotencyPayload(envelope, { surface: "wearable-sync", namespace: "default" });
+  assert.notDeepEqual(a, b, "different surfaces must mint different payloads");
+  assert.deepEqual(a.fields, b.fields, "surface identity lives in scope, never in the field set");
+});