@remnic/core 9.3.689 → 9.3.691

package/src/storage.ts

@@ -321,6 +321,22 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
   // memories round-trip unchanged; readers default `valid_at` to `created`.
   if (fm.valid_at) lines.push(`validAt: ${fm.valid_at}`);
   if (fm.invalid_at) lines.push(`invalidAt: ${fm.invalid_at}`);
+  // Issue #1578 — bi-temporal ingestion provenance.  Validate on write so a
+  // corrupt `observedAt` (non-ISO / overflowed) cannot leak onto disk; reads
+  // are permissive, mirroring the `valid_at` precedent.  `eventTimeSource` is
+  // a closed enum — reject anything outside it rather than persisting garbage.
+  if (fm.observedAt) {
+    const validated = normalizeMemoryWriteTimestamp("observedAt", fm.observedAt);
+    if (validated) lines.push(`observedAt: ${validated}`);
+  }
+  if (fm.eventTimeSource) {
+    if (fm.eventTimeSource !== "extracted" && fm.eventTimeSource !== "assumed") {
+      throw new Error(
+        `serializeFrontmatter: invalid eventTimeSource ${JSON.stringify(fm.eventTimeSource)} — expected "extracted" | "assumed"`,
+      );
+    }
+    lines.push(`eventTimeSource: ${fm.eventTimeSource}`);
+  }
   if (fm.forgottenAt) lines.push(`forgottenAt: ${fm.forgottenAt}`);
   if (fm.forgottenReason) lines.push(`forgottenReason: ${JSON.stringify(fm.forgottenReason)}`);
   // Lifecycle policy fields
