@graphorin/memory 0.6.1 → 0.7.0

package/src/conflict/locale-packs/en.ts

@@ -0,0 +1,142 @@
+/**
+ * Bundled English locale pack used by the multi-stage conflict
+ * resolution pipeline (DEC-117 / ADR-018 ext / RB-02). The patterns
+ * cover the common change signals personal-assistant scenarios surface
+ * on a daily basis: relocation, job change, preference flips,
+ * relationship transitions, and health updates.
+ *
+ * Operators supplying a different locale register their own pack via
+ * {@link defineLocalePack}. The framework ships English by default so
+ * the pipeline always has a working baseline.
+ *
+ * @packageDocumentation
+ */
+
+import { defineLocalePack, type LocalePack } from './types.js';
+
+/**
+ * The default English `LocalePack`. Frozen - share the singleton.
+ *
+ * @stable
+ */
+export const enLocalePack: LocalePack = defineLocalePack({
+  id: 'en',
+  supersedeMarkers: [
+    // Location.
+    { regex: /\bmoved (?:to|from)\b/i, kind: 'location', confidence: 0.9 },
+    {
+      regex: /\bnow (?:live|living|based|residing) (?:in|at)\b/i,
+      kind: 'location',
+      confidence: 0.9,
+    },
+    { regex: /\brelocated\b/i, kind: 'location', confidence: 0.85 },
+    { regex: /\bjust moved\b/i, kind: 'location', confidence: 0.85 },
+    { regex: /\bI live in\b/i, kind: 'location', confidence: 0.7 },
+
+    // Job.
+    { regex: /\b(?:got|started|landed)(?: a)?(?: new)? job\b/i, kind: 'job', confidence: 0.9 },
+    { regex: /\bgot promoted\b/i, kind: 'job', confidence: 0.9 },
+    { regex: /\bgot fired\b/i, kind: 'job', confidence: 0.9 },
+    { regex: /\b(?:I )?quit (?:my )?job\b/i, kind: 'job', confidence: 0.9 },
+    { regex: /\bnew employer\b/i, kind: 'job', confidence: 0.85 },
+    { regex: /\bnew job\b/i, kind: 'job', confidence: 0.8 },
+    { regex: /\bswitched (?:companies|jobs|employers)\b/i, kind: 'job', confidence: 0.9 },
+    { regex: /\bnow work(?:s|ing)? (?:at|for)\b/i, kind: 'job', confidence: 0.85 },
+
+    // Preference.
+    { regex: /\bswitched (?:from|to)\b/i, kind: 'preference', confidence: 0.85 },
+    { regex: /\bchanged my (?:mind|preference|opinion)\b/i, kind: 'preference', confidence: 0.85 },
+    {
+      regex: /\bused to (?:like|love|prefer|drink|eat|use)\b/i,
+      kind: 'preference',
+      confidence: 0.85,
+    },
+    { regex: /\bused to (?:live|work|study|play|travel)\b/i, kind: 'generic', confidence: 0.85 },
+    { regex: /\bI prefer\b/i, kind: 'preference', confidence: 0.6 },
+
+    // Relationship.
+    { regex: /\bgot (?:married|divorced|engaged)\b/i, kind: 'relationship', confidence: 0.9 },
+    { regex: /\bbroke up\b/i, kind: 'relationship', confidence: 0.85 },
+
+    // Health.
+    { regex: /\bdiagnosed (?:with|as)\b/i, kind: 'health', confidence: 0.85 },
+    { regex: /\brecovered from\b/i, kind: 'health', confidence: 0.85 },
+
+    // Generic.
+    { regex: /\bformerly\b/i, kind: 'generic', confidence: 0.7 },
+    { regex: /\bpreviously\b/i, kind: 'generic', confidence: 0.7 },
+    { regex: /\bused to be\b/i, kind: 'generic', confidence: 0.7 },
+    { regex: /\bis now\b/i, kind: 'generic', confidence: 0.7 },
+  ],
+  negationMarkers: [
+    { regex: /\bno longer\b/i, kind: 'preference', confidence: 0.85 },
+    { regex: /\bdoesn(?:'|\u2019)?t\b/i, confidence: 0.6 },
+    {
+      regex:
+        /\b(?:don(?:'|\u2019)?t|do not) (?:like|prefer|use|drink|eat|live|work|play|go|want)\b/i,
+      kind: 'preference',
+      confidence: 0.85,
+    },
+    { regex: /\bnever\b/i, confidence: 0.6 },
+    { regex: /\bnot anymore\b/i, kind: 'preference', confidence: 0.85 },
+    { regex: /\bisn(?:'|\u2019)?t\b/i, confidence: 0.6 },
+    {
+      regex: /\bnot (?:a fan|interested|willing|going|planning|in|into|looking) /i,
+      kind: 'preference',
+      confidence: 0.7,
+    },
+    { regex: /\b(?:is|are|am|was|were) not\b/i, confidence: 0.5 },
+  ],
+  predicateNormalisers: [
+    'is',
+    'are',
+    'am',
+    'was',
+    'were',
+    'be',
+    'been',
+    'being',
+    'has',
+    'have',
+    'had',
+    'do',
+    'does',
+    'did',
+    'lives',
+    'live',
+    'lived',
+    'living',
+    'works',
+    'work',
+    'worked',
+    'working',
+    'plays',
+    'play',
+    'played',
+    'playing',
+    'likes',
+    'like',
+    'liked',
+    'loves',
+    'love',
+    'loved',
+    'prefers',
+    'prefer',
+    'preferred',
+    'drinks',
+    'drink',
+    'drank',
+    'drunk',
+    'eats',
+    'eat',
+    'ate',
+    'eaten',
+    'in',
+    'at',
+    'on',
+    'with',
+    'for',
+    'to',
+  ],
+  subjectStopWords: ['a', 'an', 'the', 'my', 'your', 'his', 'her', 'their', 'our', 'this', 'that'],
+});

package/src/conflict/locale-packs/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of the locale-pack module. The bundled English pack
+ * (`enLocalePack`) is the default; additional locales are
+ * community-supplied via {@link defineLocalePack}.
+ *
+ * @packageDocumentation
+ */
+
+export { enLocalePack } from './en.js';
+export {
+  defineLocalePack,
+  evaluateMarkers,
+  type LocaleMatch,
+  type LocalePack,
+  type LocalePatternEntry,
+  type LocaleSupersedeKind,
+} from './types.js';

package/src/conflict/locale-packs/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Public types for the per-locale heuristic packs consumed by the
+ * Stage 3 (regex) and Stage 4 (subject/predicate) stages of the
+ * multi-stage conflict resolution pipeline (DEC-117 / ADR-018 ext).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Categorisation of a supersede marker. Surfaced on the audit row so
+ * downstream tooling can group conflicts by lifecycle event
+ * (relocation / job / preference / relationship / health / generic).
+ *
+ * @stable
+ */
+export type LocaleSupersedeKind =
+  | 'location'
+  | 'job'
+  | 'preference'
+  | 'relationship'
+  | 'health'
+  | 'generic';
+
+/**
+ * Single regex pattern bundled inside a `LocalePack`. The pipeline
+ * applies the regex to the fact body in case-insensitive mode unless
+ * the pattern was constructed with explicit flags.
+ *
+ * @stable
+ */
+export interface LocalePatternEntry {
+  readonly regex: RegExp;
+  readonly kind?: LocaleSupersedeKind;
+  /**
+   * Optional confidence ∈ `[0, 1]` surfaced through the audit row's
+   * `reason` field. Defaults to `0.8`.
+   */
+  readonly confidence?: number;
+}
+
+/**
+ * A `LocalePack` defines the regex sets Stage 3 and the predicate
+ * verb set Stage 4 use to evaluate a candidate fact pair against the
+ * existing conflicts.
+ *
+ * The bundled English pack (`enLocalePack`) covers the most common
+ * personal-assistant change signals (relocation / job change /
+ * preference flip / relationship / health). Additional locales are
+ * registered through {@link defineLocalePack}.
+ *
+ * @stable
+ */
+export interface LocalePack {
+  /** Stable lowercase identifier (`'en'`, `'fr'`, …). */
+  readonly id: string;
+  /** Patterns that explicitly mark the candidate as superseding the existing fact. */
+  readonly supersedeMarkers: ReadonlyArray<LocalePatternEntry>;
+  /** Patterns that negate the existing fact (treated as supersede in Stage 3). */
+  readonly negationMarkers: ReadonlyArray<LocalePatternEntry>;
+  /**
+   * Verbs (or verb particles) Stage 4 strips while normalising a
+   * predicate so e.g. `'lives in'` and `'living in'` collapse to the
+   * same key. Lowercase tokens.
+   */
+  readonly predicateNormalisers: ReadonlyArray<string>;
+  /** Tokens dropped from the subject before comparison (`'a'`, `'the'`, …). */
+  readonly subjectStopWords: ReadonlyArray<string>;
+}
+
+/**
+ * Outcome of a single locale-pack regex evaluation. Returned by
+ * `evaluateMarkers(...)` so the pipeline can propagate the matched
+ * marker into the audit row's `reason` field.
+ *
+ * @stable
+ */
+export interface LocaleMatch {
+  readonly matched: boolean;
+  readonly kind?: LocaleSupersedeKind;
+  readonly confidence?: number;
+  readonly excerpt?: string;
+}
+
+/**
+ * Builder used by application code that wants to ship a custom pack:
+ *
+ * ```ts
+ * const ru = defineLocalePack({
+ *   id: 'ru',
+ *   supersedeMarkers: [{ regex: /\bпереехал\b/iu, kind: 'location' }],
+ *   negationMarkers: [{ regex: /\bне\b/iu }],
+ *   predicateNormalisers: ['жив', 'жил', 'живёт'],
+ *   subjectStopWords: ['я', 'ты'],
+ * });
+ * ```
+ *
+ * The builder freezes every input so the pack can be safely reused
+ * across multiple `Memory` instances without accidental mutation.
+ *
+ * @stable
+ */
+export function defineLocalePack(input: LocalePack): LocalePack {
+  return Object.freeze({
+    id: input.id,
+    supersedeMarkers: Object.freeze([...input.supersedeMarkers]),
+    negationMarkers: Object.freeze([...input.negationMarkers]),
+    predicateNormalisers: Object.freeze([...input.predicateNormalisers]),
+    subjectStopWords: Object.freeze([...input.subjectStopWords]),
+  }) as LocalePack;
+}
+
+/**
+ * Apply a list of patterns to the supplied text and return the
+ * highest-confidence match (first match wins on ties). Surfaced for
+ * unit tests; the pipeline calls this internally.
+ *
+ * @stable
+ */
+export function evaluateMarkers(
+  text: string,
+  patterns: ReadonlyArray<LocalePatternEntry>,
+): LocaleMatch {
+  let best: LocaleMatch = { matched: false };
+  for (const pattern of patterns) {
+    const m = pattern.regex.exec(text);
+    if (m === null) continue;
+    const confidence = pattern.confidence ?? 0.8;
+    if (best.matched && (best.confidence ?? 0) >= confidence) continue;
+    const candidate: LocaleMatch = {
+      matched: true,
+      ...(pattern.kind !== undefined ? { kind: pattern.kind } : {}),
+      confidence,
+      excerpt: m[0],
+    };
+    best = candidate;
+  }
+  return best;
+}

package/src/conflict/pipeline.ts

@@ -0,0 +1,371 @@
+/**
+ * `runConflictPipeline` - orchestrator for the multi-stage conflict
+ * resolution pipeline shipped in `@graphorin/memory` Phase 10b
+ * (DEC-117 / ADR-018 ext / RB-02).
+ *
+ * @packageDocumentation
+ */
+
+import type { Fact, MemoryHit } from '@graphorin/core';
+import { withMemorySpan } from '../internal/spans.js';
+import { enLocalePack, type LocalePack } from './locale-packs/index.js';
+import { stage1ExactDedup } from './stages/stage1-exact-dedup.js';
+import { stage2EmbeddingThreeZone } from './stages/stage2-embedding-three-zone.js';
+import { stage3HeuristicRegex } from './stages/stage3-heuristic-regex.js';
+import { stage4SubjectPredicate } from './stages/stage4-subject-predicate.js';
+import { stage5DeferToDeep } from './stages/stage5-defer-to-deep.js';
+import {
+  type ConflictDecision,
+  type ConflictPipeline,
+  type ConflictPipelineDeps,
+  type ConflictPipelineOptions,
+  type ConflictStage,
+  type ConflictThresholds,
+  DEFAULT_CONFLICT_THRESHOLDS,
+  type StageContext,
+  type StageOutcome,
+} from './types.js';
+
+let bypassWarnedOnce = false;
+
+/**
+ * Reset the one-shot bypass-warning flag. Test-only helper - production
+ * callers never invoke this.
+ *
+ * @internal
+ */
+export function _resetBypassWarningForTesting(): void {
+  bypassWarnedOnce = false;
+}
+
+/**
+ * One-shot helper that mirrors RB-02 §8.1's `runConflictPipeline({...})`
+ * spec - convenient for callers that do not need to pre-build + cache
+ * the pipeline. Production wiring should still go through
+ * {@link createConflictPipeline} (`SemanticMemory` re-uses the cached
+ * instance per `Memory`).
+ *
+ * @stable
+ */
+export async function runConflictPipeline(args: {
+  readonly candidate: Fact;
+  readonly deps: ConflictPipelineDeps;
+  readonly options?: ConflictPipelineOptions;
+}): Promise<ConflictDecision> {
+  const pipeline = createConflictPipeline(args.options ?? {});
+  return pipeline.run(args.deps, args.candidate);
+}
+
+/**
+ * Returns a frozen pipeline handle wired with the supplied options.
+ *
+ * @stable
+ */
+export function createConflictPipeline(options: ConflictPipelineOptions = {}): ConflictPipeline {
+  const mode: 'on' | 'off' = options.mode ?? 'on';
+  const localePack: LocalePack = options.localePack ?? enLocalePack;
+  const thresholds: ConflictThresholds = Object.freeze({
+    hot: options.thresholds?.hot ?? DEFAULT_CONFLICT_THRESHOLDS.hot,
+    nearDup: options.thresholds?.nearDup ?? DEFAULT_CONFLICT_THRESHOLDS.nearDup,
+    cold: options.thresholds?.cold ?? DEFAULT_CONFLICT_THRESHOLDS.cold,
+  });
+  validateThresholds(thresholds);
+  const stage2TopK = options.stage2TopK ?? 5;
+  const now = options.now ?? ((): string => new Date().toISOString());
+
+  async function run(deps: ConflictPipelineDeps, candidate: Fact): Promise<ConflictDecision> {
+    if (mode === 'off') {
+      if (!bypassWarnedOnce) {
+        bypassWarnedOnce = true;
+        warnBypass();
+      }
+      return { kind: 'admit', stage: 'exact-dedup', reason: 'pipeline-mode-off' };
+    }
+
+    checkAbort(deps.signal);
+    const conflictStore = options.conflictStore ?? deps.store.conflicts;
+
+    return withMemorySpan(
+      deps.tracer,
+      'memory.conflict',
+      {
+        userId: candidate.userId,
+        ...(candidate.sessionId !== undefined ? { sessionId: candidate.sessionId } : {}),
+        ...(candidate.agentId !== undefined ? { agentId: candidate.agentId } : {}),
+      },
+      {
+        'memory.conflict.candidate_id': candidate.id,
+        'memory.conflict.locale_pack': localePack.id,
+      },
+      async (span) => {
+        const existing = await collectVectorCandidates(deps, candidate, stage2TopK);
+        const ctx: StageContext = {
+          candidate,
+          existing,
+          localePack,
+          thresholds,
+        };
+        const decision = await orchestrate(ctx);
+        await persistDecision(decision, candidate, conflictStore, now);
+        span.setAttributes({
+          'memory.conflict.stage': decision.stage,
+          'memory.conflict.decision': decision.kind,
+          'memory.conflict.candidate_count': existing.length,
+          ...(decision.kind === 'dedup' && decision.similarity !== undefined
+            ? { 'memory.conflict.similarity': decision.similarity }
+            : {}),
+          ...(decision.kind === 'pending' && decision.similarity !== undefined
+            ? { 'memory.conflict.similarity': decision.similarity }
+            : {}),
+          ...(decision.kind !== 'admit'
+            ? { 'memory.conflict.reason': decision.reason ?? 'unspecified' }
+            : decision.reason !== undefined
+              ? { 'memory.conflict.reason': decision.reason }
+              : {}),
+        });
+        return decision;
+      },
+    );
+  }
+
+  /**
+   * Visit the five stages in the order documented by RB-02 §8.1 and
+   * the conflict-resolution policy (DEC-117). Stage 1 short-circuits
+   * exact duplicates. Stage 2 always computes the zone but the
+   * orchestrator splits its decision in two halves: the HOT zone is
+   * the only zone that overrides Stage 3 / Stage 4 (semantic identity
+   * outranks any explicit user marker); every other zone runs Stages
+   * 3 and 4 first to give the heuristic markers a chance to supersede
+   * before falling back to Stage 2's default decision.
+   *
+   * Stage 3 is declared "orthogonal to Stage 2", which is why the
+   * heuristic stages run regardless of Stage 2's COLD / NEAR-DUP /
+   * CONFLICT-CHECK assignment as long as Stage 2 surfaced at least
+   * one candidate. The HOT-zone short-circuit preserves the dedup
+   * invariant for semantic identity.
+   */
+  async function orchestrate(ctx: StageContext): Promise<ConflictDecision> {
+    const stage1 = await stage1ExactDedup.evaluate(ctx);
+    if (stage1.kind !== 'continue') {
+      return mapOutcomeToDecision('exact-dedup', stage1, ctx.candidate);
+    }
+
+    const stage2 = await stage2EmbeddingThreeZone.evaluate(ctx);
+    if (stage2.kind === 'dedup' && stage2.reason === 'embedding-hot-zone') {
+      return mapOutcomeToDecision('embedding-three-zone', stage2, ctx.candidate);
+    }
+
+    if (ctx.existing.length > 0) {
+      const stage3 = await stage3HeuristicRegex.evaluate(ctx);
+      if (stage3.kind !== 'continue') {
+        return mapOutcomeToDecision('heuristic-regex', stage3, ctx.candidate);
+      }
+      const stage4 = await stage4SubjectPredicate.evaluate(ctx);
+      if (stage4.kind !== 'continue') {
+        return mapOutcomeToDecision('subject-predicate', stage4, ctx.candidate);
+      }
+    }
+
+    if (stage2.kind === 'dedup' || stage2.kind === 'admit') {
+      return mapOutcomeToDecision('embedding-three-zone', stage2, ctx.candidate);
+    }
+
+    const stage5 = await stage5DeferToDeep.evaluate(ctx);
+    return mapOutcomeToDecision('defer-to-deep', stage5, ctx.candidate);
+  }
+
+  return Object.freeze({
+    mode,
+    localePack,
+    thresholds,
+    run,
+  }) satisfies ConflictPipeline;
+}
+
+function mapOutcomeToDecision(
+  stage: ConflictStage,
+  outcome: StageOutcome,
+  candidate: Fact,
+): ConflictDecision {
+  switch (outcome.kind) {
+    case 'continue':
+      return { kind: 'admit', stage, reason: 'continue-fallthrough' };
+    case 'admit':
+      return {
+        kind: 'admit',
+        stage,
+        ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+      };
+    case 'dedup':
+      return {
+        kind: 'dedup',
+        stage,
+        existingId: outcome.existingId,
+        ...(outcome.similarity !== undefined ? { similarity: outcome.similarity } : {}),
+        ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+      };
+    case 'supersede':
+      return {
+        kind: 'supersede',
+        stage,
+        existingId: outcome.existingId,
+        reason: outcome.reason,
+      };
+    case 'pending':
+      return {
+        kind: 'pending',
+        stage,
+        candidateId: candidate.id,
+        conflictingIds: outcome.conflictingIds,
+        ...(outcome.similarity !== undefined ? { similarity: outcome.similarity } : {}),
+        ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+      };
+  }
+}
+
+async function persistDecision(
+  decision: ConflictDecision,
+  candidate: Fact,
+  conflictStore: ConflictPipelineDeps['store']['conflicts'],
+  now: () => string,
+): Promise<void> {
+  if (conflictStore === undefined) return;
+  const scope = {
+    userId: candidate.userId,
+    ...(candidate.sessionId !== undefined ? { sessionId: candidate.sessionId } : {}),
+    ...(candidate.agentId !== undefined ? { agentId: candidate.agentId } : {}),
+  };
+  const detectionZone = decisionToZone(decision);
+  const auditInput: Parameters<NonNullable<typeof conflictStore>['recordDecision']>[0] = {
+    scope,
+    candidateId: candidate.id,
+    decision: decision.kind,
+    stage: decision.stage,
+    ...(detectionZone !== undefined ? { detectionZone } : {}),
+    ...(decision.kind === 'dedup' && decision.existingId !== undefined
+      ? { existingId: decision.existingId }
+      : {}),
+    ...(decision.kind === 'supersede' ? { existingId: decision.existingId } : {}),
+    ...(decision.kind === 'dedup' && decision.similarity !== undefined
+      ? { similarity: decision.similarity }
+      : {}),
+    ...(decision.kind === 'pending' && decision.similarity !== undefined
+      ? { similarity: decision.similarity }
+      : {}),
+    ...(decision.kind !== 'admit' && decision.reason !== undefined
+      ? { reason: decision.reason }
+      : {}),
+    ...(decision.kind === 'admit' && decision.reason !== undefined
+      ? { reason: decision.reason }
+      : {}),
+  };
+  await conflictStore.recordDecision(auditInput);
+  if (decision.kind === 'pending') {
+    await conflictStore.enqueuePending({
+      scope,
+      factId: candidate.id,
+      candidateText: candidate.text,
+      stage: decision.stage,
+      conflictingIds: decision.conflictingIds,
+      ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+    });
+  }
+  void now;
+}
+
+function decisionToZone(decision: ConflictDecision): string | undefined {
+  switch (decision.kind) {
+    case 'admit':
+      if (decision.reason === 'embedding-cold-zone') return 'cold';
+      return undefined;
+    case 'dedup':
+      if (decision.reason === 'embedding-hot-zone') return 'hot';
+      if (decision.reason === 'embedding-near-dup-zone') return 'near-dup';
+      if (decision.reason === 'exact-hash-match') return 'exact';
+      if (decision.reason === 'subject-predicate-match-same-object') return 'subject-predicate';
+      return undefined;
+    case 'supersede':
+      if (decision.reason.startsWith('regex-supersede-marker')) return 'heuristic';
+      if (decision.reason.startsWith('regex-negation')) return 'heuristic';
+      if (decision.reason.startsWith('subject-predicate-match')) return 'subject-predicate';
+      return undefined;
+    case 'pending':
+      return 'conflict-check';
+  }
+}
+
+async function collectVectorCandidates(
+  deps: ConflictPipelineDeps,
+  candidate: Fact,
+  topK: number,
+): Promise<ReadonlyArray<MemoryHit<Fact>>> {
+  if (deps.embedder === null || deps.embedderId === null) return [];
+  const adapter = deps.store.semantic;
+  if (typeof adapter.searchVector !== 'function') return [];
+  checkAbort(deps.signal);
+  // PS-10: the candidate is compared against stored facts, which are embedded
+  // as `passage` - keep it in the same space for the asymmetric (E5) embedder.
+  const [vector] = await deps.embedder.embed([candidate.text], { taskType: 'passage' });
+  if (vector === undefined) return [];
+  checkAbort(deps.signal);
+  const scope = {
+    userId: candidate.userId,
+    ...(candidate.sessionId !== undefined ? { sessionId: candidate.sessionId } : {}),
+    ...(candidate.agentId !== undefined ? { agentId: candidate.agentId } : {}),
+  };
+  // Vector search may throw when the storage layer's vector extension
+  // is missing or mis-configured (e.g. `sqlite-vec` not loaded). Fall
+  // back to "no candidates" so the conflict pipeline degrades to the
+  // 10a straight-through write rather than blocking the agent loop.
+  // AbortError is re-raised so cancellation propagates up.
+  let hits: ReadonlyArray<MemoryHit<Fact>>;
+  try {
+    hits = await adapter.searchVector(scope, vector, deps.embedderId, topK);
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') throw err;
+    return [];
+  }
+  return [...hits].filter((hit) => hit.record.id !== candidate.id);
+}
+
+function validateThresholds(thresholds: ConflictThresholds): void {
+  if (
+    !(
+      thresholds.hot >= thresholds.nearDup &&
+      thresholds.nearDup >= thresholds.cold &&
+      thresholds.hot <= 1 &&
+      thresholds.cold >= 0
+    )
+  ) {
+    throw new TypeError(
+      `[graphorin/memory] invalid conflict thresholds: expected 0 <= cold <= nearDup <= hot <= 1, got ${JSON.stringify(thresholds)}.`,
+    );
+  }
+}
+
+/**
+ * Throw the canonical `AbortError` when the supplied signal is
+ * already aborted. Safe to call with `undefined`.
+ *
+ * @internal
+ */
+function checkAbort(signal: AbortSignal | undefined): void {
+  if (signal === undefined) return;
+  if (signal.aborted) {
+    if (typeof signal.throwIfAborted === 'function') {
+      signal.throwIfAborted();
+    }
+    throw new DOMException('The operation was aborted.', 'AbortError');
+  }
+}
+
+function warnBypass(): void {
+  // Use the structured logger once it lands (Phase 04 follow-up). For
+  // now, surface a one-shot console.warn so operators notice the
+  // regression risk per the Phase 10b spec ("WARN-once per process").
+  console.warn(
+    '[graphorin/memory] conflict pipeline disabled (mode: "off"). ' +
+      'Semantic writes fall back to a straight-through path - bi-temporal supersede / dedup ' +
+      'will not fire until you re-enable the pipeline.',
+  );
+}