@remnic/core 9.3.683 → 9.3.685

package/src/provenance.ts

@@ -0,0 +1,305 @@
+/**
+ * Claim-level provenance spans (issue #1575 PR 1).
+ *
+ * Centralizes the parse/serialize logic for the `sources` array and the
+ * coarse `provenance` strength tag, plus the `provenance` config-block
+ * parser.  Extracted from `storage.ts` and `config.ts` so those files keep
+ * only thin delegation call-sites — the frontmatter round-trip and config
+ * parsing growth lives here (issue #1520 ratchet discipline).
+ *
+ * Contract:
+ *  - When no provenance fields are present, output is byte-identical to
+ *    pre-feature behavior (rule 39).
+ *  - Corrupt `sources` lines / unknown `provenance` tags drop to
+ *    `undefined` on read so a malformed frontmatter never poisons
+ *    downstream readers (rule 34 spirit — drop corrupt rather than poison).
+ *  - Validation lives on the write path; this module only parses.
+ *  - Invariant (review round 5, cursor thread KQN): a `verified` or
+ *    `unverified` tag is NEVER persisted/read without surviving sources —
+ *    without excerpts the tag is indistinguishable from a grounded fact to
+ *    downstream faithfulness/correction/TrustScore surfaces. The invariant
+ *    is enforced symmetrically: `serializeProvenanceFields` (write) and
+ *    `reconcileProvenanceRead` (read) both downgrade the tag to `none`
+ *    when no source survives.
+ */
+
+import { z } from "zod";
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { readEnvVar } from "./runtime/env.js";
+import type { MemoryFrontmatter, ProvenanceConfig, ProvenanceSource } from "./types.js";
+
+/**
+ * Canonical key order for a serialized `ProvenanceSource` (issue #1575).
+ * Deterministic emission (rule 38) — readers and the byte-identical-when-off
+ * contract (rule 39) depend on this order never drifting.
+ */
+const PROVENANCE_SOURCE_KEY_ORDER = [
+  "sessionKey",
+  "turnId",
+  "observedAt",
+  "quote",
+  "charStart",
+  "charEnd",
+] as const;
+
+/**
+ * Build a single `ProvenanceSource` object whose keys appear in the canonical
+ * order, omitting absent optional fields. The result is what gets fed to
+ * `JSON.stringify` so the on-disk line is deterministic.
+ */
+function canonicalProvenanceSource(src: ProvenanceSource): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of PROVENANCE_SOURCE_KEY_ORDER) {
+    const value = src[key];
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Serialize the `sources` array (issue #1575) as a single JSON line, matching
+ * the `structuredAttributes` precedent. Each entry is rebuilt in canonical key
+ * order (rule 38) so the output is byte-stable. The `provenance` enum is
+ * emitted bare (same style as `status`) — only the three documented values
+ * are ever written.
+ *
+ * Verified-requires-evidence invariant (review round 5, cursor thread KQN):
+ * a `verified`/`unverified` tag is downgraded to `none` whenever no source
+ * survives write validation — whether sources were absent, an empty array,
+ * or all entries failed the schema. This covers all three failure shapes the
+ * earlier 3-branch logic left open (`{provenance:"verified"}`,
+ * `{sources:[],provenance:"verified"}`, `{sources:[invalid…],provenance:"verified"}`).
+ */
+export function serializeProvenanceFields(fm: MemoryFrontmatter, lines: string[]): void {
+  let hasValidSources = false;
+  if (fm.sources && fm.sources.length > 0) {
+    // Validate each entry against the same schema used on read so invalid
+    // in-memory sources are dropped at write time, not silently lost on the
+    // next read (review thread 4 — write-path validation parity).
+    const canonical: Record<string, unknown>[] = [];
+    for (const src of fm.sources) {
+      const result = ProvenanceSourceSchema.safeParse(src);
+      if (result.success) canonical.push(canonicalProvenanceSource(result.data));
+    }
+    if (canonical.length > 0) {
+      lines.push(`sources: ${JSON.stringify(canonical)}`);
+      hasValidSources = true;
+    }
+  }
+  // A verified/unverified tag requires surviving evidence; without it the
+  // tag is meaningless downstream (faithfulness/TrustScore cannot distinguish
+  // it from a grounded fact). Downgrade to "none" regardless of WHY no source
+  // survived (absent / empty / all-invalid) — single invariant, all cases.
+  const tag =
+    (fm.provenance === "verified" || fm.provenance === "unverified") && !hasValidSources
+      ? "none"
+      : fm.provenance;
+  if (tag) {
+    lines.push(`provenance: ${tag}`);
+  }
+}
+
+/**
+ * Parse the coarse `provenance` strength tag (issue #1575). Returns
+ * `undefined` for missing/blank/unknown values so a corrupt or hand-edited
+ * field fails safely to the legacy-equivalent `"none"` semantics on read
+ * (rule 34 spirit — drop corrupt rather than poison).
+ */
+export function parseProvenanceTag(
+  raw: string | undefined,
+): "verified" | "unverified" | "none" | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed === "verified" || trimmed === "unverified" || trimmed === "none") {
+    return trimmed;
+  }
+  return undefined;
+}
+
+/**
+ * Enforce the verified-requires-evidence invariant on the READ path.
+ * `parseProvenanceTag` and `parseProvenanceSources` are independent (they
+ * parse separate frontmatter lines), so a hand-edited or imported memory may
+ * carry `provenance: verified` with no surviving `sources` — a corrupt line,
+ * an empty array, or all-invalid entries. Downgrade such a tag to `none` so
+ * the in-memory object never exposes an ungrounded "verified" fact
+ * (review round 5, cursor thread KQN — read-path parity with the write-path
+ * downgrade in `serializeProvenanceFields`). `none`/`undefined` tags pass
+ * through unchanged.
+ */
+export function reconcileProvenanceRead(
+  tag: "verified" | "unverified" | "none" | undefined,
+  sources: ProvenanceSource[] | undefined,
+): "verified" | "unverified" | "none" | undefined {
+  if ((tag === "verified" || tag === "unverified") && (!sources || sources.length === 0)) {
+    return "none";
+  }
+  return tag;
+}
+
+/**
+ * Strict ISO-8601 timestamp check (review round 6, codex thread OXPAp).
+ * `Date.parse` accepts non-ISO strings (bare years like `"123"`) and
+ * silently normalizes calendar overflow (`2026-02-30` -> March 2, hour 25
+ * -> next day), so malformed provenance survives as if valid. Require the
+ * full `YYYY-MM-DDTHH:MM:SS[.fff](Z|±HH:MM)` shape and reject overflow via a
+ * `Date.UTC` round-trip component check — the offset does not affect whether
+ * a wall-clock field overflows, so this is correct for any timezone suffix.
+ */
+function isStrictIsoTimestamp(s: string): boolean {
+  const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.exec(s);
+  if (!m) return false;
+  const y = Number(m[1]), mo = Number(m[2]), da = Number(m[3]);
+  const h = Number(m[4]), mi = Number(m[5]), se = Number(m[6]);
+  // Date.UTC normalizes overflow (Feb 30 -> Mar 2); a component round-trip
+  // catches what Date.parse silently accepts.
+  const d = new Date(Date.UTC(y, mo - 1, da, h, mi, se));
+  // The component round-trip validates wall-clock overflow (Feb 30 -> Mar 2);
+  // Date.parse additionally rejects impossible timezone offsets such as
+  // +99:99, which the regex accepts but the runtime treats as NaN
+  // (codex thread OXQ0e).
+  return (
+    !Number.isNaN(Date.parse(s)) &&
+    d.getUTCFullYear() === y &&
+    d.getUTCMonth() === mo - 1 &&
+    d.getUTCDate() === da &&
+    d.getUTCHours() === h &&
+    d.getUTCMinutes() === mi &&
+    d.getUTCSeconds() === se
+  );
+}
+
+/**
+ * Zod schema for a single `ProvenanceSource` entry (issue #1575).  Parsed
+ * JSON from frontmatter is external data, so each entry is validated here
+ * rather than trusted via a cast (rule: no inline-cast-access on parsed
+ * blobs).  `safeParse` lets us drop corrupt entries individually instead of
+ * failing the whole field.
+ */
+const ProvenanceSourceSchema = z
+  .object({
+    sessionKey: z.string().min(1),
+    observedAt: z
+      .string()
+      .min(1)
+      .refine(isStrictIsoTimestamp, "must be a valid ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], no calendar overflow)"),
+    quote: z.string().min(1),
+    turnId: z.string().min(1).optional(),
+    charStart: z.number().finite().nonnegative().int().optional(),
+    charEnd: z.number().finite().nonnegative().int().optional(),
+  })
+  .refine(
+    (src) => src.charStart === undefined || src.charEnd === undefined || src.charEnd >= src.charStart,
+    { message: "charEnd must be >= charStart (half-open interval, rule 35)" },
+  );
+
+/**
+ * Parse the `sources` array (issue #1575) from its single-line JSON form.
+ * Mirrors `parseStructuredAttributes` (JSON.parse) but validates each entry
+ * against `ProvenanceSourceSchema` and DROPS corrupt ones rather than
+ * poisoning downstream readers — the same "drop corrupt rather than poison"
+ * contract as `parseMemoryWorthCounterField`.  If no entry survives, the
+ * whole field is `undefined` (legacy-equivalent).
+ */
+export function parseProvenanceSources(raw: string | undefined): ProvenanceSource[] | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(parsed)) return undefined;
+  const sources: ProvenanceSource[] = [];
+  for (const entry of parsed) {
+    const result = ProvenanceSourceSchema.safeParse(entry);
+    if (result.success) sources.push(result.data);
+  }
+  return sources.length > 0 ? sources : undefined;
+}
+
+/**
+ * Parse the `provenance` config block (issue #1575 PR 1).  Validates the
+ * shape before applying defaults — a shorthand like `provenance: false` must
+ * reject loudly rather than normalize to `{}` and silently enable the feature
+ * (rule 51).  Booleans coerce via `coerceBool` (rule 36); numeric cap clamps
+ * at 1 (rule 28).  `REMNIC_PROVENANCE_ENABLED` / `ENGRAM_PROVENANCE_ENABLED`
+ * are honored only when the `enabled` key is omitted (explicit config wins).
+ *
+ * Schema-default note (review rounds 1–3, settled): `provenance.enabled` has
+ * NO `"default"` in any plugin.json schema. OpenClaw's loader runs
+ * `applyDefaults: true` before exposing `api.pluginConfig` (src/index.ts:1345,
+ * PR #1593 round 8), so a schema default would be materialized into the
+ * merged config and mask the `REMNIC_`/`ENGRAM_` env override. The code-level
+ * default-on here (`return true` when `enabled` is omitted) supplies the
+ * default-on behavior without that materialization. This matches the
+ * emitLegacyTools/namespaceCatalogEnabled precedent, which omits the env
+ * override only after a raw-vs-effective split — overkill for a single
+ * boolean, so this field uses the simpler omit-the-default approach.
+ */
+export function parseProvenanceConfig(raw: unknown): ProvenanceConfig {
+  if (
+    raw !== undefined &&
+    (raw === null || typeof raw !== "object" || Array.isArray(raw))
+  ) {
+    throw new Error(
+      `provenance must be an object (got ${JSON.stringify(raw)}). Use provenance: { enabled: false } to opt out; omit the key to use the default-on behavior (issue #1575).`,
+    );
+  }
+  const rawProvenance =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  return {
+    enabled: (() => {
+      if (rawProvenance.enabled === undefined) {
+        const envEnabled =
+          readEnvVar("REMNIC_PROVENANCE_ENABLED") ?? readEnvVar("ENGRAM_PROVENANCE_ENABLED");
+        if (envEnabled !== undefined) {
+          const coerced = coerceBool(envEnabled);
+          if (coerced === undefined) {
+            throw new Error(
+              `REMNIC_PROVENANCE_ENABLED must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(envEnabled)}`,
+            );
+          }
+          return coerced;
+        }
+        return true;
+      }
+      const coerced = coerceBool(rawProvenance.enabled);
+      if (coerced === undefined) {
+        throw new Error(
+          `provenance.enabled must be a boolean or one of "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off" (got ${JSON.stringify(rawProvenance.enabled)}). Omit the key to use the default-on behavior (issue #1575).`,
+        );
+      }
+      return coerced;
+    })(),
+    maxQuoteChars: (() => {
+      if (rawProvenance.maxQuoteChars === undefined) return 300;
+      const rawCap = coerceNumber(rawProvenance.maxQuoteChars);
+      // Reject present-but-invalid rather than silently widening the cap
+      // (AGENTS.md input-validation rule — a typo should not persist more
+      // text than the operator configured).
+      if (rawCap === undefined || !Number.isFinite(rawCap) || rawCap < 1 || !Number.isInteger(rawCap)) {
+        throw new Error(
+          `provenance.maxQuoteChars must be a positive integer >= 1 (got ${JSON.stringify(rawProvenance.maxQuoteChars)}).`,
+        );
+      }
+      return rawCap;
+    })(),
+    requireSpans: (() => {
+      if (rawProvenance.requireSpans === undefined) return false;
+      const coerced = coerceBool(rawProvenance.requireSpans);
+      if (coerced === undefined) {
+        throw new Error(
+          `provenance.requireSpans must be a boolean or one of "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off" (got ${JSON.stringify(rawProvenance.requireSpans)}).`,
+        );
+      }
+      return coerced;
+    })(),
+  };
+}

