@remnic/core 9.51.0 → 9.52.0

package/src/orchestration/dependency-propagation-queue-state.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+
+import type { MemoryFile } from "../types.js";
+import { isRecord } from "../store-contract.js";
+import type { PropagationEvent } from "./dependency-propagation.js";
+import type {
+  DependencyPropagationJob,
+  DependencyPropagationJobStatus,
+} from "./dependency-propagation-delivery.js";
+
+export const JOB_STATES: readonly DependencyPropagationJobStatus[] = [
+  "prepared",
+  "ready",
+  "leased",
+  "retryable",
+  "completed",
+  "dead_letter",
+  "canceled",
+];
+
+const CAUSES: Record<PropagationEvent["cause"], true> = {
+  contradiction: true,
+  temporal_supersession: true,
+  consolidation_invalidate: true,
+  consolidation_merge: true,
+};
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function isPropagationEvent(value: unknown): value is PropagationEvent {
+  if (!isRecord(value) || !isRecord(value.oldMemory)) return false;
+  const oldMemory = value.oldMemory;
+  if (!isRecord(oldMemory.frontmatter)) return false;
+  const frontmatter = oldMemory.frontmatter;
+  if (typeof oldMemory.content !== "string" || typeof frontmatter.id !== "string") return false;
+  if (
+    !(value.replacementId === null || typeof value.replacementId === "string") ||
+    !(value.replacementContent === null || typeof value.replacementContent === "string") ||
+    typeof value.namespaceScope !== "string" ||
+    value.namespaceScope.length === 0 ||
+    typeof value.cause !== "string" ||
+    !Object.hasOwn(CAUSES, value.cause)
+  ) {
+    return false;
+  }
+  const temporalMutation = value.temporalMutation;
+  if (
+    temporalMutation !== undefined &&
+    (!isRecord(temporalMutation) ||
+      typeof temporalMutation.supersededAt !== "string" ||
+      (temporalMutation.invalidAt !== undefined && typeof temporalMutation.invalidAt !== "string") ||
+      !Array.isArray(temporalMutation.matchedKeys) ||
+      temporalMutation.matchedKeys.some((key) => typeof key !== "string"))
+  ) {
+    return false;
+  }
+  if (frontmatter.links !== undefined) {
+    if (!Array.isArray(frontmatter.links)) return false;
+    for (const link of frontmatter.links) {
+      if (!isRecord(link) || typeof link.targetId !== "string" || typeof link.linkType !== "string") return false;
+    }
+  }
+  return true;
+}
+
+export function validateJob(
+  value: unknown,
+  expectedState?: DependencyPropagationJobStatus,
+): DependencyPropagationJob | null {
+  if (!isRecord(value)) return null;
+  const status = value.status;
+  const event = value.event;
+  const attempts = value.attempts;
+  const createdAt = value.createdAt;
+  const updatedAt = value.updatedAt;
+  if (
+    typeof value.jobId !== "string" ||
+    value.jobId.length === 0 ||
+    typeof value.namespace !== "string" ||
+    value.namespace.length === 0 ||
+    typeof value.sourceId !== "string" ||
+    value.sourceId.length === 0 ||
+    !isPropagationEvent(event) ||
+    value.jobId !== eventJobId(event) ||
+    value.namespace !== event.namespaceScope ||
+    value.sourceId !== event.oldMemory.frontmatter.id ||
+    typeof status !== "string" ||
+    !JOB_STATES.includes(status as DependencyPropagationJobStatus) ||
+    (expectedState !== undefined && status !== expectedState) ||
+    typeof attempts !== "number" ||
+    !Number.isInteger(attempts) ||
+    attempts < 0 ||
+    !isFiniteNumber(createdAt) ||
+    !isFiniteNumber(updatedAt)
+  ) {
+    return null;
+  }
+  const revision = value.revision === undefined ? 0 : value.revision;
+  if (typeof revision !== "number" || !Number.isInteger(revision) || revision < 0) return null;
+  const reservationIdsValue = value.reservationIds;
+  if (!Array.isArray(reservationIdsValue)) return null;
+  const reservationIds = reservationIdsValue as unknown[];
+  if (
+    reservationIds.some(
+      (reservationId) => typeof reservationId !== "string" || reservationId.trim().length === 0,
+    ) || new Set(reservationIds).size !== reservationIds.length
+  ) {
+    return null;
+  }
+  const reservations = value.reservations;
+  if (
+    typeof reservations !== "number" ||
+    !Number.isInteger(reservations) ||
+    reservations < 0 ||
+    reservations !== reservationIds.length
+  ) {
+    return null;
+  }
+  const nextAttemptAt = value.nextAttemptAt;
+  const leaseOwner = value.leaseOwner;
+  const leaseExpiresAt = value.leaseExpiresAt;
+  const lastError = value.lastError;
+  const preparedReplacementFingerprint = value.preparedReplacementFingerprint;
+  if (nextAttemptAt !== undefined && !isFiniteNumber(nextAttemptAt)) return null;
+  if (leaseOwner !== undefined && typeof leaseOwner !== "string") return null;
+  if (leaseExpiresAt !== undefined && !isFiniteNumber(leaseExpiresAt)) return null;
+  if (lastError !== undefined && typeof lastError !== "string") return null;
+  if (
+    preparedReplacementFingerprint !== undefined &&
+    (typeof preparedReplacementFingerprint !== "string" || preparedReplacementFingerprint.length === 0)
+  ) {
+    return null;
+  }
+  if (status === "retryable" && nextAttemptAt === undefined) return null;
+  if (status === "leased" && (typeof leaseOwner !== "string" || leaseExpiresAt === undefined)) return null;
+  return {
+    jobId: value.jobId as string,
+    namespace: value.namespace as string,
+    sourceId: value.sourceId as string,
+    event,
+    status: status as DependencyPropagationJobStatus,
+    attempts,
+    createdAt,
+    updatedAt,
+    reservations,
+    reservationIds: [...(reservationIds as string[])],
+    revision,
+    ...(nextAttemptAt === undefined ? {} : { nextAttemptAt: nextAttemptAt as number }),
+    ...(leaseOwner === undefined ? {} : { leaseOwner: leaseOwner as string }),
+    ...(leaseExpiresAt === undefined ? {} : { leaseExpiresAt: leaseExpiresAt as number }),
+    ...(lastError === undefined ? {} : { lastError: lastError as string }),
+    ...(preparedReplacementFingerprint === undefined
+      ? {}
+      : { preparedReplacementFingerprint: preparedReplacementFingerprint as string }),
+  };
+}
+export function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  if (isRecord(value)) {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(value).sort()) {
+      if (value[key] === undefined) continue;
+      result[key] = canonicalize(value[key]);
+    }
+    return result;
+  }
+  return value === undefined ? null : value;
+}
+
+export function compareByteStable(left: string, right: string): number {
+  return Buffer.from(left, "utf8").compare(Buffer.from(right, "utf8"));
+}
+
+export function canonicalEvent(event: PropagationEvent): PropagationEvent {
+  return canonicalize(event) as PropagationEvent;
+}
+
+export function stableLinks(links: unknown): unknown {
+  if (!Array.isArray(links)) return links;
+  return [...links].sort((left, right) => {
+    const leftKey = JSON.stringify(canonicalize(left));
+    const rightKey = JSON.stringify(canonicalize(right));
+    return compareByteStable(leftKey, rightKey);
+  });
+}
+
+export function matchesPreparedSource(
+  current: MemoryFile,
+  prepared: Pick<MemoryFile, "content" | "frontmatter">,
+): boolean {
+  const { accessCount: _currentAccessCount, lastAccessed: _currentLastAccessed, ...currentSemantic } =
+    current.frontmatter;
+  const { accessCount: _preparedAccessCount, lastAccessed: _preparedLastAccessed, ...preparedSemantic } =
+    prepared.frontmatter;
+  const normalizedCurrent = { ...currentSemantic, links: stableLinks(currentSemantic.links) };
+  const normalizedPrepared = { ...preparedSemantic, links: stableLinks(preparedSemantic.links) };
+  return (
+    current.content === prepared.content &&
+    JSON.stringify(canonicalize(normalizedCurrent)) === JSON.stringify(canonicalize(normalizedPrepared))
+  );
+}
+
+export function eventJobId(event: PropagationEvent): string {
+  const { accessCount: _accessCount, lastAccessed: _lastAccessed, links, ...semanticFrontmatter } =
+    event.oldMemory.frontmatter;
+  const semanticEvent = {
+    ...event,
+    oldMemory: {
+      ...event.oldMemory,
+      frontmatter: { ...semanticFrontmatter, links: stableLinks(links) },
+    },
+  };
+  return createHash("sha256").update(JSON.stringify(canonicalize(semanticEvent))).digest("hex");
+}
+
+export function isNotFound(error: unknown): boolean {
+  return isRecord(error) && error.code === "ENOENT";
+}

