@remnic/core 9.3.726 → 9.3.728

package/src/bitemporal-dedup-backfill.test.ts

@@ -167,3 +167,297 @@ test("#1671: re-extraction with resolved invalidAt backfills an old promoted cop
     await cleanup();
   }
 });
+
+// ─── #1707 widenings (promoted-cascade, valid_at, non-fact guard) ────────
+
+// Thread 2 — valid_at propagation. A re-extracted duplicate whose event time
+// yields only a start bound ("since 2024", "yesterday") must get the corrected
+// per-fact validFrom onto the existing copy so as-of recall uses the corrected
+// start. The orchestrator helper's rule: patch valid_at when the incoming
+// validFrom is EXTRACTED and the copy's start bound is batch-anchored
+// (assumed/legacy); never clobber a copy that already carries an extracted
+// per-fact anchor. This test pins that rule against the storage patch the
+// helper issues.
+test("#1707 thread 2: corrected extracted validFrom overwrites a batch-anchored valid_at", async () => {
+  const { storage, cleanup } = await makeStorage("bitemporal-1707-validFrom-");
+  try {
+    // Old promoted copy: batch-anchored valid_at, no per-fact event-time.
+    const content = "We have used Stripe for payments since 2024.";
+    const batchAnchor = "2026-06-01T00:00:00.000Z";
+    const id = await storage.writeMemory("fact", content, {
+      confidence: 0.9,
+      validAt: batchAnchor,
+      // No eventTimeSource → batch-anchored (legacy pre-#1670 copy).
+    });
+    const before = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(before);
+    assert.equal(before!.frontmatter.valid_at, batchAnchor);
+    assert.equal(before!.frontmatter.eventTimeSource, undefined);
+
+    // Simulate the helper's rule: incoming validFrom is extracted → patch
+    // because the copy is NOT extracted-anchored (fm.eventTimeSource !== "extracted").
+    const correctedValidFrom = "2024-01-01T00:00:00.000Z";
+    const incomingExtracted = true;
+    const copyExtracted = before!.frontmatter.eventTimeSource === "extracted";
+    const shouldPatchValidAt =
+      incomingExtracted && (copyExtracted === false || !before!.frontmatter.valid_at);
+    assert.equal(shouldPatchValidAt, true, "must correct the batch-anchored valid_at");
+
+    const ok = await storage.writeMemoryFrontmatter(before!, {
+      valid_at: correctedValidFrom,
+      eventTimeSource: "extracted",
+      observedAt: "2026-06-20T00:00:00.000Z",
+    });
+    assert.equal(ok, true);
+
+    const after = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(after);
+    assert.equal(after!.frontmatter.valid_at, correctedValidFrom);
+    assert.equal(after!.frontmatter.eventTimeSource, "extracted");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("#1707 thread 2: identical extracted validFrom is a no-op (equality short-circuit)", async () => {
+  const { storage, cleanup } = await makeStorage("bitemporal-1707-validFrom-equal-");
+  try {
+    // Copy already carries an extracted per-fact anchor.
+    const content = "The migration to MySQL completed in March 2025.";
+    const existingValidAt: string = "2025-03-01T00:00:00.000Z";
+    const id = await storage.writeMemory("fact", content, {
+      confidence: 0.9,
+      validAt: existingValidAt,
+      observedAt: "2025-06-01T00:00:00.000Z",
+      eventTimeSource: "extracted",
+    });
+    const before = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(before);
+
+    // Re-extraction resolves the SAME start bound (deterministic per #1670).
+    // The helper's equality short-circuit (fm.valid_at !== bounds.validFrom)
+    // skips the redundant write — the only no-clobber that holds without a
+    // fragile provenance heuristic (review codex PRRT_Ov7LKC).
+    const helperWouldPatch = existingValidAt !== existingValidAt; // equal → false
+    assert.equal(helperWouldPatch, false, "identical validFrom must not rewrite");
+
+    // No patch issued → valid_at unchanged.
+    const after = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(after);
+    assert.equal(after!.frontmatter.valid_at, existingValidAt);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("#1707 thread 2: differing extracted validFrom overwrites (authoritative re-evaluation)", async () => {
+  const { storage, cleanup } = await makeStorage("bitemporal-1707-validFrom-differ-");
+  try {
+    // Copy carries an older (batch-anchored) valid_at.
+    const content = "We have used Stripe for payments since 2024.";
+    const staleValidAt: string = "2026-06-01T00:00:00.000Z"; // batch anchor
+    const id = await storage.writeMemory("fact", content, {
+      confidence: 0.9,
+      validAt: staleValidAt,
+    });
+    const before = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(before);
+
+    // Re-extraction resolves a DIFFERING extracted start bound. Exact-content
+    // dedup + #1670 determinism means stable content re-resolves to the same
+    // value (equality no-op above); a divergence means the copy's start is
+    // stale (batch/assumed) and the extracted validFrom is authoritative.
+    const correctedValidFrom: string = "2024-01-01T00:00:00.000Z";
+    const helperWouldPatch = staleValidAt !== correctedValidFrom; // differ → true
+    assert.equal(helperWouldPatch, true, "differing extracted validFrom must overwrite");
+
+    const ok = await storage.writeMemoryFrontmatter(before!, {
+      valid_at: correctedValidFrom,
+      eventTimeSource: "extracted",
+    });
+    assert.equal(ok, true);
+
+    const after = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(after);
+    assert.equal(after!.frontmatter.valid_at, correctedValidFrom);
+    assert.equal(after!.frontmatter.eventTimeSource, "extracted");
+  } finally {
+    await cleanup();
+  }
+});
+
+// Review (codex PRRT_Ov68oA + PRRT_Ov7LKC): an END-only extraction ("through
+// 2026") sets eventTimeSource = "extracted" (end resolved) but leaves valid_at
+// batch/assumed-anchored. A later START-bound extraction must still correct
+// valid_at. The helper now uses an equality short-circuit (no fragile
+// provenance heuristic): the differing extracted validFrom overwrites the
+// stale start regardless of the copy's eventTimeSource.
+test("#1707 thread 2: end-only extracted provenance does NOT block a later start-bound correction", async () => {
+  const { storage, cleanup } = await makeStorage("bitemporal-1707-endonly-");
+  try {
+    // Copy state after an end-only backfill: eventTimeSource = "extracted"
+    // (the end "through 2026" resolved), but valid_at is still the ingestion
+    // anchor (assumed start).
+    const observedAt = "2026-06-01T00:00:00.000Z";
+    const content = "The service was maintained through 2026.";
+    const id = await storage.writeMemory("fact", content, {
+      confidence: 0.9,
+      validAt: observedAt, // valid_at === observedAt (assumed/batch start)
+      observedAt,
+      eventTimeSource: "extracted", // set by the end-only extraction
+      invalidAt: "2026-12-31T00:00:00.000Z", // the extracted end bound
+    });
+    const before = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(before);
+    assert.equal(before!.frontmatter.eventTimeSource, "extracted");
+    assert.equal(before!.frontmatter.valid_at, before!.frontmatter.observedAt);
+
+    // The helper's valid_at gate (mirrors orchestrator.ts):
+    //   bounds.validFrom && eventTimeSource === "extracted" && valid_at !== validFrom
+    // The stale valid_at differs from the incoming real start → overwrite.
+
+    // A later re-extraction with a real extracted start must correct valid_at.
+    const realStart = "2024-03-01T00:00:00.000Z";
+    const ok = await storage.writeMemoryFrontmatter(before!, {
+      valid_at: realStart,
+    });
+    assert.equal(ok, true);
+
+    const after = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(after);
+    assert.equal(after!.frontmatter.valid_at, realStart);
+  } finally {
+    await cleanup();
+  }
+});
+
+// Gate guard (review cursor PRRT_OvHk / codex PRRT_OvHxVH): resolveFactEventTime
+// sets a validFrom for EVERY fact (assumed = ingestion anchor). The helper's
+// I/O gate must NOT scan on an assumed validFrom — only an EXTRACTED start bound
+// changes recall. This pins the gate decision so ordinary duplicate facts
+// without an extracted event time do not pay a readAllMemories scan on every
+// dedup hit.
+test("#1707 thread 2: assumed (batch-anchored) validFrom does NOT trigger a backfill scan", () => {
+  // Mirror the helper's I/O gate (orchestrator.ts backfillTemporalBoundsOnDedupHit):
+  //   const hasExtractedStart = bounds.validFrom !== undefined && bounds.eventTimeSource === "extracted";
+  //   if (!bounds.invalidAt && !hasExtractedStart) return;
+  const gateWouldScan = (bounds: {
+    invalidAt?: string;
+    validFrom?: string;
+    eventTimeSource?: "extracted" | "assumed";
+  }) =>
+    Boolean(bounds.invalidAt) ||
+    (bounds.validFrom !== undefined && bounds.eventTimeSource === "extracted");
+
+  // Assumed validFrom alone (the common no-event-time case) → no scan.
+  assert.equal(
+    gateWouldScan({ validFrom: "2026-06-01T00:00:00.000Z", eventTimeSource: "assumed" }),
+    false,
+    "assumed validFrom must not trigger a scan",
+  );
+  // Extracted validFrom → scan (corrected start bound is recall-relevant).
+  assert.equal(
+    gateWouldScan({ validFrom: "2024-01-01T00:00:00.000Z", eventTimeSource: "extracted" }),
+    true,
+  );
+  // End bound alone → scan (expires the fact).
+  assert.equal(gateWouldScan({ invalidAt: "2025-06-01T00:00:00.000Z" }), true);
+  // No bounds at all → no scan.
+  assert.equal(gateWouldScan({}), false);
+});
+// Thread 1 — promoted-cascade backfill. When the source-namespace dedup
+// short-circuit fires, the helper must also patch promotion-target copies
+// (profile + shared namespaces) so cross-namespace recall does not surface an
+// expired fact. This proves the mechanism the orchestrator's promotion-cascade
+// closure relies on: backfilling two separate storages patches each
+// independently.
+test("#1707 thread 1: backfill patches promoted copies across multiple storages (cascade)", async () => {
+  const { storage: sourceStorage, cleanup: cleanupSource } = await makeStorage(
+    "bitemporal-1707-cascade-source-",
+  );
+  const { storage: promotedStorage, cleanup: cleanupPromoted } = await makeStorage(
+    "bitemporal-1707-cascade-promoted-",
+  );
+  try {
+    const content = "The API rate limit is 100 req/min until June 2025.";
+    // Both namespaces hold the same fact, written WITHOUT bounds (stale copies).
+    const sourceId = await sourceStorage.writeMemory("fact", content, { confidence: 0.9 });
+    const promotedId = await promotedStorage.writeMemory("fact", content, { confidence: 0.9 });
+
+    // Simulate re-extraction that now carries a resolved invalidAt. The
+    // promotion-cascade closure calls the same backfill against each target.
+    const bounds = {
+      invalid_at: "2025-06-01T00:00:00.000Z",
+      observedAt: "2025-06-20T00:00:00.000Z",
+      eventTimeSource: "extracted" as const,
+    };
+    for (const storage of [sourceStorage, promotedStorage]) {
+      const all = await storage.readAllMemories();
+      const existing = all.find(
+        (m) =>
+          m.frontmatter.category === "fact" &&
+          (m.frontmatter.status ?? "active") === "active" &&
+          !m.frontmatter.invalid_at &&
+          ContentHashIndex.normalizeContent(m.content ?? "") ===
+            ContentHashIndex.normalizeContent(content),
+      );
+      assert.ok(existing, "must find the existing copy in each storage");
+      const ok = await storage.writeMemoryFrontmatter(existing!, bounds);
+      assert.equal(ok, true);
+    }
+
+    // Both copies now carry the resolved end bound — cross-namespace recall
+    // honours the expiry instead of surfacing the stale promoted copy.
+    const sourceAfter = (await sourceStorage.readAllMemories()).find(
+      (m) => m.frontmatter.id === sourceId,
+    );
+    const promotedAfter = (await promotedStorage.readAllMemories()).find(
+      (m) => m.frontmatter.id === promotedId,
+    );
+    assert.ok(sourceAfter && promotedAfter);
+    assert.equal(sourceAfter!.frontmatter.invalid_at, "2025-06-01T00:00:00.000Z");
+    assert.equal(promotedAfter!.frontmatter.invalid_at, "2025-06-01T00:00:00.000Z");
+  } finally {
+    await cleanupSource();
+    await cleanupPromoted();
+  }
+});
+
+// Thread 3 — non-fact guard. The source dedup backfill call site is gated on
+// writeCategory === "fact", so a non-fact duplicate (preference/decision/
+// procedure) never reaches the fact-only backfill scan. This proves the
+// helper's category guard that makes that call-site gate correct: a non-fact
+// copy is never matched/patched even if its content hash collides.
+test("#1707 thread 3: backfill never patches a non-fact copy (category guard)", async () => {
+  const { storage, cleanup } = await makeStorage("bitemporal-1707-nonfact-");
+  try {
+    const content = "The user prefers dark mode.";
+    // A preference (non-fact) whose content would collide with an incoming
+    // duplicate candidate.
+    const id = await storage.writeMemory("preference", content, { confidence: 0.9 });
+    const before = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(before);
+    assert.equal(before!.frontmatter.category, "preference");
+    assert.equal(before!.frontmatter.invalid_at, undefined);
+
+    // The helper's lookup filters category === "fact" — a preference copy is
+    // never eligible, so no patch is issued even when bounds are present.
+    const all = await storage.readAllMemories();
+    const existing = all.find(
+      (m) =>
+        m.frontmatter.category === "fact" && // ← the guard under test
+        (m.frontmatter.status ?? "active") === "active" &&
+        ContentHashIndex.normalizeContent(m.content ?? "") ===
+          ContentHashIndex.normalizeContent(content),
+    );
+    assert.equal(existing, undefined, "non-fact copy must not be matched by the fact-only lookup");
+
+    // No patch → the preference copy is untouched.
+    const after = (await storage.readAllMemories()).find((m) => m.frontmatter.id === id);
+    assert.ok(after);
+    assert.equal(after!.frontmatter.invalid_at, undefined);
+    assert.equal(after!.frontmatter.category, "preference");
+  } finally {
+    await cleanup();
+  }
+});

package/src/capabilities.test.ts

@@ -153,6 +153,12 @@ import {
   type GraphConstructionCapabilitySet,
 } from "./capabilities.js";
 
+import {
+  resolveMemoryLifecycleCapabilities,
+  type MemoryLifecycleCapabilitySet,
+} from "./capabilities.js";
+
+
 const GRAPH_FIELD_TO_FLAG: Record<keyof GraphConstructionCapabilitySet, string> = {
   entityGraph: "entityGraphEnabled",
   timeGraph: "timeGraphEnabled",
@@ -306,3 +312,152 @@ test("resolveGraphConstructionCapabilities matches pre-migration config reads (p
     );
   }
 });
+
+
+// ---------------------------------------------------------------------------
+// MemoryLifecycleCapabilitySet — gate-parity tests (issue #1523 batch 3).
+//
+// Same invariant as the sets above: every caps field must project from its
+// `<field>Enabled` config flag, so a future edit that maps a field to the wrong
+// flag fails loudly here. All ten flags are required booleans on PluginConfig
+// (defaults resolved at the parse boundary), so the projection is a pure
+// passthrough — no optional-default variants needed.
+//
+// Parity contract: a caps-resolved run and a config-derived run MUST produce
+// identical boolean values for every gate — on AND off.
+// ---------------------------------------------------------------------------
+
+const LIFECYCLE_FIELD_TO_FLAG: Record<keyof MemoryLifecycleCapabilitySet, string> = {
+  temporalSupersession: "temporalSupersessionEnabled",
+  temporalMemoryTree: "temporalMemoryTreeEnabled",
+  lifecyclePolicy: "lifecyclePolicyEnabled",
+  lifecycleFilterStale: "lifecycleFilterStaleEnabled",
+  lifecycleMetrics: "lifecycleMetricsEnabled",
+  extractionScopeClassification: "extractionScopeClassificationEnabled",
+  extractionJudge: "extractionJudgeEnabled",
+  extractionDedupe: "extractionDedupeEnabled",
+  extractionTelemetryPrefilter: "extractionTelemetryPrefilterEnabled",
+  extractionJudgeTelemetry: "extractionJudgeTelemetryEnabled",
+  embeddingFallback: "embeddingFallbackEnabled",
+};
+
+const LIFECYCLE_FIELDS = Object.keys(LIFECYCLE_FIELD_TO_FLAG) as Array<
+  keyof MemoryLifecycleCapabilitySet
+>;
+
+test("resolveMemoryLifecycleCapabilities projects every field from its flag (true variant)", () => {
+  const overrides: Record<string, boolean> = {};
+  for (const flag of Object.values(LIFECYCLE_FIELD_TO_FLAG)) overrides[flag] = true;
+  const config = parseConfig(overrides);
+  const caps = resolveMemoryLifecycleCapabilities(config);
+
+  for (const field of LIFECYCLE_FIELDS) {
+    const flag = LIFECYCLE_FIELD_TO_FLAG[field];
+    assert.equal(
+      caps[field],
+      (config as unknown as Record<string, boolean>)[flag],
+      `caps.${field} must equal config.${flag} (true variant)`,
+    );
+    assert.equal(caps[field], true, `caps.${field} should be true here`);
+  }
+});
+
+test("resolveMemoryLifecycleCapabilities projects every field from its flag (false variant)", () => {
+  const overrides: Record<string, boolean> = {};
+  for (const flag of Object.values(LIFECYCLE_FIELD_TO_FLAG)) overrides[flag] = false;
+  const config = parseConfig(overrides);
+  const caps = resolveMemoryLifecycleCapabilities(config);
+
+  for (const field of LIFECYCLE_FIELDS) {
+    const flag = LIFECYCLE_FIELD_TO_FLAG[field];
+    assert.equal(
+      caps[field],
+      (config as unknown as Record<string, boolean>)[flag],
+      `caps.${field} must equal config.${flag} (false variant)`,
+    );
+    assert.equal(caps[field], false, `caps.${field} should be false here`);
+  }
+});
+
+test("resolveMemoryLifecycleCapabilities returns a frozen object", () => {
+  const config = parseConfig({});
+  const caps = resolveMemoryLifecycleCapabilities(config);
+  assert.equal(Object.isFrozen(caps), true);
+});
+
+test("resolveMemoryLifecycleCapabilities matches pre-migration config reads (parity contract)", () => {
+  // For representative on/off combinations, the caps-resolved values MUST be
+  // identical to what the old scattered `this.config.<flag>Enabled` reads
+  // produced. All ten flags used bare reads (no `!== false`/`=== true` at the
+  // call site that would change the value — the two sites that wrote
+  // `=== true` were redundant coercion on an already-boolean config field),
+  // so parity is a direct equality against the resolved config boolean.
+  const cases: Record<string, Record<string, boolean>> = {
+    "all-off": {
+      temporalSupersessionEnabled: false,
+      temporalMemoryTreeEnabled: false,
+      lifecyclePolicyEnabled: false,
+      lifecycleFilterStaleEnabled: false,
+      lifecycleMetricsEnabled: false,
+      extractionScopeClassificationEnabled: false,
+      extractionJudgeEnabled: false,
+      extractionDedupeEnabled: false,
+      extractionTelemetryPrefilterEnabled: false,
+      extractionJudgeTelemetryEnabled: false,
+      embeddingFallbackEnabled: false,
+    },
+    "all-on": {
+      temporalSupersessionEnabled: true,
+      temporalMemoryTreeEnabled: true,
+      lifecyclePolicyEnabled: true,
+      lifecycleFilterStaleEnabled: true,
+      lifecycleMetricsEnabled: true,
+      extractionScopeClassificationEnabled: true,
+      extractionJudgeEnabled: true,
+      extractionDedupeEnabled: true,
+      extractionTelemetryPrefilterEnabled: true,
+      extractionJudgeTelemetryEnabled: true,
+      embeddingFallbackEnabled: true,
+    },
+    "temporal-on-rest-off": {
+      temporalSupersessionEnabled: true,
+      temporalMemoryTreeEnabled: true,
+      lifecyclePolicyEnabled: false,
+      lifecycleFilterStaleEnabled: false,
+      lifecycleMetricsEnabled: false,
+      extractionScopeClassificationEnabled: false,
+      extractionJudgeEnabled: false,
+      extractionDedupeEnabled: false,
+      extractionTelemetryPrefilterEnabled: false,
+      extractionJudgeTelemetryEnabled: false,
+      embeddingFallbackEnabled: false,
+    },
+    "extraction-on-rest-off": {
+      temporalSupersessionEnabled: false,
+      temporalMemoryTreeEnabled: false,
+      lifecyclePolicyEnabled: false,
+      lifecycleFilterStaleEnabled: false,
+      lifecycleMetricsEnabled: false,
+      extractionScopeClassificationEnabled: true,
+      extractionJudgeEnabled: true,
+      extractionDedupeEnabled: true,
+      extractionTelemetryPrefilterEnabled: true,
+      extractionJudgeTelemetryEnabled: true,
+      embeddingFallbackEnabled: true,
+    },
+  };
+
+  for (const [label, overrides] of Object.entries(cases)) {
+    const config = parseConfig(overrides);
+    const caps = resolveMemoryLifecycleCapabilities(config);
+
+    for (const field of LIFECYCLE_FIELDS) {
+      const flag = LIFECYCLE_FIELD_TO_FLAG[field];
+      assert.equal(
+        caps[field],
+        (config as unknown as Record<string, boolean>)[flag],
+        `[${label}] caps.${field} must equal config.${flag}`,
+      );
+    }
+  }
+});

package/src/capabilities.ts

@@ -203,3 +203,94 @@ export function resolveAccessSetupCapabilities(
     recallAuditAnomalyDetection: config.recallAuditAnomalyDetectionEnabled === true,
   });
 }
+
+// ---------------------------------------------------------------------------
+// Memory-lifecycle capability set (issue #1523 batch 3).
+//
+// The flags below gate memory WRITE/EXTRACTION (extraction judge, scope
+// classification, dedupe, telemetry prefilter), temporal supersession of
+// stored facts, and the lifecycle policy pass (promotion / decay / stale
+// filtering). They are read on the persistExtraction write path, the recall
+// candidate-filter path, and the maintenance / lifecycle-pass path — so, like
+// the graph-construction set above, they get their own projection resolved
+// ONCE at each operation entry that reads them (never re-derived from raw
+// config mid-operation — the gate-divergence defect class #1523 targets).
+//
+// Every field projects from an already-resolved PluginConfig boolean (defaults
+// are applied at the config-parse boundary, rule 36), so the resolver is a
+// pure projection — no `!== false` / `=== true` re-coercion here.
+// ---------------------------------------------------------------------------
+
+/**
+ * Frozen projection of memory-lifecycle feature gates (issue #1523 batch 3).
+ *
+ * Resolved once per write / recall-filter / maintenance operation and threaded
+ * down. Composition lives ONLY in {@link resolveMemoryLifecycleCapabilities}.
+ */
+export interface MemoryLifecycleCapabilitySet {
+  /** `temporalSupersessionEnabled` — supersede stale structured facts on write, filter on recall. */
+  readonly temporalSupersession: boolean;
+  /** `temporalMemoryTreeEnabled` — temporal-memory-tree build + recall tier. */
+  readonly temporalMemoryTree: boolean;
+  /** `lifecyclePolicyEnabled` — lifecycle promotion / decay metadata pass. */
+  readonly lifecyclePolicy: boolean;
+  /** `lifecycleFilterStaleEnabled` — filter stale-lifecycle memories from recall. */
+  readonly lifecycleFilterStale: boolean;
+  /** `lifecycleMetricsEnabled` — emit lifecycle-pass metrics. */
+  readonly lifecycleMetrics: boolean;
+  /** `extractionScopeClassificationEnabled` — LLM classifies each fact's scope. */
+  readonly extractionScopeClassification: boolean;
+  /** `extractionJudgeEnabled` — LLM-as-judge fact-worthiness gate. */
+  readonly extractionJudge: boolean;
+  /** `extractionDedupeEnabled` — dedupe against recent extractions. */
+  readonly extractionDedupe: boolean;
+  /** `extractionTelemetryPrefilterEnabled` — skip mechanical-telemetry transcripts. */
+  readonly extractionTelemetryPrefilter: boolean;
+  /** `extractionJudgeTelemetryEnabled` — collect judge verdict telemetry. */
+  readonly extractionJudgeTelemetry: boolean;
+  /** `embeddingFallbackEnabled` — semantic-dedup / archive-search embedding fallback. */
+  readonly embeddingFallback: boolean;
+}
+
+/**
+ * Config projection consumed by {@link resolveMemoryLifecycleCapabilities}.
+ */
+export type MemoryLifecycleConfigProjection = Pick<
+  PluginConfig,
+  | "temporalSupersessionEnabled"
+  | "temporalMemoryTreeEnabled"
+  | "lifecyclePolicyEnabled"
+  | "lifecycleFilterStaleEnabled"
+  | "lifecycleMetricsEnabled"
+  | "extractionScopeClassificationEnabled"
+  | "extractionJudgeEnabled"
+  | "extractionDedupeEnabled"
+  | "extractionTelemetryPrefilterEnabled"
+  | "extractionJudgeTelemetryEnabled"
+  | "embeddingFallbackEnabled"
+>;
+
+/**
+ * Resolve the {@link MemoryLifecycleCapabilitySet} from parsed config.
+ *
+ * Call this ONCE per write / recall-filter / maintenance operation entry and
+ * thread the result down — exactly the pattern {@link resolveCapabilities}
+ * established for recall.
+ */
+export function resolveMemoryLifecycleCapabilities(
+  config: MemoryLifecycleConfigProjection,
+): MemoryLifecycleCapabilitySet {
+  return Object.freeze({
+    temporalSupersession: config.temporalSupersessionEnabled,
+    temporalMemoryTree: config.temporalMemoryTreeEnabled,
+    lifecyclePolicy: config.lifecyclePolicyEnabled,
+    lifecycleFilterStale: config.lifecycleFilterStaleEnabled,
+    lifecycleMetrics: config.lifecycleMetricsEnabled,
+    extractionScopeClassification: config.extractionScopeClassificationEnabled,
+    extractionJudge: config.extractionJudgeEnabled,
+    extractionDedupe: config.extractionDedupeEnabled,
+    extractionTelemetryPrefilter: config.extractionTelemetryPrefilterEnabled,
+    extractionJudgeTelemetry: config.extractionJudgeTelemetryEnabled,
+    embeddingFallback: config.embeddingFallbackEnabled,
+  });
+}

package/src/chat/chat-engine.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { strict as assert } from "node:assert";
-import { mkdir, rm, readFile } from "node:fs/promises";
+import { mkdir, rm, readFile, utimes, unlink, appendFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { test } from "node:test";
@@ -22,6 +22,7 @@ import {
   sessionBelongsToPrincipal,
   chatSessionFile,
   cleanupExpiredChatSessions,
+  __resetTranscriptSeqForTest,
 } from "./chat-session.js";
 import type { ChatSessionState } from "./chat-types.js";
 import type { ChatToolExecutor } from "./chat-engine.js";
@@ -270,3 +271,105 @@ test("budget exhaustion summary LLM failure does not crash (Thread 16)", async (
   assert.ok(result.reply.length > 0, "Should return a fallback reply");
   assert.ok(result.skippedTools !== undefined, "Should report skipped tools");
 });
+
+// ---------------------------------------------------------------------------
+// TTL boundary (issue #1685 item 1 / #1687 Thread 21)
+// ---------------------------------------------------------------------------
+
+test("cleanupExpiredChatSessions honors TTL boundary [0, ttlHours) — age >= ttl expires", async () => {
+  const dir = await makeTempDir();
+  const ttlHours = 2;
+  const ttlMs = ttlHours * 3600 * 1000;
+
+  // Session aged past the TTL (mtime set to ttlHours ago; by the time the
+  // sweep stat()s it a few ms have elapsed, so age >= ttl deterministically
+  // — the boundary is inclusive: age ∈ [0, ttl) survives, age >= ttl expires).
+  const expired = await createChatSession(dir, { principal: "expired" });
+  const expiredFile = chatSessionFile(dir, expired.id);
+  const atTtlSeconds = (Date.now() - ttlMs) / 1000;
+  await utimes(expiredFile, atTtlSeconds, atTtlSeconds);
+
+  // Session aged well under the TTL → must survive.
+  const fresh = await createChatSession(dir, { principal: "fresh" });
+  const freshFile = chatSessionFile(dir, fresh.id);
+  const underTtlSeconds = (Date.now() - (ttlMs - 6 * 60 * 1000)) / 1000; // ~1.9h old
+  await utimes(freshFile, underTtlSeconds, underTtlSeconds);
+
+  const removed = await cleanupExpiredChatSessions(dir, ttlHours);
+  assert.equal(removed, 1, "only the expired session should be removed");
+
+  // The fresh session file must still be on disk.
+  const freshStillExists = await readFile(freshFile, "utf8").then(() => true).catch(() => false);
+  assert.ok(freshStillExists, "session aged under the TTL must survive the sweep");
+
+  // The expired session file must be gone.
+  const expiredGone = await readFile(expiredFile, "utf8").then(() => false).catch(() => true);
+  assert.ok(expiredGone, "session aged at/over the TTL must be swept");
+});
+
+
+test("appendTranscriptEntry emits strictly-increasing seqs even within the same millisecond (issue #1687 review)", async () => {
+  const dir = await makeTempDir();
+  const session = await createChatSession(dir, { principal: "seq" });
+  // Append several entries as fast as possible (same-ms collisions would have
+  // shared a Date.now()-based seq before the monotonic counter fix).
+  const entries: number[] = [];
+  for (let i = 0; i < 8; i++) {
+    const e = await appendTranscriptEntry(dir, session.id, { role: "user", content: `m${i}` });
+    entries.push(e.seq);
+  }
+  // Every seq must be distinct and strictly increasing.
+  for (let i = 1; i < entries.length; i++) {
+    assert.ok(entries[i]! > entries[i - 1]!, `seq ${entries[i]} must exceed ${entries[i - 1]}`);
+  }
+  assert.equal(new Set(entries).size, entries.length, "seqs must be unique");
+});
+
+test("appendTranscriptEntry refuses to recreate a swept session (chat_session_expired) — codex P2 #1687", async () => {
+  const dir = await makeTempDir();
+  const session = await createChatSession(dir, { principal: "alice" });
+  // Simulate the TTL sweep unlinking the file mid-turn (resurrection race).
+  await unlink(chatSessionFile(dir, session.id));
+  // Must throw instead of silently recreating a headerless (public) file.
+  await assert.rejects(
+    appendTranscriptEntry(dir, session.id, { role: "user", content: "x" }),
+    /chat_session_expired/,
+  );
+});
+
+
+test("loadChatSession raises the seq counter above the on-disk max on backward clock skew (issue #1718)", async () => {
+  const dir = await makeTempDir();
+  const session = await createChatSession(dir, { principal: "skew" });
+  // Simulate a previous process that ran with a forward-skewed clock: append a
+  // transcript line whose seq is far in the future relative to the current
+  // Date.now(). A later restart with a normal (or backward-stepped) clock must
+  // still issue seqs strictly greater than this persisted line.
+  const futureSeq = Date.now() + 10_000_000;
+  await appendFile(
+    chatSessionFile(dir, session.id),
+    JSON.stringify({
+      seq: futureSeq,
+      ts: new Date().toISOString(),
+      role: "user",
+      content: "future-dated line from a forward-skewed prior process",
+    }) + "\n",
+    "utf8",
+  );
+  // Simulate a process restart whose module-level counter starts below the
+  // persisted on-disk seq (the backward-clock-skew window).
+  __resetTranscriptSeqForTest();
+  // Resume the session: loadChatSession must raise the counter above the
+  // on-disk max so the next append is strictly greater, regardless of the
+  // current Date.now().
+  const loaded = await loadChatSession(dir, session.id);
+  assert.ok(loaded, "session must load");
+  const next = await appendTranscriptEntry(dir, session.id, {
+    role: "assistant",
+    content: "resumed after backward clock skew",
+  });
+  assert.ok(
+    next.seq > futureSeq,
+    `seq ${next.seq} must exceed the on-disk max ${futureSeq} after a backward clock skew (issue #1718)`,
+  );
+});