package/src/storage.ts

@@ -9,6 +9,7 @@ import { assertPathInsideRoot } from "./utils/path-containment.js";
 import { getCachedEntities, invalidateAllForDir, setCachedEntities } from "./memory-cache.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
+import { serializeProvenanceFields, parseProvenanceSources, parseProvenanceTag, reconcileProvenanceRead } from "./provenance.js";
 import { createVersion as createPageVersion, type VersioningConfig, type VersionTrigger } from "./page-versioning.js";
 import { isValidTranscriptDate, WEARABLES_DIR_NAME } from "./wearables/day-store.js";
 import {
@@ -440,6 +441,7 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
   if (fm.last_reinforced_at) {
     lines.push(`last_reinforced_at: ${fm.last_reinforced_at}`);
   }
+  serializeProvenanceFields(fm, lines);
   lines.push("---");
   return lines.join("\n");
 }
@@ -843,13 +845,11 @@ function parseFrontmatter(
       // PR; no code produces these fields yet.
       derived_from,
       derived_via,
-      // Pattern-reinforcement metadata (issue #687 PR 2/4).  Parse
-      // permissively: invalid values (negative, non-integer, blank
-      // ISO-strings) are dropped to undefined so a corrupt frontmatter
-      // never poisons downstream scoring.  Validation lives on the
-      // write path in serializeFrontmatter.
+      // Pattern-reinforcement metadata (issue #687 PR 2/4) — drop corrupt values on read (rule 34).
       reinforcement_count: parseReinforcementCountField(fm.reinforcement_count),
       last_reinforced_at: fm.last_reinforced_at || undefined,
+      sources: parseProvenanceSources(fm.sources),
+      provenance: reconcileProvenanceRead(parseProvenanceTag(fm.provenance), parseProvenanceSources(fm.sources)),
     },
     content,
   };