package/src/orchestration/dependency-propagation-recovery-replay.ts

@@ -0,0 +1,237 @@
+/**
+ * Recovery primary-mutation replay for durable dependency propagation.
+ *
+ * Extracted from the delivery module so the recovery concern — resolving a
+ * memory across hot/cold/archived stores and replaying the primary mutation
+ * (supersede / invalidate / temporal) that a durable job represents — lives in
+ * one cohesive place. These functions are stateless with respect to the
+ * delivery class: they operate on an injected storage handle plus pure helpers,
+ * so the delivery delegates here without wrapper indirection. The module
+ * imports only package-local, host-agnostic sources (no index backend).
+ */
+import { createHash } from "node:crypto";
+
+import { sanitizeMemoryContent } from "../sanitize.js";
+import type { MemoryFile } from "../types.js";
+import {
+  applyTemporalSupersessionPrimaryMutation,
+  type TemporalSupersessionStorage,
+} from "../temporal-supersession.js";
+import {
+  type DependencyPropagationStorage,
+  type PropagationEvent,
+} from "./dependency-propagation.js";
+import { canonicalize, matchesPreparedSource } from "./dependency-propagation-queue-state.js";
+
+/**
+ * Storage capabilities the recovery replay needs beyond the base
+ * {@link DependencyPropagationStorage}: cold/archived memory reads, committed
+ * invalidation bookkeeping, and the supersede/invalidate primitives.
+ */
+export type DependencyPropagationRecoveryStorage = DependencyPropagationStorage & {
+  readAllColdMemories?: () => Promise<MemoryFile[]>;
+  readArchivedMemories?: () => Promise<MemoryFile[]>;
+  hasCommittedInvalidation?: (memory: Pick<MemoryFile, "content" | "frontmatter">) => Promise<boolean>;
+  clearCommittedInvalidation?: (
+    memory: Pick<MemoryFile, "content" | "frontmatter">,
+  ) => Promise<void>;
+  invalidateMemory?: (
+    id: string,
+    snapshot?: Pick<MemoryFile, "content" | "frontmatter"> & Partial<Pick<MemoryFile, "path">>,
+    options?: { recordCommitProof?: boolean },
+  ) => Promise<boolean>;
+  updateMemoryIfUnchanged?: (
+    expected: MemoryFile,
+    content: string,
+    options?: {
+      supersedes?: string;
+      lineage?: string[];
+      actor?: string;
+      sourceConnector?: string;
+    },
+  ) => Promise<boolean>;
+};
+
+/**
+ * Content fingerprint captured at preparation time. Access-count /
+ * last-accessed bookkeeping is excluded so a replay can prove the survivor has
+ * not drifted.
+ */
+export function memoryFingerprint(memory: Pick<MemoryFile, "content" | "frontmatter">): string {
+  const { accessCount: _accessCount, lastAccessed: _lastAccessed, ...frontmatter } = memory.frontmatter;
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalize({ content: memory.content, frontmatter })))
+    .digest("hex");
+}
+
+/**
+ * Resolve a memory by id across hot, cold, and archived stores. Returns `null`
+ * when no source record survives anywhere — recovery then cannot replay.
+ */
+export async function findRecoverySource(
+  storage: DependencyPropagationRecoveryStorage,
+  sourceId: string,
+): Promise<MemoryFile | null> {
+  const hot = await storage.getMemoryById(sourceId);
+  if (hot?.frontmatter.id === sourceId) return hot;
+  if (storage.readAllColdMemories) {
+    const cold = await storage.readAllColdMemories();
+    const coldMatch = cold.find((memory) => memory.frontmatter.id === sourceId);
+    if (coldMatch) return coldMatch;
+  }
+  if (storage.readArchivedMemories) {
+    const archived = await storage.readArchivedMemories();
+    const archivedMatch = archived.find((memory) => memory.frontmatter.id === sourceId);
+    if (archivedMatch) return archivedMatch;
+  }
+  return null;
+}
+
+/**
+ * Refresh a propagation event's replacement content from the current store for
+ * replay. Returns the event unchanged when it has no replacement; returns
+ * `null` when a replacement was expected but is no longer resolvable.
+ */
+export async function readCurrentReplacementEvent(
+  storage: DependencyPropagationStorage,
+  event: PropagationEvent,
+): Promise<PropagationEvent | null> {
+  if (event.replacementId === null) return event;
+  const replacement = await findRecoverySource(
+    storage as DependencyPropagationRecoveryStorage,
+    event.replacementId,
+  );
+  if (!replacement) return null;
+  return {
+    ...event,
+    replacementContent: replacement.content,
+  };
+}
+
+/**
+ * Replay the primary mutation a durable job represents against the current
+ * store, by cause: temporal supersession, contradiction supersede,
+ * consolidation invalidate, or consolidation merge. Idempotent — returns
+ * `true` when the mutation is already applied or is applied now, `false` when
+ * the source/replacement no longer matches the prepared snapshot (so the caller
+ * keeps the job retryable instead of marking it complete).
+ */
+export async function replayPrimaryMutation(
+  sourceStorage: DependencyPropagationStorage,
+  event: PropagationEvent,
+  preparedReplacementFingerprint?: string,
+): Promise<boolean> {
+  const storage = sourceStorage as DependencyPropagationRecoveryStorage;
+  const source = await findRecoverySource(storage, event.oldMemory.frontmatter.id);
+  const primaryApplied =
+    source?.frontmatter.status === "superseded" &&
+    source.frontmatter.supersededBy === event.replacementId;
+
+  if (event.cause === "temporal_supersession") {
+    if (!event.replacementId || !event.temporalMutation || !source) return false;
+    const temporalPrimaryApplied =
+      primaryApplied &&
+      source.frontmatter.supersededAt === event.temporalMutation.supersededAt &&
+      (event.temporalMutation.invalidAt === undefined ||
+        source.frontmatter.invalid_at === event.temporalMutation.invalidAt);
+    if (!temporalPrimaryApplied) {
+      const replacement = await findRecoverySource(storage, event.replacementId);
+      if (
+        event.replacementContent === null ||
+        !replacement ||
+        replacement.frontmatter.id !== event.replacementId ||
+        replacement.content !== event.replacementContent
+      )
+        return false;
+      if (!matchesPreparedSource(source, event.oldMemory)) return false;
+    }
+    return await applyTemporalSupersessionPrimaryMutation({
+      storage: sourceStorage as unknown as TemporalSupersessionStorage,
+      oldMemory: source,
+      replacementId: event.replacementId,
+      mutation: event.temporalMutation,
+    });
+  }
+
+  if (event.cause === "contradiction") {
+    if (!event.replacementId || !source) return false;
+    if (primaryApplied) return true;
+    const replacement = await findRecoverySource(storage, event.replacementId);
+    if (
+      event.replacementContent === null ||
+      !replacement ||
+      replacement.frontmatter.id !== event.replacementId ||
+      replacement.content !== event.replacementContent
+    )
+      return false;
+    if (!matchesPreparedSource(source, event.oldMemory)) return false;
+    return await storage.supersedeMemory(
+      event.oldMemory.frontmatter.id,
+      event.replacementId,
+      `dependency_propagation:${event.cause}`,
+      undefined,
+      { requireActive: true, acceptExactReplay: true, expectedSnapshot: source },
+    );
+  }
+
+  if (event.cause === "consolidation_invalidate") {
+    if (!source) {
+      return storage.hasCommittedInvalidation
+        ? await storage.hasCommittedInvalidation(event.oldMemory)
+        : false;
+    }
+    if (!storage.invalidateMemory || !matchesPreparedSource(source, event.oldMemory)) return false;
+    return await storage.invalidateMemory(source.frontmatter.id, source, {
+      recordCommitProof: true,
+    });
+  }
+
+  if (
+    !event.replacementId ||
+    event.replacementContent === null ||
+    !storage.updateMemoryIfUnchanged
+  ) {
+    return false;
+  }
+  const replacement = await findRecoverySource(storage, event.replacementId);
+  const persistedReplacementContent = sanitizeMemoryContent(event.replacementContent).text;
+  if (
+    replacement &&
+    replacement.frontmatter.supersedes === event.oldMemory.frontmatter.id &&
+    replacement.content !== persistedReplacementContent
+  ) {
+    return false;
+  }
+  const mergeAlreadyApplied =
+    replacement !== null &&
+    replacement.frontmatter.supersedes === event.oldMemory.frontmatter.id &&
+    replacement.content === persistedReplacementContent;
+  if (!source) {
+    if (!storage.hasCommittedInvalidation) return false;
+    return await storage.hasCommittedInvalidation(event.oldMemory);
+  }
+  if (
+    preparedReplacementFingerprint &&
+    source &&
+    !mergeAlreadyApplied &&
+    (!replacement || memoryFingerprint(replacement) !== preparedReplacementFingerprint)
+  ) {
+    return false;
+  }
+  if (!replacement || !matchesPreparedSource(source, event.oldMemory)) return false;
+  if (!mergeAlreadyApplied) {
+    const updated = await storage.updateMemoryIfUnchanged(
+      replacement,
+      event.replacementContent,
+      {
+        supersedes: event.oldMemory.frontmatter.id,
+        lineage: [event.replacementId, event.oldMemory.frontmatter.id],
+      },
+    );
+    if (!updated) return false;
+  }
+  if (!storage.invalidateMemory) return false;
+  return await storage.invalidateMemory(source.frontmatter.id, source, {
+    recordCommitProof: true,
+  });
+}

