@remnic/core 9.3.690 → 9.3.691

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