@remnic/core 9.3.704 → 9.3.706

package/src/storage-contract/versioning.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Issue #1533 — Phase A contract test: page versioning snapshots.
+ *
+ * When versioning is enabled, overwriting a FIXED-PATH file produces a numbered
+ * snapshot in the `.versions/` sidecar. Revert restores a prior version.
+ * This pins the versioning contract the consolidation/provenance paths rely on.
+ *
+ * NOTE: `writeMemory` generates a unique path per id, so the first write to a
+ * path never has pre-existing content to snapshot. The versioning integration
+ * is exercised through `writeProfile` — a fixed-path write that calls
+ * `snapshotBeforeWrite` before overwriting. The direct `createVersion`/
+ * `revertToVersion` API is tested separately.
+ */
+
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  createVersion,
+  listVersions,
+  revertToVersion,
+  getVersion,
+  type VersioningConfig,
+} from "../page-versioning.js";
+import { StorageManager } from "../storage.js";
+import { resetStaticCaches } from "./harness.js";
+
+const VERSIONING_CONFIG: VersioningConfig = {
+  enabled: true,
+  maxVersionsPerPage: 10,
+  sidecarDir: ".versions",
+};
+
+test("versioning: overwrite of a fixed-path file (writeProfile) produces a numbered snapshot", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-snapshot-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setVersioningConfig(VERSIONING_CONFIG);
+
+    const profilePath = path.join(dir, "profile.md");
+    await storage.writeProfile("first version of profile");
+
+    // Overwrite the same fixed path → snapshotBeforeWrite fires
+    await storage.writeProfile("second version of profile");
+
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.ok(
+      versions.versions.length >= 1,
+      "at least one snapshot must exist after overwriting a fixed-path file",
+    );
+    assert.equal(versions.versions[0].trigger, "consolidation");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: snapshot captures the PRE-overwrite content", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-pre-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setVersioningConfig(VERSIONING_CONFIG);
+
+    const profilePath = path.join(dir, "profile.md");
+    await storage.writeProfile("ORIGINAL PROFILE");
+    await storage.writeProfile("REPLACEMENT PROFILE");
+
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.ok(versions.versions.length >= 1);
+
+    // Read the snapshot — it must contain the ORIGINAL, not the replacement
+    const snapshot = await getVersion(profilePath, versions.versions[0].versionId, VERSIONING_CONFIG);
+    assert.ok(snapshot, "snapshot content must be readable");
+    assert.ok(
+      snapshot!.includes("ORIGINAL PROFILE"),
+      "the snapshot must contain the pre-overwrite content",
+    );
+    assert.ok(
+      !snapshot!.includes("REPLACEMENT"),
+      "the snapshot must NOT contain the replacement content",
+    );
+
+    // The live file has the replacement
+    const live = await readFile(profilePath, "utf-8");
+    assert.ok(live.includes("REPLACEMENT PROFILE"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: disabled by default — no snapshots created", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-disabled-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    // Do NOT call setVersioningConfig — default is disabled
+    await storage.writeProfile("v1");
+    await storage.writeProfile("v2");
+
+    const profilePath = path.join(dir, "profile.md");
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.equal(versions.versions.length, 0, "no snapshots when versioning was disabled at write time");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: createVersion → revertToVersion round-trip restores content", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-revert-"));
+  try {
+    const filePath = path.join(dir, "doc.md");
+    await writeFile(filePath, "alpha", "utf-8");
+
+    await createVersion(filePath, "alpha", "manual", VERSIONING_CONFIG);
+    await writeFile(filePath, "beta", "utf-8");
+    await createVersion(filePath, "beta", "manual", VERSIONING_CONFIG);
+
+    const versions = await listVersions(filePath, VERSIONING_CONFIG);
+    assert.ok(versions.versions.length >= 2);
+
+    const firstVersionId = versions.versions[0].versionId;
+    await revertToVersion(filePath, firstVersionId, VERSIONING_CONFIG);
+
+    const restored = await readFile(filePath, "utf-8");
+    assert.equal(restored, "alpha", "revert must restore the version-1 content");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/storage.ts

@@ -3580,6 +3580,7 @@ export class StorageManager {
       // or assumed from the ingestion anchor.  Both validate on serialize.
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
+      invalidAt?: string;
       structuredAttributes?: Record<string, string>;
       /**
        * When provided, this string is used as the source for the fact-content
@@ -3665,6 +3666,7 @@ export class StorageManager {
       valid_at: validAt,
       observedAt,
       eventTimeSource: options.eventTimeSource,
+      invalid_at: normalizeMemoryWriteTimestamp("invalidAt", options.invalidAt),
       structuredAttributes: options.structuredAttributes,
     };
     if (options.status !== undefined) {
@@ -4504,12 +4506,10 @@ export class StorageManager {
     // is disabled, missing, or unhealthy. RECALL_FALLBACK_DIRS is the single
     // source of truth derived from ALL_CATEGORY_DIRS (shared with
     // ensureDirectories() and the write routing in utils/category-dir.ts).
-    //
     // These paths resolve identically to the legacy this.factsDir /
     // this.correctionsDir / this.proceduresDir / this.reasoningTracesDir
     // getters (all `path.join(this.baseDir, <dir>)`), so the scan stays
     // namespace-aware: this.baseDir is per-namespace, set by the storage router.
-    //
     // Deliberately EXCLUDED (issue #1497 + PR #1503 review): the non-category
     // content dirs that ensureDirectories() also creates — entities/, state/,
     // artifacts/, identity/, config/ — plus the root profile.md, AND the
@@ -7359,6 +7359,12 @@ export class StorageManager {
       sources?: ProvenanceSource[];
       /** Coarse provenance tag (issue #1575 PR 2), propagated from the parent. */
       provenance?: "verified" | "unverified" | "none";
+      // Issue #1578 — bi-temporal bounds + ingestion provenance propagated from
+      // the parent fact so an independently-surfaced chunk expires at the same
+      // invalid_at window and carries the same observed-at anchor.
+      invalidAt?: string;
+      observedAt?: string;
+      eventTimeSource?: "extracted" | "assumed";
     } = {},
   ): Promise<string> {
     await this.ensureDirectories();
@@ -7368,6 +7374,8 @@ export class StorageManager {
     const conf = options.confidence ?? 0.8;
     const tier = confidenceTier(conf);
     const validAt = normalizeMemoryWriteTimestamp("validAt", options.validAt);
+    const chunkInvalidAt = normalizeMemoryWriteTimestamp("invalidAt", options.invalidAt);
+    const chunkObservedAt = normalizeMemoryWriteTimestamp("observedAt", options.observedAt);
 
     const fm: MemoryFrontmatter = {
       id,
@@ -7388,6 +7396,9 @@ export class StorageManager {
       intentEntityTypes: options.intentEntityTypes,
       memoryKind: options.memoryKind,
       valid_at: validAt,
+      invalid_at: chunkInvalidAt,
+      observedAt: chunkObservedAt,
+      eventTimeSource: options.eventTimeSource,
       ...(options.status ? { status: options.status } : {}),
       ...(options.faithfulness ? { faithfulness: options.faithfulness } : {}),
       ...(options.sources ? { sources: options.sources } : {}),

package/src/temporal-validity.test.ts

@@ -410,6 +410,39 @@ test("isValidAsOf: half-open interval [valid_at, invalid_at)", () => {
   assert.equal(isValidAsOf(fm, Date.parse("2026-01-01T00:00:00.000Z")), false);
 });
 
+test("isValidAsOf: extracted end-only bound is open-start (-inf, invalid_at] (#1578 r3)", () => {
+  // An extracted fact like "we used MongoDB until June 2025" resolves to
+  // validUntil only (no validFrom); valid_at is absent, eventTimeSource is
+  // "extracted". The interval must be open-start so historical as_of queries
+  // before ingestion still see it, rather than defaulting valid_at to created.
+  const fm = {
+    invalid_at: "2025-07-01T00:00:00.000Z",
+    created: "2025-08-15T00:00:00.000Z",
+    eventTimeSource: "extracted" as const,
+  };
+  // Well before ingestion/created — still authoritative (open start).
+  assert.equal(isValidAsOf(fm, Date.parse("2024-01-01T00:00:00.000Z")), true);
+  // Mid-window — authoritative.
+  assert.equal(isValidAsOf(fm, Date.parse("2025-06-15T00:00:00.000Z")), true);
+  // Exactly at invalid_at — NOT authoritative (exclusive upper bound).
+  assert.equal(isValidAsOf(fm, Date.parse("2025-07-01T00:00:00.000Z")), false);
+  // After invalid_at — not authoritative.
+  assert.equal(isValidAsOf(fm, Date.parse("2026-01-01T00:00:00.000Z")), false);
+});
+
+test("isValidAsOf: legacy memory without eventTimeSource keeps created fallback (#1578 r3)", () => {
+  // A legacy memory with invalid_at but no eventTimeSource must NOT become
+  // open-start — it keeps the pre-#1578 [created, invalid_at) behaviour so
+  // supersession/backfill semantics are unchanged.
+  const fm = {
+    invalid_at: "2025-12-31T00:00:00.000Z",
+    created: "2025-06-01T00:00:00.000Z",
+  };
+  // Before created — not authoritative (legacy behaviour preserved).
+  assert.equal(isValidAsOf(fm, Date.parse("2025-05-01T00:00:00.000Z")), false);
+  assert.equal(isValidAsOf(fm, Date.parse("2025-09-01T00:00:00.000Z")), true);
+});
+
 test("isValidAsOf: timezone-suffixed ISO strings compare via Date.parse, not lexicographic", () => {
   // Two strings that order differently lexicographically vs as Dates.
   // 2025-01-01T00:00:00+02:00 == 2024-12-31T22:00:00Z

package/src/temporal-validity.ts

@@ -82,11 +82,34 @@ export function effectiveInvalidAt(
 export function isValidAsOf(
   fm: Pick<
     MemoryFrontmatter,
-    "valid_at" | "invalid_at" | "created" | "supersededAt" | "status"
+    | "valid_at"
+    | "invalid_at"
+    | "created"
+    | "supersededAt"
+    | "status"
+    | "eventTimeSource"
   >,
   asOfMs: number,
 ): boolean {
   if (!Number.isFinite(asOfMs)) return true;
+  // Open-start bi-temporal interval (#1578 r3): an extracted end-only bound
+  // (eventTimeSource "extracted", no valid_at, has invalid_at) is true from
+  // the indefinite past. Without this, effectiveValidAt falls back to
+  // `created` and a historical as_of before ingestion hides a fact that was
+  // actually true up until invalid_at (chatgpt-codex thread on
+  // orchestrator.ts:15533). Gated on eventTimeSource so legacy memories
+  // (no bi-temporal provenance) keep the created-anchor fallback.
+  const explicitValidAt = fm.valid_at?.trim();
+  if (
+    (!explicitValidAt || explicitValidAt.length === 0) &&
+    fm.eventTimeSource === "extracted"
+  ) {
+    const invalidAt = effectiveInvalidAt(fm);
+    if (invalidAt !== undefined) {
+      const invalidAtMs = Date.parse(invalidAt);
+      if (Number.isFinite(invalidAtMs)) return invalidAtMs > asOfMs;
+    }
+  }
   const validAtMs = Date.parse(effectiveValidAt(fm));
   if (!Number.isFinite(validAtMs)) return false;
   if (validAtMs > asOfMs) return false;

package/src/types.ts

@@ -810,8 +810,9 @@ export interface PluginConfig {
    * 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.
+   * extraction prompt emits an optional per-fact `eventTime` expression
+   * and `resolveFactEventTime` resolves it against the source turn
+   * timestamp at write time (#1578 PR2).
    */
   temporalBiTemporal: boolean;
   /**
@@ -2893,6 +2894,15 @@ export interface ExtractedFact {
    * walked through. Persisted under reasoning-traces/.
    */
   reasoningTrace?: ExtractedReasoningTrace;
+  /**
+   * Optional event-time expression for bi-temporal validity (#1578 PR2).
+   * Verbatim temporal anchor extracted from the conversation ("2025-03-01",
+   * "last March", "since 2024", "until 2025-06-01"). Resolved against the
+   * source turn timestamp at write time by `resolveFactEventTime` — never
+   * re-resolved at read. Absent when the fact carries no temporal anchor or
+   * when `temporal.biTemporal` is off.
+   */
+  eventTime?: string;
 }
 
 export interface ExtractedReasoningTraceStep {