package/src/orchestration/dependency-propagation-replay-reconciliation.ts

@@ -0,0 +1,73 @@
+/**
+ * Replay reconciliation for dependency-propagation recovery.
+ *
+ * Reconciles the index effects — reindex the survivor, deindex the superseded
+ * set — of a replayed consolidation merge so a recovery pass matches what a
+ * normal consolidation MERGE/INVALIDATE performs inline. Host-agnostic: it
+ * imports no index backend and never references the orchestrator. The namespace
+ * storage lookup, survivor reindex, embedding deindex, and query-aware-indexing
+ * gate all flow through core APIs plus the injected
+ * {@link DependencyPropagationReplayHost}. Cause-gating mirrors consolidation
+ * exactly: reindex runs only for a consolidation_merge survivor; deindex runs
+ * for consolidation_merge and consolidation_invalidate superseded memories,
+ * dropping embedding visibility first then the temporal index entry. Any
+ * rejection propagates so the delivery keeps recovery retryable rather than
+ * marking the job safely complete.
+ */
+import { deindexMemoriesBatchAsync } from "../temporal-index.js";
+import { resolveIndexingCapabilities } from "../capabilities.js";
+import type { StorageManager } from "../storage.js";
+import type { PluginConfig } from "../types.js";
+import type { DependencyPropagationReplayReconciliationPort } from "./dependency-propagation-delivery.js";
+
+/**
+ * Narrow host port: the index primitives a recovery replay needs. The host
+ * (orchestrator) supplies them; this module owns the cause-gating and
+ * deindex/reindex ordering and imports no index backend of its own.
+ */
+export interface DependencyPropagationReplayHost {
+  /** Resolve the storage owning a propagation event's namespace scope. */
+  getStorage(namespace: string): Promise<StorageManager>;
+  /** Reindex/refresh a still-active survivor's index visibility. */
+  indexPersistedMemory(storage: StorageManager, memoryId: string): Promise<void>;
+  /** Remove a superseded memory's stale embedding index entry. */
+  removeFromIndex(memoryId: string): Promise<void>;
+  /** Host config; read for the query-aware-indexing gate. */
+  readonly config: PluginConfig;
+}
+
+/**
+ * Build the replay-reconciliation port bound to a host's index primitives. The
+ * returned port is handed to {@link DependencyPropagationDelivery} as
+ * `replayReconciliation`; it is inert until the delivery replays a job.
+ */
+export function createDependencyPropagationReplayReconciliation(
+  host: DependencyPropagationReplayHost,
+): DependencyPropagationReplayReconciliationPort {
+  return {
+    reindex: async (event, survivorId) => {
+      if (event.cause !== "consolidation_merge") return;
+      const storage = await host.getStorage(event.namespaceScope);
+      await host.indexPersistedMemory(storage, survivorId);
+    },
+    deindex: async (event, memoryIds) => {
+      if (
+        event.cause !== "consolidation_merge" &&
+        event.cause !== "consolidation_invalidate"
+      ) {
+        return;
+      }
+      await Promise.all(
+        memoryIds.map((memoryId) => host.removeFromIndex(memoryId)),
+      );
+      if (!resolveIndexingCapabilities(host.config).queryAwareIndexing) return;
+      if (!event.oldMemory.path || !event.oldMemory.frontmatter.created) return;
+      const storage = await host.getStorage(event.namespaceScope);
+      await deindexMemoriesBatchAsync(storage.dir, [{
+        path: event.oldMemory.path,
+        createdAt: event.oldMemory.frontmatter.created,
+        tags: event.oldMemory.frontmatter.tags ?? [],
+      }]);
+    },
+  };
+}