@@ -2238,24 +2238,12 @@ export class StorageManager {
 
   // Cache for readAllColdMemories() — keyed by cold root directory path.
   // Prevents an uncached full-tree directory scan on every structured-attribute
-  // write (Finding UOGi, PR #402 round-6).  The cache is only invalidated when
-  // cold-tier content actually changes (via invalidateColdMemoriesCache), NOT
-  // on every hot-tier write.  It also expires after COLD_SCAN_CACHE_TTL_MS as
-  // a safety net.
-  //
-  // Finding UvUy (PR #402 round-11): cache entries now carry a `coldVersion`
-  // sentinel that is bumped (via a file-size counter in state/cold-write.log)
-  // on every write that modifies cold-tier content.  Before serving a cached
-  // result, readAllColdMemories() reads the sentinel from disk and compares.
-  // If they differ the entry is dropped and the cold tree is re-scanned.  This
-  // makes the cache correct across process boundaries (gateway + CLI): a second
-  // process that writes a new cold memory bumps the sentinel on disk, so the
-  // first process's next readAllColdMemories() sees the change within one call
-  // (rather than waiting up to 30s for TTL expiry).
-  //
-  // After Finding UTsP broadened readAllColdMemories to scan the entire cold/
-  // subtree (not just facts/+corrections/), amortizing this I/O across
-  // back-to-back writes in the same burst is even more important.
+  // write (Finding UOGi, PR #402 round-6). Invalidated when cold-tier content
+  // changes (via invalidateColdMemoriesCache) and expires after COLD_SCAN_CACHE_TTL_MS.
+  // Entries carry a `coldVersion` sentinel (Finding UvUy, PR #402 round-11) bumped
+  // on every cold-tier write, making the cache correct across process boundaries
+  // (gateway + CLI). After Finding UTsP broadened the scan to the entire cold/
+  // subtree, amortizing across back-to-back writes is even more important.
   private static readonly COLD_SCAN_CACHE_TTL_MS = 30_000; // 30 seconds
   private static readonly coldMemoriesCache = new Map<string, { memories: MemoryFile[]; loadedAt: number; coldVersion: number }>();
 
@@ -2289,6 +2277,11 @@ export class StorageManager {
   private offlineSyncDigestCacheWriteTimer: ReturnType<typeof setTimeout> | null = null;
   /** Optional: set by the orchestrator after construction to enable template-aware citation stripping during legacy hash rebuild. */
   citationTemplate: string = DEFAULT_CITATION_FORMAT;
+  /** Post-write catalog hook (#1522). Installed by the namespace router; fire-and-forget. */
+  onCatalogWrite?: () => void;
+  private notifyCatalogWrite(): void {
+    try { this.onCatalogWrite?.(); } catch { /* gotcha #13 */ }
+  }
 
   /** Page-versioning configuration.  Set by the orchestrator after construction. */
   private _versioningConfig: VersioningConfig | null = null;
@@ -2576,7 +2569,7 @@ export class StorageManager {
   ): Promise<void> {
     const targetPath = this.wearableTranscriptPath(sourceId, date);
     // writeMaybeEncryptedFile handles mkdir + atomic temp→rename.
-    await writeMaybeEncryptedFile(targetPath, serialized, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(targetPath, serialized);
   }
 
   /** Read a stored day transcript; null when the day has no file. */
@@ -2747,8 +2740,13 @@ export class StorageManager {
   private readStorageSecureFile(filePath: string): Promise<string> {
     return readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
   }
-  private writeStorageSecureFile(filePath: string, content: string): Promise<void> {
-    return writeMaybeEncryptedFile(filePath, content, this.resolveWriteKey(), {}, this.baseDir);
+  private writeStorageSecureFile(filePath: string, content: string | Buffer): Promise<void> {
+    return writeMaybeEncryptedFile(filePath, content, this.resolveWriteKey(), {}, this.baseDir)
+      .then(() => this.notifyCatalogWrite());
+  }
+  private writeStorageSecureFileChunks(filePath: string, chunks: AsyncIterable<Buffer>): Promise<void> {
+    return writeMaybeEncryptedFileFromChunks(filePath, chunks, this.resolveWriteKey(), {}, this.baseDir)
+      .then(() => this.notifyCatalogWrite());
   }
 
   private assertManagedStoragePath(filePath: string, method: string): string {
@@ -2929,18 +2927,18 @@ export class StorageManager {
 
   async writeOfflineSyncFile(filePath: string, content: Buffer): Promise<void> {
     const target = this.assertManagedStoragePath(filePath, "storage.writeOfflineSyncFile");
-    await writeMaybeEncryptedFile(target, content, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(target, content);
     await this.invalidateAfterOfflineSyncMutation(target);
   }
 
   async writeOfflineSyncStagingFile(filePath: string, content: Buffer): Promise<void> {
     const target = this.assertManagedStoragePath(filePath, "storage.writeOfflineSyncStagingFile");
-    await writeMaybeEncryptedFile(target, content, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(target, content);
   }
 
   async writeOfflineSyncFileChunks(filePath: string, chunks: AsyncIterable<Buffer>): Promise<void> {
     const target = this.assertManagedStoragePath(filePath, "storage.writeOfflineSyncFileChunks");
-    await writeMaybeEncryptedFileFromChunks(target, chunks, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFileChunks(target, chunks);
     await this.invalidateAfterOfflineSyncMutation(target);
   }
 
@@ -3005,12 +3003,14 @@ export class StorageManager {
         if (isEncryptedFile(await readFile(filePath))) {
           const existing = await this.readStorageSecureFile(filePath);
           await writeMaybeEncryptedFile(filePath, `${existing}${content}`, null, {}, this.baseDir);
+          this.notifyCatalogWrite();
           return;
         }
       } catch (err) {
         if (!isErrnoCode(err, "ENOENT")) throw err;
       }
       await appendFile(filePath, content, "utf-8");
+      this.notifyCatalogWrite();
       return;
     }
 
@@ -3021,6 +3021,7 @@ export class StorageManager {
       if (!isErrnoCode(err, "ENOENT")) throw err;
     }
     await writeMaybeEncryptedFile(filePath, `${existing}${content}`, writeKey, {}, this.baseDir);
+    this.notifyCatalogWrite();
   }
   private get stateDir(): string {
     return path.join(this.baseDir, "state");
@@ -3465,7 +3466,7 @@ export class StorageManager {
     const filePath = await this.resolveCategoryWritePath(category, id, today);
 
     await this.snapshotBeforeWrite(filePath, "write");
-    await writeMaybeEncryptedFile(filePath, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(filePath, fileContent);
     this.invalidateAllMemoriesCache();
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
       memoryId: id,
@@ -3638,7 +3639,7 @@ export class StorageManager {
       return "";
     }
     const filePath = path.join(dir, `${id}.md`);
-    await writeMaybeEncryptedFile(filePath, `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`);
     const actor =
       typeof options.actor === "string" && options.actor.length > 0
         ? options.actor
@@ -3876,7 +3877,7 @@ export class StorageManager {
   async writeProfile(content: string): Promise<void> {
     await this.ensureDirectories();
     await this.snapshotBeforeWrite(this.profilePath, "consolidation");
-    await writeMaybeEncryptedFile(this.profilePath, content, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(this.profilePath, content);
     log.debug("updated profile.md");
   }
 
@@ -4601,10 +4602,9 @@ export class StorageManager {
 
   private async writeMemoryFileAtomic(targetPath: string, memory: MemoryFile): Promise<void> {
     const fileContent = `${serializeFrontmatter(memory.frontmatter)}\n\n${memory.content}\n`;
-    // writeMaybeEncryptedFile handles atomic temp→rename internally and
-    // calls mkdir on the parent directory — no need to duplicate here.
     await writeMaybeEncryptedFile(targetPath, fileContent, this.resolveWriteKey(), {}, this.baseDir);
     this.invalidateAllMemoriesCache();
+    this.notifyCatalogWrite();
   }
 
   async moveMemoryToPath(memory: MemoryFile, targetPath: string): Promise<void> {
@@ -4694,7 +4694,7 @@ export class StorageManager {
       const destPath = path.join(destDir, path.basename(memory.path));
 
       // Write to archive location first (encrypted if applicable), then remove original.
-      await writeMaybeEncryptedFile(destPath, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+      await this.writeStorageSecureFile(destPath, fileContent);
       await unlink(memory.path);
       this.invalidateAllMemoriesCache();
       await this.appendGeneratedMemoryLifecycleEventFailOpen(
@@ -4851,7 +4851,7 @@ export class StorageManager {
       log.warn(`updated memory content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
     }
     const fileContent = `${serializeFrontmatter(updated)}\n\n${sanitized.text}\n`;
-    await writeMaybeEncryptedFile(memory.path, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(memory.path, fileContent);
     this.invalidateAllMemoriesCache();
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.updateMemory", {
       memoryId: id,
@@ -4886,7 +4886,7 @@ export class StorageManager {
     const afterStatus = updated.status ?? "active";
 
     const fileContent = `${serializeFrontmatter(updated)}\n\n${memory.content}\n`;
-    await writeMaybeEncryptedFile(memory.path, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+    await this.writeStorageSecureFile(memory.path, fileContent);
     this.invalidateAllMemoriesCache();
     // If the target file lives in cold/, bump the cold-version sentinel so
     // other processes detect the change on their next readAllColdMemories()
@@ -5826,7 +5826,7 @@ export class StorageManager {
     const content = `---\n${Object.entries(frontmatter).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join("\n")}\n---\n\n${question}\n\n**Context:** ${context}\n`;
 
     const filePath = path.join(this.questionsDir, `${id}.md`);
-    await writeFile(filePath, content, "utf-8");
+    await this.writeStorageSecureFile(filePath, content);
 
     log.debug(`wrote question ${id} to ${filePath}`);
     this.invalidateQuestionsCache();
@@ -5942,13 +5942,13 @@ export class StorageManager {
     const q = questions.find((q) => q.id === id);
     if (!q) return false;
 
-    let raw = await readFile(q.filePath, "utf-8");
+    let raw = await this.readStorageSecureFile(q.filePath);
     raw = raw.replace(/resolved: false/, "resolved: true");
     raw = raw.replace(
       /---\n\n/,
       `resolvedAt: "${new Date().toISOString()}"\n---\n\n`,
     );
-    await writeFile(q.filePath, raw, "utf-8");
+    await this.writeStorageSecureFile(q.filePath, raw);
     log.debug(`resolved question ${id}`);
     return true;
   }
@@ -7080,7 +7080,7 @@ export class StorageManager {
     const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${oldMemory.content}\n`;
 
     try {
-      await writeMaybeEncryptedFile(oldMemory.path, fileContent, this.resolveWriteKey(), {}, this.baseDir);
+      await this.writeStorageSecureFile(oldMemory.path, fileContent);
       await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
         memoryId: oldMemoryId,
         eventType: "superseded",

package/src/types.ts

@@ -387,6 +387,29 @@ export interface ProceduralConfig {
   recallMaxProcedures: number;
 }
 
+/**
+ * Claim-level provenance spans (issue #1575). Controls whether extracted
+ * facts carry verbatim source-utterance excerpts and the strength tag that
+ * downstream features (faithfulness gate #1576, correction UX #1580/#1583,
+ * tombstone matching #1579, TrustScore #1577) consume.
+ *
+ * PR 1 parses the block + schema only; the extraction prompt and validator
+ * land in PR 2. When `enabled` is false, extraction prompt/output are
+ * byte-identical to pre-feature behavior (rule 39).
+ */
+export interface ProvenanceConfig {
+  /** Emit provenance spans on new extractions. Default true. */
+  enabled: boolean;
+  /** Maximum characters stored per quote; longer quotes truncate at a word boundary. Default 300. */
+  maxQuoteChars: number;
+  /**
+   * When true, facts whose quote cannot be located are routed to
+   * `pending_review` instead of `active`. Stays false until #1576 lands and
+   * the bench shows the gate is safe (rule 48).
+   */
+  requireSpans: boolean;
+}
+
 /**
  * Coding-agent mode config (issue #569).
  *
@@ -951,6 +974,12 @@ export interface PluginConfig {
    */
   dreamsPhases: DreamsPhasesConfig;
   procedural: ProceduralConfig;
+  /**
+   * Claim-level provenance spans (issue #1575). Parsed from the
+   * `provenance` config block; see `ProvenanceConfig` for the documented
+   * defaults. PR 1 parses + persists only; extraction wiring lands in PR 2.
+   */
+  provenance: ProvenanceConfig;
   /**
    * Wearable transcript ingestion (Limitless / Bee / Omi connectors).
    * Disabled by default; see docs/wearables.md.
@@ -2514,6 +2543,28 @@ export interface MemoryFrontmatter {
    * is absent.
    */
   last_reinforced_at?: string;
+  // Claim-level provenance spans (issue #1575).
+  //
+  // Verbatim source-utterance excerpts that ground each extracted fact, plus
+  // a coarse `provenance` tag recording whether the span was located in the
+  // buffered turn text. Absent on legacy memories written before #1575;
+  // readers MUST treat both `undefined` (legacy) and `provenance: "none"`
+  // uniformly — never crash, never drop the fact (rule 34 spirit).
+  //
+  // `charStart` / `charEnd` are best-effort debugging aids — consumers MUST
+  // tolerate their absence (turn text is not persisted forever). The span
+  // interval is half-open [charStart, charEnd) per rule 35.
+  //
+  // PR 1 wires only the schema + storage round-trip — no extraction prompt,
+  // validator, or read surfaces yet.
+  /** Literal source-utterance excerpts backing this fact (issue #1575). */
+  sources?: ProvenanceSource[];
+  /**
+   * Coarse provenance strength: `"verified"` (span located in source text),
+   * `"unverified"` (span present but not locatable), or `"none"` (no span
+   * recorded). Readers treat absent as `"none"` for legacy memories.
+   */
+  provenance?: "verified" | "unverified" | "none";
 }
 
 /** Memory link relationship types */
@@ -2527,6 +2578,31 @@ export interface MemoryLink {
   reason?: string;
 }
 
+/**
+ * A verbatim source-utterance excerpt that grounds an extracted fact
+ * (issue #1575). Emitted by the PR 2 extraction validator; round-tripped
+ * through storage in PR 1.
+ *
+ * `quote` is the only strictly-required field — without it the entry is
+ * meaningless and is dropped on read. `charStart` / `charEnd` are
+ * best-effort offsets within the buffered turn text at write time and
+ * form a half-open interval [charStart, charEnd) (rule 35).
+ */
+export interface ProvenanceSource {
+  /** Session key of the source turn (e.g. `project/<name>/<ts>`). */
+  sessionKey: string;
+  /** Host-supplied turn identifier, when one was provided. */
+  turnId?: string;
+  /** ISO 8601 timestamp of the source turn. */
+  observedAt: string;
+  /** Verbatim utterance excerpt, capped at `provenance.maxQuoteChars`. */
+  quote: string;
+  /** Offset within the buffered turn text where the quote begins, when located. */
+  charStart?: number;
+  /** Half-open end offset within the buffered turn text (rule 35). */
+  charEnd?: number;
+}
+
 // Conversation Threading (Phase 3B)
 export interface ConversationThread {
   id: string;

package/dist/chunk-2ODBA7MQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/logger.ts"],"sourcesContent":["export interface LoggerBackend {\n  info(msg: string, ...args: unknown[]): void;\n  warn(msg: string, ...args: unknown[]): void;\n  error(msg: string, ...args: unknown[]): void;\n  debug?(msg: string, ...args: unknown[]): void;\n}\n\nconst NOOP_LOGGER: LoggerBackend = {\n  info() {},\n  warn() {},\n  error() {},\n  debug() {},\n};\n\nlet _backend: LoggerBackend = NOOP_LOGGER;\nlet _debug = false;\n\nconst CONSOLE_LOGGER: LoggerBackend = {\n  info: console.info.bind(console),\n  warn: console.warn.bind(console),\n  error: console.error.bind(console),\n  debug: console.debug.bind(console),\n};\n\nexport function initLogger(backend?: LoggerBackend, debug?: boolean): void {\n  _backend = backend ?? CONSOLE_LOGGER;\n  _debug = debug ?? false;\n}\n\nexport const log = {\n  info(msg: string, ...args: unknown[]): void {\n    _backend.info(`remnic: ${msg}`, ...args);\n  },\n  warn(msg: string, ...args: unknown[]): void {\n    _backend.warn(`remnic: ${msg}`, ...args);\n  },\n  error(msg: string, err?: unknown): void {\n    const detail =\n      err instanceof Error ? err.message : err ? String(err) : \"\";\n    _backend.error(\n      `remnic: ${msg}${detail ? ` — ${detail}` : \"\"}`,\n    );\n  },\n  debug(msg: string, ...args: unknown[]): void {\n    if (!_debug) return;\n    const fn = _backend.debug ?? _backend.info;\n    fn(`remnic [debug]: ${msg}`, ...args);\n  },\n};\n"],"mappings":";AAOA,IAAM,cAA6B;AAAA,EACjC,OAAO;AAAA,EAAC;AAAA,EACR,OAAO;AAAA,EAAC;AAAA,EACR,QAAQ;AAAA,EAAC;AAAA,EACT,QAAQ;AAAA,EAAC;AACX;AAEA,IAAI,WAA0B;AAC9B,IAAI,SAAS;AAEb,IAAM,iBAAgC;AAAA,EACpC,MAAM,QAAQ,KAAK,KAAK,OAAO;AAAA,EAC/B,MAAM,QAAQ,KAAK,KAAK,OAAO;AAAA,EAC/B,OAAO,QAAQ,MAAM,KAAK,OAAO;AAAA,EACjC,OAAO,QAAQ,MAAM,KAAK,OAAO;AACnC;AAEO,SAAS,WAAW,SAAyB,OAAuB;AACzE,aAAW,WAAW;AACtB,WAAS,SAAS;AACpB;AAEO,IAAM,MAAM;AAAA,EACjB,KAAK,QAAgB,MAAuB;AAC1C,aAAS,KAAK,WAAW,GAAG,IAAI,GAAG,IAAI;AAAA,EACzC;AAAA,EACA,KAAK,QAAgB,MAAuB;AAC1C,aAAS,KAAK,WAAW,GAAG,IAAI,GAAG,IAAI;AAAA,EACzC;AAAA,EACA,MAAM,KAAa,KAAqB;AACtC,UAAM,SACJ,eAAe,QAAQ,IAAI,UAAU,MAAM,OAAO,GAAG,IAAI;AAC3D,aAAS;AAAA,MACP,WAAW,GAAG,GAAG,SAAS,WAAM,MAAM,KAAK,EAAE;AAAA,IAC/C;AAAA,EACF;AAAA,EACA,MAAM,QAAgB,MAAuB;AAC3C,QAAI,CAAC,OAAQ;AACb,UAAM,KAAK,SAAS,SAAS,SAAS;AACtC,OAAG,mBAAmB,GAAG,IAAI,GAAG,IAAI;AAAA,EACtC;AACF;","names":[]}