agent-working-memory 0.16.1 → 0.18.1

package/src/core/whoami.ts

@@ -1,120 +1,136 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Instance identity (D3, 2026-07-30).
- *
- * Answers "which AWM am I talking to?" — the recurring confusion class where
- * sessions mix up the hosted multi-agent connector with the local instance,
- * or run blind to sibling agent spaces in the same store (an evaluation once
- * analyzed this project without seeing the `personal` space that held its
- * design decisions).
- *
- * Exposed as the `memory_whoami` MCP tool and the `GET /whoami` HTTP route.
- * Read-only; additive module.
- */
-
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { VERSION } from '../version.js';
-import { getConfiguredBackend, getConfiguredPath } from '../storage/factory.js';
-import { activeRecallConfig, recallConfigFingerprint } from './recall-config.js';
-import { embeddingHealth } from './embeddings.js';
-
-export interface WhoamiInfo {
-  agentId: string;
-  workspace: string | null;
-  surface: 'mcp' | 'http';
-  mode: 'standalone' | 'hive';
-  backend: string;
-  storePath: string;
-  version: string;
-  codePath: string;
-  pid: number;
-  ports: { http: number | null; hookSidecar: number | null };
-  /**
-   * Effective recall configuration. `whoami` is the "what am I actually
-   * running" tool, and the version alone does not answer that: a build can be
-   * current while the recall flags that change its behavior are unset, or set
-   * to something unintended. GET /health already reports this, but HTTP is off
-   * by default, so an MCP-only session had no way to see it.
-   */
-  recall: { fingerprint: string; flags: Record<string, string> };
-  siblingAgents: string[];
-}
-
-/** Store subset whoami needs — every backend implements listAgentIds. */
-export interface WhoamiStore {
-  listAgentIds(): string[] | Promise<string[]>;
-}
-
-function packageRoot(): string {
-  // src/core/whoami.ts (dev) and dist/core/whoami.js (build) both sit two
-  // levels below the package root.
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(join(here, '..', '..'));
-}
-
-export async function buildWhoami(
-  store: WhoamiStore,
-  agentId: string,
-  surface: 'mcp' | 'http',
-  /**
-   * 0.14.2: the port the hook sidecar actually BOUND, from the running handle.
-   * Before this, whoami echoed AWM_HOOK_PORT from the environment — so a session
-   * whose sidecar had lost the port fight and disabled hooks still reported
-   * "hookSidecar=8401". Pass `null` for "tried and failed"; omit (undefined)
-   * for surfaces that have no sidecar, which falls back to the env value.
-   */
-  boundHookPort?: number | null,
-): Promise<WhoamiInfo> {
-  const coordination = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
-  let siblings: string[] = [];
-  try {
-    const all = await store.listAgentIds();
-    siblings = all.filter(a => a !== agentId).sort();
-  } catch { /* identity must never fail on a listing error */ }
-  const httpPort = Number(process.env.AWM_PORT ?? '');
-  const hookPort = Number(process.env.AWM_HOOK_PORT ?? '');
-  return {
-    agentId,
-    workspace: process.env.AWM_WORKSPACE ?? null,
-    surface,
-    mode: coordination ? 'hive' : 'standalone',
-    backend: getConfiguredBackend(),
-    storePath: getConfiguredPath(),
-    version: VERSION,
-    codePath: packageRoot(),
-    pid: process.pid,
-    ports: {
-      http: Number.isFinite(httpPort) && httpPort > 0 ? httpPort : null,
-      hookSidecar: boundHookPort !== undefined
-        ? boundHookPort
-        : (Number.isFinite(hookPort) && hookPort > 0 ? hookPort : null),
-    },
-    recall: { fingerprint: recallConfigFingerprint(), flags: activeRecallConfig() },
-    siblingAgents: siblings,
-  };
-}
-
-/** Human-readable rendering for the MCP tool response. */
-export function formatWhoami(w: WhoamiInfo): string {
-  return [
-    `Agent: ${w.agentId}${w.workspace ? ` (workspace: ${w.workspace})` : ''}`,
-    `Mode: ${w.mode} · Surface: ${w.surface} · Version: ${w.version}`,
-    `Backend: ${w.backend}`,
-    `Store: ${w.storePath}`,
-    `Code: ${w.codePath} (pid ${w.pid})`,
-    `Ports: http=${w.ports.http ?? 'off'} hookSidecar=${w.ports.hookSidecar ?? 'off'}`,
-    `Recall config: ${w.recall.fingerprint}`,
-    ...(embeddingHealth().dimensionMismatches > 0
-      ? [`\u26a0 EMBEDDING INTEGRITY: ${embeddingHealth().dimensionMismatches} dimension mismatches ` +
-         `(expected ${embeddingHealth().expectedDimensions}d). Affected memories score 0 on the ` +
-         `vector channel — the corpus is probably half-migrated. Re-embed the whole store or ` +
-         `revert AWM_EMBED_MODEL/AWM_EMBED_DIMS.`]
-      : []),
-    w.siblingAgents.length
-      ? `Sibling agent spaces in this store: ${w.siblingAgents.join(', ')} — recall is scoped to '${w.agentId}'; other spaces need workspace recall, \`awm export --agent <id>\`, or a session configured for that agent.`
-      : 'Sibling agent spaces in this store: none',
-  ].join('\n');
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Instance identity (D3, 2026-07-30).
+ *
+ * Answers "which AWM am I talking to?" — the recurring confusion class where
+ * sessions mix up the hosted multi-agent connector with the local instance,
+ * or run blind to sibling agent spaces in the same store (an evaluation once
+ * analyzed this project without seeing the `personal` space that held its
+ * design decisions).
+ *
+ * Exposed as the `memory_whoami` MCP tool and the `GET /whoami` HTTP route.
+ * Read-only; additive module.
+ */
+
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from '../version.js';
+import { getConfiguredBackend, getConfiguredPath } from '../storage/factory.js';
+import { activeRecallConfig, recallConfigFingerprint } from './recall-config.js';
+import { embeddingHealth } from './embeddings.js';
+import { modelDaemonStatus } from './ml-worker.js';
+
+export interface WhoamiInfo {
+  agentId: string;
+  workspace: string | null;
+  surface: 'mcp' | 'http';
+  mode: 'standalone' | 'hive';
+  backend: string;
+  storePath: string;
+  version: string;
+  codePath: string;
+  pid: number;
+  ports: { http: number | null; hookSidecar: number | null };
+  /**
+   * Effective recall configuration. `whoami` is the "what am I actually
+   * running" tool, and the version alone does not answer that: a build can be
+   * current while the recall flags that change its behavior are unset, or set
+   * to something unintended. GET /health already reports this, but HTTP is off
+   * by default, so an MCP-only session had no way to see it.
+   */
+  recall: { fingerprint: string; flags: Record<string, string> };
+  /** Where inference runs: this process, or the shared model daemon (AWM_MODEL_DAEMON=1). */
+  models: ReturnType<typeof modelDaemonStatus>;
+  siblingAgents: string[];
+}
+
+/** Store subset whoami needs — every backend implements listAgentIds. */
+export interface WhoamiStore {
+  listAgentIds(): string[] | Promise<string[]>;
+}
+
+function packageRoot(): string {
+  // src/core/whoami.ts (dev) and dist/core/whoami.js (build) both sit two
+  // levels below the package root.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(join(here, '..', '..'));
+}
+
+export async function buildWhoami(
+  store: WhoamiStore,
+  agentId: string,
+  surface: 'mcp' | 'http',
+  /**
+   * 0.14.2: the port the hook sidecar actually BOUND, from the running handle.
+   * Before this, whoami echoed AWM_HOOK_PORT from the environment — so a session
+   * whose sidecar had lost the port fight and disabled hooks still reported
+   * "hookSidecar=8401". Pass `null` for "tried and failed"; omit (undefined)
+   * for surfaces that have no sidecar, which falls back to the env value.
+   */
+  boundHookPort?: number | null,
+): Promise<WhoamiInfo> {
+  const coordination = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
+  let siblings: string[] = [];
+  try {
+    const all = await store.listAgentIds();
+    siblings = all.filter(a => a !== agentId).sort();
+  } catch { /* identity must never fail on a listing error */ }
+  const httpPort = Number(process.env.AWM_PORT ?? '');
+  const hookPort = Number(process.env.AWM_HOOK_PORT ?? '');
+  return {
+    agentId,
+    workspace: process.env.AWM_WORKSPACE ?? null,
+    surface,
+    mode: coordination ? 'hive' : 'standalone',
+    backend: getConfiguredBackend(),
+    storePath: getConfiguredPath(),
+    version: VERSION,
+    codePath: packageRoot(),
+    pid: process.pid,
+    ports: {
+      http: Number.isFinite(httpPort) && httpPort > 0 ? httpPort : null,
+      hookSidecar: boundHookPort !== undefined
+        ? boundHookPort
+        : (Number.isFinite(hookPort) && hookPort > 0 ? hookPort : null),
+    },
+    recall: { fingerprint: recallConfigFingerprint(), flags: activeRecallConfig() },
+    models: modelDaemonStatus(),
+    siblingAgents: siblings,
+  };
+}
+
+function formatModels(m: WhoamiInfo['models']): string {
+  if (!m.enabled) return 'in this process';
+  const fallback = m.fallbacks
+    ? ` · ${m.fallbacks} fallback(s) to in-process, last: ${m.lastFallbackReason} at ${m.lastFallbackAt}`
+    : '';
+  const where = m.mode === 'daemon' ? `shared daemon pid ${m.daemonPid}`
+    : m.mode === 'in-process-fallback' ? 'in this process (daemon unavailable)'
+    : 'shared daemon (not connected yet)';
+  return `${where} · fingerprint ${m.fingerprint} · ${m.requests} request(s)${fallback}`;
+}
+
+/** Human-readable rendering for the MCP tool response. */
+export function formatWhoami(w: WhoamiInfo): string {
+  return [
+    `Agent: ${w.agentId}${w.workspace ? ` (workspace: ${w.workspace})` : ''}`,
+    `Mode: ${w.mode} · Surface: ${w.surface} · Version: ${w.version}`,
+    `Backend: ${w.backend}`,
+    `Store: ${w.storePath}`,
+    `Code: ${w.codePath} (pid ${w.pid})`,
+    `Ports: http=${w.ports.http ?? 'off'} hookSidecar=${w.ports.hookSidecar ?? 'off'}`,
+    `Recall config: ${w.recall.fingerprint}`,
+    `Models: ${formatModels(w.models)}`,
+    ...(embeddingHealth().dimensionMismatches > 0
+      ? [`\u26a0 EMBEDDING INTEGRITY: ${embeddingHealth().dimensionMismatches} dimension mismatches ` +
+         `(expected ${embeddingHealth().expectedDimensions}d). Affected memories score 0 on the ` +
+         `vector channel — the corpus is probably half-migrated. Re-embed the whole store or ` +
+         `revert AWM_EMBED_MODEL/AWM_EMBED_DIMS.`]
+      : []),
+    w.siblingAgents.length
+      ? `Sibling agent spaces in this store: ${w.siblingAgents.join(', ')} — recall is scoped to '${w.agentId}'; other spaces need workspace recall, \`awm export --agent <id>\`, or a session configured for that agent.`
+      : 'Sibling agent spaces in this store: none',
+  ].join('\n');
+}

package/src/core/write-pipeline.ts

@@ -38,6 +38,7 @@
 import type { IEngramStore as EngramStore } from '../storage/store.js';
 import type { ConnectionEngine } from '../engine/connections.js';
 import type { Engram, MemoryClass, MemoryType } from '../types/engram.js';
+import { mergeBlockedByTrust, trustTier } from './trust.js';
 import {
   evaluateSalience,
   computeNoveltyWithMatch,
@@ -56,6 +57,15 @@ import { buildRetrievalText } from './retrieval-text.js';
 /** Confidence floor below which a matched engram is treated as "decaying out". */
 export const HEALTHY_CONFIDENCE_FLOOR = 0.3;
 
+/**
+ * Lowest novelty match score at which `correction: true` may supersede the
+ * match without an id. matchScore is the stronger of BM25 and cosine
+ * similarity (0–1). A paraphrased correction of one fact scores well above
+ * this (the probe's flight correction: 0.95); two unrelated memories about
+ * the same subject do not.
+ */
+const CORRECTION_MIN_MATCH = 0.6;
+
 /** Confidence delta applied on reinforcement. Bounded by REINFORCE_CONFIDENCE_CEIL. */
 export const REINFORCE_CONFIDENCE_DELTA = 0.05;
 export const REINFORCE_CONFIDENCE_CEIL = 0.95;
@@ -83,12 +93,41 @@ export interface WriteInput {
   eventType?: SalienceEventType;
   surprise?: number;
   decisionMade?: boolean;
+  /**
+   * Caller-declared purpose of the write: 'decision' | 'question' | 'todo' |
+   * 'finding' | 'context'. Stored as an `intent=` tag by the callers, and read HERE
+   * so a declared decision reaches the salience filter.
+   *
+   * It did not, before 2026-10-12: `intent` became a tag and nothing else, while the
+   * redundant `decisionMade` boolean was the only wired path, so a caller following
+   * the documented tagging discipline got no salience credit for saying this was a
+   * decision. Measured over all 496 discarded writes in the live store
+   * (`low-salience`, `work`+`personal`): those tagged `intent=decision` were later
+   * recalled at **77.3% against a 38.1% base rate**, +41pp — the strongest
+   * discriminator of any feature tested, discarded anyway.
+   *
+   * Mapped in the pipeline rather than at each call site so both write surfaces, and
+   * any future one, inherit it; widening the content-based operational-verb list was
+   * tested on the same population and rejected, because every candidate token scored
+   * at the base rate.
+   */
+  intent?: string;
   causalDepth?: number;
   resolutionEffort?: number;
   /** Confidence override. When unset, defaults from disposition + eventType priors. */
   confidence?: number;
   /** Explicit supersession requested by caller (independent of correction-on-match). */
   supersedes?: string;
+  /**
+   * This write corrects an existing memory whose id the caller does not have
+   * (2026-10-19). The closest active memory about the same thing — the same
+   * concept, else the novelty match when it is close enough — is superseded,
+   * the correction goes active at no less than that memory's confidence, and
+   * the result says what was replaced (`correctionOf`). Never reinforce-merges.
+   * With nothing close enough, the write is stored as new and `correctionOf`
+   * is null. An explicit `supersedes` outranks this.
+   */
+  correction?: boolean;
   /** Workspace scope for cross-agent novelty (v0.5.4+ stores only). */
   workspace?: string | null;
   /** Set to false to skip the reinforce/supersede branching and always create. */
@@ -132,6 +171,17 @@ export interface WriteResult {
   };
   /** Supersession detail — present only for action='supersede'. */
   supersedeOf?: { id: string };
+  /**
+   * Set when the write asked `correction: true`: the memory it replaced, or
+   * null when nothing close enough existed and the write was stored as new.
+   */
+  correctionOf?: { id: string; concept: string; matchScore: number } | null;
+  /**
+   * Set when a merge, supersede, revive or correction was refused because the
+   * write is less trusted than the memory it matched (src/core/trust.ts). The
+   * write was stored as its own engram instead.
+   */
+  trustBlocked?: { matchedId: string; writeTrust: number | null; matchedTrust: number | null };
 }
 
 export interface WritePipelineEngines {
@@ -169,8 +219,19 @@ export async function performWrite(
   input: WriteInput,
 ): Promise<WriteResult> {
   const { store, connectionEngine } = engines;
+  // An explicit `supersedes` argument outranks every novelty signal: the caller has
+  // NAMED the engram this write replaces. Gating reinforcement off it routes the write
+  // to createNewEngram, which is the only path that honors meta.supersedesId (see the
+  // supersession side-effects below). Without this gate the argument was silently
+  // discarded by every branch in the block below — R1 (healthy match reinforced),
+  // R2 (the superseder reinforced instead), R1b (an archived match revived), and R3,
+  // which supersedes `matched.id` rather than the id the caller actually asked for.
   const enableReinforcement = input.enableReinforcement !== false
-    && process.env.AWM_WRITE_PIPELINE !== 'off';
+    && process.env.AWM_WRITE_PIPELINE !== 'off'
+    && !input.supersedes
+    // A correction must never reinforce-merge: merging is exactly how a changed
+    // value ended up inside the stale memory with a "--- reinforced ---" marker.
+    && !input.correction;
 
   // Profiling: AWM_PROFILE_WRITE=1 logs ms-per-phase to stderr (v0.8.2).
   // Off by default; zero cost when unset.
@@ -223,7 +284,7 @@ export async function performWrite(
     content: input.content,
     eventType: effectiveEventType,
     surprise: input.surprise,
-    decisionMade: input.decisionMade,
+    decisionMade: input.decisionMade || input.intent === 'decision',
     causalDepth: input.causalDepth,
     resolutionEffort: input.resolutionEffort,
     novelty: noveltyResult.novelty,
@@ -234,6 +295,7 @@ export async function performWrite(
   const tStartCreate = performance.now();
   let busyHit = false;
   let result: WriteResult | null = null;
+  let trustBlocked: WriteResult['trustBlocked'];
   try {
   if (enableReinforcement && noveltyResult.matchedEngramId) {
     const matched = await store.getEngram(noveltyResult.matchedEngramId);
@@ -241,7 +303,12 @@ export async function performWrite(
     // workspace/hive recall can surface another agent's same-concept engram as the match; mutating it
     // (merge content, re-embed, bump confidence, or supersede) would corrupt that agent's memory. A
     // cross-agent match falls through to createNewEngram so this agent gets its own copy.
-    if (matched && matched.agentId === input.agentId) {
+    // Trust guard (2026-10-19, src/core/trust.ts): a less-trusted write never merges into,
+    // supersedes or revives a more-trusted memory. It falls through to its own engram.
+    if (matched && matched.agentId === input.agentId && mergeBlockedByTrust(input.tags, matched.tags)) {
+      trustBlocked = { matchedId: matched.id, writeTrust: trustTier(input.tags), matchedTrust: trustTier(matched.tags) };
+    }
+    if (matched && matched.agentId === input.agentId && !trustBlocked) {
       const newConcept = (input.concept ?? '').toLowerCase().trim();
       const matchedConcept = (matched.concept ?? '').toLowerCase().trim();
       const sameConcept = newConcept === matchedConcept && newConcept.length > 0;
@@ -312,14 +379,86 @@ export async function performWrite(
     }
   }
 
+  // -- Correction by intent, not by id (2026-10-19) --
+  // The MWA evaluation probe wrote "now departs 8:40" as an ordinary observation
+  // under a new concept: novelty 0.10, so it was stored at confidence 0.25 and
+  // ranked BELOW the stale "10:15". The writer knew it was a correction; it did
+  // not know the old id, and the only in-band way to say so (eventType surprise
+  // on the SAME concept, R3 above) is undocumented and needs the exact concept.
+  // `correction: true` names the intent. The target is the novelty match — the
+  // closest memory in content — when it is close enough to be the same fact;
+  // a superseded match is followed to its superseder. Below the floor nothing
+  // is replaced and the caller is told, because superseding a stranger would
+  // retire a true fact.
+  let correctionOf: WriteResult['correctionOf'];
+  if (!result && input.correction && !input.supersedes) {
+    correctionOf = null;
+    let target: Engram | null = noveltyResult.matchedEngramId
+      ? await store.getEngram(noveltyResult.matchedEngramId)
+      : null;
+    if (target?.supersededBy) target = await store.getEngram(target.supersededBy);
+    const closeEnough = noveltyResult.matchScore >= CORRECTION_MIN_MATCH;
+    if (target && closeEnough && target.agentId === input.agentId && mergeBlockedByTrust(input.tags, target.tags)) {
+      trustBlocked = { matchedId: target.id, writeTrust: trustTier(input.tags), matchedTrust: trustTier(target.tags) };
+    }
+    if (target && closeEnough && target.agentId === input.agentId && !trustBlocked
+        && !target.retracted && target.stage !== 'archived' && !target.supersededBy) {
+      const correctionSalience: SalienceResult = {
+        ...salience,
+        disposition: 'active' as const,
+        reasonCodes: [...salience.reasonCodes, 'correction:override-active'],
+      };
+      result = await createNewEngram(engines, {
+        ...input,
+        // The replacement must not stand weaker than what it replaces.
+        confidence: Math.max(input.confidence ?? 0, target.confidence),
+      }, correctionSalience, noveltyResult, {
+        effectiveEventType,
+        effectiveMemoryClass,
+        supersedesId: target.id,
+      }, prewriteEmbedding);
+      correctionOf = { id: target.id, concept: target.concept, matchScore: noveltyResult.matchScore };
+    }
+  }
+
   // -- Default: create new engram (if no reinforce/supersede branch fired) --
   if (!result) {
-    result = await createNewEngram(engines, input, salience, noveltyResult, {
+    // An explicit `supersedes` names the target, but naming it does not make the
+    // write trustworthy: an untrusted write must not retire a trusted memory by id.
+    if (input.supersedes) {
+      const named = await store.getEngram(input.supersedes);
+      if (named && mergeBlockedByTrust(input.tags, named.tags)) {
+        trustBlocked = { matchedId: named.id, writeTrust: trustTier(input.tags), matchedTrust: trustTier(named.tags) };
+        input = { ...input, supersedes: undefined };
+      }
+    }
+    // A correction of a near-duplicate has low novelty BY CONSTRUCTION: the replacement
+    // says almost what the engram it replaces said. Left on its own salience it lands at
+    // `discard` (confidence 0.25, tagged `low-salience`, below HEALTHY_CONFIDENCE_FLOOR)
+    // or at `staging` — while the supersession side-effect fires regardless. The old
+    // engram would be retired and its replacement too weak to stand in for it, so the
+    // fact leaves recall altogether: strictly worse than dropping the argument. R3 above
+    // already forces `active` for precisely this reason; an explicit `supersedes` is the
+    // same correction intent, stated by the caller instead of inferred from eventType.
+    const supersedeSalience: SalienceResult = input.supersedes
+      ? {
+          ...salience,
+          disposition: 'active' as const,
+          reasonCodes: [...salience.reasonCodes, 'supersede:override-active'],
+        }
+      : salience;
+    result = await createNewEngram(engines, input, supersedeSalience, noveltyResult, {
       effectiveEventType,
       effectiveMemoryClass,
       supersedesId: input.supersedes,
     }, prewriteEmbedding);
   }
+  // A correction always reports what it did, including "nothing" (null).
+  if (input.correction && !input.supersedes && result) result.correctionOf = correctionOf ?? null;
+  if (trustBlocked && result) {
+    result.trustBlocked = trustBlocked;
+    if (result.salience) result.salience = { ...result.salience, reasonCodes: [...result.salience.reasonCodes, 'trust:no-merge'] };
+  }
   } catch (e) {
     const es = `${(e as { code?: unknown })?.code ?? ''} ${(e as Error)?.message ?? ''}`;
     busyHit = /busy/i.test(es);

package/src/engine/activation.ts

@@ -59,6 +59,8 @@ import type {
 } from '../types/index.js';
 import type { IEngramStore as EngramStore } from '../storage/store.js';
 import { reorderByReranker, rerank2Enabled, rerank2WindowSize } from '../core/rerank2.js';
+import { validityState } from '../core/validity.js';
+import { detectConflicts } from '../core/conflicts.js';
 import { buildRerankPassage, rerankTruncation, rerankWindowMode } from '../core/rerank-window.js';
 import { parseTemporal, temporalEnabled, temporalBoost, type TemporalMatch } from '../core/temporal-query.js';
 import { aliasTermsFor } from '../core/alias-map.js';
@@ -1137,11 +1139,17 @@ export class ActivationEngine {
       }
     }
 
-    // Phase 8c: Supersession penalty — superseded memories are deprioritized.
-    // They aren't wrong (that's retraction), just outdated.
+    // Phase 8c: Stale penalty — superseded memories, and (since 2026-10-19)
+    // memories outside their valid_from/valid_to window, are deprioritized.
+    // They aren't wrong (that's retraction), just outdated or not yet true.
+    // The factor is also recorded on phaseScores so Phase 9b's re-sort by
+    // reranker score honours it — without that, rerank2 put a superseded
+    // memory above its successor (see src/core/rerank2.ts).
+    const validityNow = query.asOf ?? Date.now();
     for (const item of rerankPool) {
-      if (item.engram.supersededBy) {
-        item.score *= 0.15; // Severe down-rank — successor should dominate
+      if (item.engram.supersededBy || validityState(item.engram, validityNow) !== 'current') {
+        item.score *= 0.15; // Severe down-rank — the current version should dominate
+        item.phaseScores.stalePenalty = 0.15;
       }
     }
 
@@ -1306,6 +1314,21 @@ export class ActivationEngine {
         };
       });
 
+    // Conflict surfacing over the returned set (2026-10-19): two versions of
+    // one fact used to come back as two undated lines with nothing to say they
+    // disagreed. Pairwise over `limit` results, so it is a handful of string
+    // comparisons; see src/core/conflicts.ts for the rule and its known limit.
+    if (results.length > 1) {
+      const marks = detectConflicts(results, validityNow);
+      results.forEach((r, i) => { if (marks[i].length > 0) r.conflictsWith = marks[i]; });
+      // The marks do NOT reorder results. Measured 2026-10-19: moving the
+      // newest of a marked pair ahead cost identifier s@1 93.0% -> 74.7% with
+      // s@5 unchanged, because on a real store the detector also marks related
+      // memories that differ in a ticket id or a date — a cue to check the
+      // source, not a verdict on rank. A harness that wants newest-first among
+      // marked results can apply conflicts.ts `newestFirstAmongConflicts` itself.
+    }
+
     const activatedIds = results.map(r => r.engram.id);
 
     // Side effects: touch, co-activate, defer Hebbian to validation gate (skip for internal/system calls)