@@ -808,6 +824,12 @@ function parseFrontmatter(
       // Issue #680 — explicit fact lifecycle round-trip.
       valid_at: fm.validAt || undefined,
       invalid_at: fm.invalidAt || undefined,
+      // Issue #1578 — bi-temporal ingestion provenance round-trip.
+      observedAt: fm.observedAt || undefined,
+      eventTimeSource:
+        fm.eventTimeSource === "extracted" || fm.eventTimeSource === "assumed"
+          ? fm.eventTimeSource
+          : undefined,
       forgottenAt: fm.forgottenAt || undefined,
       forgottenReason: parseFrontmatterStringValue(fm.forgottenReason),
       lifecycleState: (fm.lifecycleState as LifecycleState) || undefined,
@@ -1175,26 +1197,12 @@ export class ContentHashIndex {
  *   normalizeAttributePairs({ foo: "bar", BAZ: "qux" })
  *   // → "baz: qux; foo: bar"
  */
-/**
- * Remove the "[Attributes: ...]" suffix `writeMemory` appends to the
- * stored body when structuredAttributes are present, yielding the raw
- * fact text for content comparison. Inverse companion of
- * `normalizeAttributePairs` enrichment. String operations, not regex —
- * CodeQL js/polynomial-redos on a suffix-anchored pattern over
- * library-supplied content.
- */
-export function stripAttributesSuffix(content: string): string {
-  const trimmed = content.trimEnd();
-  if (!trimmed.endsWith("]")) return content.trim();
-  const marker = "\n[Attributes: ";
-  const markerIndex = trimmed.lastIndexOf(marker);
-  if (markerIndex === -1) return content.trim();
-  // The block must be the FINAL line and contain no "]" before the
-  // closing bracket (mirrors the shape normalizeAttributePairs emits).
-  const inner = trimmed.slice(markerIndex + marker.length, -1);
-  if (inner.includes("]") || inner.includes("\n")) return content.trim();
-  return trimmed.slice(0, markerIndex).trim();
-}
+// `stripAttributesSuffix` now lives in ./structured-attributes.ts (shared with
+// the coding surfaces + wearable service). Imported here so internal callers
+// (snapshotBeforeWrite, snapshotForProvenance) resolve, and re-exported to
+// keep the public storage API stable for existing callers (wearables, dist).
+import { stripAttributesSuffix } from "./structured-attributes.js";
+export { stripAttributesSuffix };
 
 export function normalizeAttributePairs(pairs: Record<string, string>): string {
   return Object.entries(pairs)
@@ -3347,6 +3355,12 @@ export class StorageManager {
       memoryKind?: MemoryFrontmatter["memoryKind"];
       expiresAt?: string;
       validAt?: string;
+      // Issue #1578 — bi-temporal ingestion provenance.  `observedAt` is the
+      // ingestion time (when Remnic learned the fact); `eventTimeSource`
+      // records whether `validAt` was resolved from an extracted expression
+      // or assumed from the ingestion anchor.  Both validate on serialize.
+      observedAt?: string;
+      eventTimeSource?: "extracted" | "assumed";
       structuredAttributes?: Record<string, string>;
       /**
        * When provided, this string is used as the source for the fact-content
@@ -3379,6 +3393,10 @@ export class StorageManager {
     const conf = options.confidence ?? 0.8;
     const tier = confidenceTier(conf);
     const validAt = normalizeMemoryWriteTimestamp("validAt", options.validAt);
+    const observedAt = normalizeMemoryWriteTimestamp(
+      "observedAt",
+      options.observedAt,
+    );
 
     // Auto-set TTL for speculative memories
     let expiresAt: string | undefined;
@@ -3412,6 +3430,8 @@ export class StorageManager {
       sourceTurnId: options.sourceTurnId,
       memoryKind: options.memoryKind,
       valid_at: validAt,
+      observedAt,
+      eventTimeSource: options.eventTimeSource,
       structuredAttributes: options.structuredAttributes,
     };
     if (options.status !== undefined) {

package/src/structured-attributes.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared helpers for the `\n[Attributes: …]` enrichment suffix that
+ * `writeMemory` appends to a stored body when `structuredAttributes` are
+ * present.
+ *
+ * Extracted here (out of `storage.ts`) so every reader — the storage
+ * manager, the wearable service, and the coding surfaces — strips the suffix
+ * with ONE definition. Previously `coding/architecture-surfaces.ts` carried a
+ * weaker local copy that only checked the trailing `]`, which could truncate
+ * card markdown that legitimately ends in a `[Attributes: …]` line (cursor
+ * review: duplicate attribute suffix stripper).
+ *
+ * String operations, not regex — CodeQL `js/polynomial-redos` flags
+ * suffix-anchored patterns over library-supplied content.
+ */
+
+/**
+ * Remove the `[Attributes: …]` suffix `writeMemory` appends to the stored
+ * body when structuredAttributes are present, yielding the raw fact/card text
+ * for content comparison or client display. Inverse companion of
+ * `normalizeAttributePairs` enrichment in `storage.ts`.
+ *
+ * Returns the stripped (trimmed) body when the marker opens the final
+ * non-empty line and its inner payload contains no premature `]` or newline
+ * (mirrors the exact shape `normalizeAttributePairs` emits). Otherwise
+ * returns the trimmed input unchanged — never truncates legitimate content.
+ */
+export function stripAttributesSuffix(content: string): string {
+  const trimmed = content.trimEnd();
+  if (!trimmed.endsWith("]")) return content.trim();
+  const marker = "\n[Attributes: ";
+  const markerIndex = trimmed.lastIndexOf(marker);
+  if (markerIndex === -1) return content.trim();
+  // The block must be the FINAL line and contain no "]" before the
+  // closing bracket (mirrors the shape normalizeAttributePairs emits).
+  const inner = trimmed.slice(markerIndex + marker.length, -1);
+  if (inner.includes("]") || inner.includes("\n")) return content.trim();
+  return trimmed.slice(0, markerIndex).trim();
+}

package/src/temporal-validity.ts

@@ -101,6 +101,40 @@ export function isValidAsOf(
   return invalidAtMs > asOfMs;
 }
 
+/**
+ * Bi-temporal injection filter (issue #1578).
+ *
+ * Returns `true` when the fact's event-time interval has already ended before
+ * `nowMs` — i.e. it is no longer *true in the world* and should leave the
+ * default injection candidate set (it remains findable by explicit search
+ * and `as_of` queries, mirroring the lifecycle-filter escape-hatch principle
+ * in AGENTS.md §16).  Gated by `temporalBiTemporal`; the escape hatch
+ * `temporalExpiredInInjection` re-admits expired facts when a deployment
+ * prefers the older always-inject behavior.
+ *
+ * Semantics: a fact is expired-now when `invalid_at` is present and
+ * `invalid_at <= nowMs` (the exclusive upper bound has passed).  Absent
+ * `invalid_at` means "still valid" — never expired.  This is the
+ * status-orthogonal complement of `isValidAsOf` for the wall-clock instant:
+ * an `active` memory can be validity-expired, and a `superseded` one can
+ * still be validity-valid within its historical window (issue pitfall: the
+ * filter is status-orthogonal).
+ */
+export function isValidityExpiredNow(
+  fm: Pick<MemoryFrontmatter, "invalid_at">,
+  nowMs: number,
+): boolean {
+  if (!Number.isFinite(nowMs)) return false;
+  const invalidAt = fm.invalid_at?.trim();
+  if (!invalidAt || invalidAt.length === 0) return false;
+  const invalidAtMs = Date.parse(invalidAt);
+  // Unparseable invalid_at — conservatively keep the fact (do not filter on
+  // corrupt data; the as_of path already handles malformed bounds).
+  if (!Number.isFinite(invalidAtMs)) return false;
+  // Half-open interval end has passed: [valid_at, invalid_at) ended.
+  return invalidAtMs <= nowMs;
+}
+
 /**
  * Parse and validate an `as_of` value supplied at an input boundary
  * (CLI flag, HTTP query param, MCP field).  Returns parsed milliseconds

package/src/types.ts

@@ -788,6 +788,25 @@ export interface PluginConfig {
    * filtered out.
    */
   temporalSupersessionIncludeInRecall: boolean;
+  /**
+   * Bi-temporal validity master gate (issue #1578). When `false` (default),
+   * the recall validity-injection filter and `asOf` semantics behave
+   * byte-identically to pre-#1578.
+   *
+   * Turn on to exclude validity-expired facts from default injection
+   * candidates (they remain findable by explicit search and `as_of`
+   * queries). Storage round-trips `observedAt`/`eventTimeSource`; the
+   * extraction prompt → `resolveEventTime` write-time wiring lands in a
+   * follow-on PR, so new extractions are not yet event-time-resolved.
+   */
+  temporalBiTemporal: boolean;
+  /**
+   * Escape hatch for the bi-temporal injection filter (issue #1578). When
+   * `true`, facts whose `[valid_at, invalid_at)` interval ended before now
+   * are kept in injection candidates even with `temporalBiTemporal` on — some
+   * deployments prefer the older (always-inject) behavior. Default `false`.
+   */
+  temporalExpiredInInjection: boolean;
   // Direct-answer retrieval tier (issue #518)
   /**
    * When true, recall checks whether a single validated memory in a
@@ -2423,6 +2442,25 @@ export interface MemoryFrontmatter {
    * point in time.
    */
   invalid_at?: string;
+  /**
+   * Ingestion time (issue #1578) — when Remnic *learned* this fact.
+   * Distinct from `created` (file creation) and `valid_at` (event-time
+   * start).  Aligns with the source turn timestamp (#1575
+   * `sources[].observedAt`).  When `eventTimeSource === "assumed"`,
+   * `valid_at` is copied from this value.
+   */
+  observedAt?: string;
+  /**
+   * Provenance of the event-time interval (issue #1578).
+   *   - `"extracted"` — a per-fact `eventTime` expression was resolved
+   *     against the source turn's timestamp and produced `valid_at` /
+   *     `invalid_at`.
+   *   - `"assumed"` — no resolvable expression; `valid_at` was copied from
+   *     `observedAt` (the ingestion anchor).
+   * Absent on memories written before #1578; readers treat absent as
+   * `"assumed"` for display purposes.
+   */
+  eventTimeSource?: "extracted" | "assumed";
   /**
    * Timestamp when the operator explicitly forgot this memory
    * (issue #686 PR 4/6).  Set by `remnic forget <id>`.  Memories with