@remnic/core 9.27.0 → 9.28.0

package/src/replica-peers-config.ts

@@ -0,0 +1,250 @@
+/**
+ * `replicaPeers` config surface (issue #2149) — types + parser.
+ *
+ * Deliberately split out of replica-divergence.ts as a LIGHT module: it imports
+ * no heavy modules (no corpus-watermark, no access-token-capabilities). PluginConfig
+ * carries `replicaPeers: ReplicaPeersConfig`, so types.ts imports ReplicaPeersConfig
+ * from HERE. If that type instead lived in replica-divergence.ts (which pulls in the
+ * corpus census graph), then types.ts -> replica-divergence.ts -> corpus-watermark.ts
+ * -> types.ts would form a heavy import cycle that rollup-plugin-dts re-expands across
+ * every PluginConfig-inlining entry, OOMing the default-heap DTS worker (the issue
+ * #1562 heap cliff). Keeping the config surface corpus-free severs that cycle.
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { isAgentAccessSecretRef } from "./resolve-auth-token.js";
+import type { AgentAccessAuthToken } from "./types.js";
+
+const DEFAULT_POLL_INTERVAL_MS = 300_000; // 5 min
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_FILE_COUNT_DELTA = 100;
+const DEFAULT_MAX_WATERMARK_AGE_DELTA_MS = 900_000; // 15 min
+/** Node clamps a `setTimeout`/`AbortSignal.timeout` delay above 2^31-1 ms to 1ms,
+ *  which would make `withDeadline` fire immediately and mark every peer unreachable. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+export interface ReplicaPeerConfig {
+  /** Base URL of the peer's agent-access HTTP server (http/https). */
+  url: string;
+  /**
+   * Bearer token for the peer's authenticated `/health`. A literal string
+   * (env-expanded) or an unresolved SecretRef preserved verbatim and resolved
+   * at poll time — mirrors `agentAccessHttp.authToken` exactly.
+   */
+  token?: AgentAccessAuthToken;
+}
+
+export interface ReplicaPeersConfig {
+  /** Master gate. Default false — a daemon with no peers behaves exactly as before. */
+  enabled: boolean;
+  /** Peers to poll. Default []. */
+  peers: ReplicaPeerConfig[];
+  /** How often a peer is re-polled (SWR TTL), ms. Default 5 min. */
+  pollIntervalMs: number;
+  /** Per-peer request timeout, ms. Default 10s. */
+  requestTimeoutMs: number;
+  /** File-count delta (per namespace) beyond which a peer is flagged diverged. Default 100. */
+  maxFileCountDelta: number;
+  /** Newest-write timestamp gap (per namespace) beyond which a peer is flagged diverged, ms. Default 15 min. */
+  maxWatermarkAgeDeltaMs: number;
+}
+
+/**
+ * Expand `${ENV_VAR}` placeholders in a config string, matching config.ts's
+ * `resolveEnvVars` semantics (throw on unset var / malformed placeholder).
+ * Inlined rather than imported because config.ts imports THIS module for
+ * `parseReplicaPeersConfig`, so importing back would be circular — the same
+ * reason extraction-liveness.ts inlines its numeric validation.
+ */
+function expandEnvValue(value: string): string {
+  const resolved = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name: string) => {
+    const envValue = process.env[name];
+    if (envValue === undefined || envValue === "") {
+      throw new Error(`replicaPeers: environment variable ${name} is not set`);
+    }
+    return envValue;
+  });
+  // An UNTERMINATED `${NAME` matches neither the replacement regex nor the
+  // balanced leftover check below, so the literal typo would be sent as the
+  // bearer token and surface as a misleading `http_401` (round 8, codex P2).
+  const unterminated = resolved.match(/\$\{[^}]*$/);
+  if (unterminated) {
+    throw new Error(`replicaPeers: unterminated environment variable placeholder: ${unterminated[0]}`);
+  }
+  const remaining = resolved.match(/\$\{[^}]*\}/);
+  if (remaining) {
+    throw new Error(`replicaPeers: malformed environment variable placeholder: ${remaining[0]}`);
+  }
+  return resolved;
+}
+
+/**
+ * An absent key falls back to the default; any PRESENT value (including an
+ * explicit `null`) must coerce to an integer `>= min`, else THROW. A fractional
+ * or out-of-range value is rejected, never floored/reinterpreted (§1/§17/§39).
+ */
+function parseIntegerAtLeast(value: unknown, min: number, dflt: number, label: string, max = Number.MAX_SAFE_INTEGER): number {
+  if (value === undefined) return dflt;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced) || !Number.isInteger(coerced) || coerced < min) {
+    throw new Error(`${label} must be an integer greater than or equal to ${min}; got ${JSON.stringify(value)}`);
+  }
+  if (coerced > max) {
+    throw new Error(`${label} must be an integer no greater than ${max}; got ${JSON.stringify(value)}`);
+  }
+  return coerced;
+}
+
+function asRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseReplicaPeerToken(raw: unknown, index: number): AgentAccessAuthToken | undefined {
+  // Only an OMITTED token selects unauthenticated polling. A present `null` (round
+  // 4, codex P2) or an explicit empty/whitespace string (round 6, codex P2) is a
+  // present-but-invalid credential: silently dropping it polls without the token
+  // and surfaces a healthy peer as `http_401`, hiding the real config error.
+  if (raw === undefined) return undefined;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      throw new Error(`replicaPeers.peers[${index}].token must be a non-empty string or a SecretRef object`);
+    }
+    // Re-validate AFTER expansion: `${PEER_TOKEN}` pointing at a whitespace-only
+    // env value clears the check above, then resolveAgentAccessAuthToken
+    // normalizes it to undefined — silently downgrading an explicitly
+    // authenticated peer to an unauthenticated poll read as http_401 (round 9).
+    const expanded = expandEnvValue(trimmed);
+    if (expanded.trim().length === 0) {
+      throw new Error(`replicaPeers.peers[${index}].token expanded to an empty value`);
+    }
+    return expanded;
+  }
+  if (isAgentAccessSecretRef(raw)) return raw;
+  throw new Error(`replicaPeers.peers[${index}].token must be a string or a SecretRef object`);
+}
+
+function parseReplicaPeer(value: unknown, index: number): ReplicaPeerConfig {
+  const record = asRecord(value, `replicaPeers.peers[${index}]`);
+  if (typeof record.url !== "string" || record.url.trim().length === 0) {
+    throw new Error(`replicaPeers.peers[${index}].url must be a non-empty string`);
+  }
+  const url = expandEnvValue(record.url.trim());
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`replicaPeers.peers[${index}].url is not a valid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`replicaPeers.peers[${index}].url must be an http(s) URL (got ${parsed.protocol})`);
+  }
+  // The health path is appended to this base by string concatenation, so a query
+  // or fragment would corrupt the request URL (`https://h?x` + `/engram/v1/health`
+  // targets `/` with a mangled query; a fragment drops the path). Reject them at
+  // parse time — a peer URL must be a clean base (round 6, codex). Embedded
+  // credentials (`user:pass@host`) are rejected too: Node's fetch refuses to
+  // construct a request from a URL with credentials, so a healthy peer would
+  // falsely read as unreachable while redaction hid the config mistake.
+  if (parsed.search.length > 0 || parsed.hash.length > 0 || parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new Error(`replicaPeers.peers[${index}].url must be a clean base URL (no query, fragment, or embedded credentials)`);
+  }
+  const token = parseReplicaPeerToken(record.token, index);
+  // Store the CANONICAL form: `new URL()` tolerates surrounding whitespace that
+  // the raw string keeps, and the health path is appended by concatenation - so
+  // " https://peer /engram/v1/health" reads as an unreachable healthy peer.
+  const canonical = parsed.toString().replace(/\/+$/, "");
+  return token === undefined ? { url: canonical } : { url: canonical, token };
+}
+
+/**
+ * Parse the `replicaPeers` config block. Mirrors the nested-block validation of
+ * the other config-block parsers; coerces string booleans (§24) and rejects
+ * invalid numbers/urls/shapes (§1/§39).
+ */
+/**
+ * Strict boolean for the parse path: absent -> the default, present -> must be
+ * a recognized boolean token. A value like `1` must NOT silently reinterpret as
+ * `false`, which would leave monitoring off after an operator tried to enable
+ * it (round 3, codex P2). The lenient read-boundary resolver still defaults.
+ */
+function parseStrictBool(value: unknown, fallback: boolean, label: string): boolean {
+  if (value === undefined) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(`${label} must be a boolean (got ${JSON.stringify(value)})`);
+  }
+  return coerced;
+}
+
+export function parseReplicaPeersConfig(cfg: Record<string, unknown>): ReplicaPeersConfig {
+  const raw = cfg.replicaPeers;
+  if (raw !== undefined && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
+    throw new Error(`replicaPeers must be a plain object (got ${JSON.stringify(raw)})`);
+  }
+  const block = (raw ?? {}) as Record<string, unknown>;
+  if (block.peers !== undefined && !Array.isArray(block.peers)) {
+    throw new Error(`replicaPeers.peers must be an array (got ${JSON.stringify(block.peers)})`);
+  }
+  const peers = (block.peers ?? []).map(parseReplicaPeer);
+  return {
+    enabled: parseStrictBool(block.enabled, false, "replicaPeers.enabled"),
+    peers,
+    pollIntervalMs: parseIntegerAtLeast(block.pollIntervalMs, 1, DEFAULT_POLL_INTERVAL_MS, "replicaPeers.pollIntervalMs"),
+    requestTimeoutMs: parseIntegerAtLeast(block.requestTimeoutMs, 1, DEFAULT_REQUEST_TIMEOUT_MS, "replicaPeers.requestTimeoutMs", MAX_TIMER_DELAY_MS),
+    maxFileCountDelta: parseIntegerAtLeast(block.maxFileCountDelta, 0, DEFAULT_MAX_FILE_COUNT_DELTA, "replicaPeers.maxFileCountDelta"),
+    maxWatermarkAgeDeltaMs: parseIntegerAtLeast(
+      block.maxWatermarkAgeDeltaMs,
+      0,
+      DEFAULT_MAX_WATERMARK_AGE_DELTA_MS,
+      "replicaPeers.maxWatermarkAgeDeltaMs",
+    ),
+  };
+}
+
+/**
+ * READ-boundary resolver (mirrors `resolveExtractionLivenessConfig`, issue #2155).
+ * `parseConfig` always populates `replicaPeers`, but a host adapter, an older
+ * persisted config, or a hand-built `PluginConfig` can hand a READ surface
+ * (/health, doctor) an absent, partial, or loosely-typed block. Every replica
+ * surface must degrade to the documented default (disabled, no peers, no polling)
+ * rather than throw — `/health` must stay answerable. Unlike the strict parser, a
+ * present-but-invalid field falls back to its default here instead of throwing, and
+ * a malformed peer entry is dropped rather than aborting the whole block.
+ */
+export function resolveReplicaPeersConfig(block: unknown): ReplicaPeersConfig {
+  const record =
+    block !== null && typeof block === "object" && !Array.isArray(block) ? (block as Record<string, unknown>) : {};
+  return {
+    enabled: coerceBool(record.enabled) ?? false,
+    peers: resolveReplicaPeers(record.peers),
+    pollIntervalMs: resolveIntegerAtLeast(record.pollIntervalMs, 1, DEFAULT_POLL_INTERVAL_MS),
+    requestTimeoutMs: resolveIntegerAtLeast(record.requestTimeoutMs, 1, DEFAULT_REQUEST_TIMEOUT_MS, MAX_TIMER_DELAY_MS),
+    maxFileCountDelta: resolveIntegerAtLeast(record.maxFileCountDelta, 0, DEFAULT_MAX_FILE_COUNT_DELTA),
+    maxWatermarkAgeDeltaMs: resolveIntegerAtLeast(record.maxWatermarkAgeDeltaMs, 0, DEFAULT_MAX_WATERMARK_AGE_DELTA_MS),
+  };
+}
+
+/** Lenient sibling of {@link parseIntegerAtLeast}: a present-but-invalid value falls back, never throws. */
+function resolveIntegerAtLeast(value: unknown, min: number, dflt: number, max = Number.MAX_SAFE_INTEGER): number {
+  if (value === undefined) return dflt;
+  const coerced = coerceNumber(value);
+  return coerced !== undefined && Number.isFinite(coerced) && Number.isInteger(coerced) && coerced >= min && coerced <= max ? coerced : dflt;
+}
+
+/** Lenient peer list: a non-array is empty; a malformed entry is dropped, never thrown (read boundary). */
+function resolveReplicaPeers(value: unknown): ReplicaPeerConfig[] {
+  if (!Array.isArray(value)) return [];
+  const peers: ReplicaPeerConfig[] = [];
+  value.forEach((entry, index) => {
+    try {
+      peers.push(parseReplicaPeer(entry, index));
+    } catch {
+      // Read surfaces never throw on a bad peer — parseConfig is the enforcing boundary.
+    }
+  });
+  return peers;
+}

package/src/resolve-auth-token.ts

@@ -154,3 +154,41 @@ export function isAgentAccessSecretRef(value: unknown): value is SecretRef {
 export function clearAuthTokenSecretCache(): void {
   resolvedCache = new WeakMap<ResolveSecretRefFn, Map<string, string>>();
 }
+
+/**
+ * Resolve a host SecretRef resolver, preferring an explicitly supplied one over
+ * the lazy loader.
+ *
+ * Shared by every CLI command that authenticates with a SecretRef — `access
+ * serve` and `doctor` (replica peer tokens, issue #2149) — so the two cannot
+ * drift. Structurally typed rather than importing the CLI's options type, which
+ * would invert the dependency.
+ */
+export async function loadHostSecretRefResolver(options: {
+  resolveSecretRef?: ResolveSecretRefFn | null;
+  loadResolveSecretRef?: () =>
+    | Promise<ResolveSecretRefFn | null | undefined>
+    | ResolveSecretRefFn
+    | null
+    | undefined;
+}): Promise<ResolveSecretRefFn | null | undefined> {
+  if (options.resolveSecretRef) return options.resolveSecretRef;
+  if (!options.loadResolveSecretRef) return null;
+  try {
+    return await options.loadResolveSecretRef();
+  } catch {
+    // A host whose lazy loader throws means "no resolver available" — not
+    // "abort the caller". `doctor` must still run its unrelated checks and let
+    // the replica check report token_error per affected peer (round 9, codex).
+    return null;
+  }
+}
+
+/**
+ * Adapt a host's lazily-loaded SecretRef resolver into the eager
+ * `ResolveSecretRefFn` that `EngramAccessService` expects, so replica peer
+ * tokens resolve at poll time (issue #2149).
+ */
+export function hostSecretRefResolver(options: Parameters<typeof loadHostSecretRefResolver>[0]): ResolveSecretRefFn {
+  return (ref, context) => loadHostSecretRefResolver(options).then((resolve) => resolve?.(ref, context));
+}

package/src/storage/entity-canonical-id-migration-adapter.ts

@@ -0,0 +1,72 @@
+import type { EntityFile, MemoryFile } from "../types.js";
+import {
+  getFingerprint,
+  migrateLegacyEntityCanonicalIds,
+  validateRoots,
+  type EntityCanonicalIdMigrationDependencies,
+} from "./entity-canonical-id-migration.js";
+import {
+  rewriteProjectedEntityReferences,
+  rewriteProjectedMemoryEntityReference,
+} from "../memory-projection-mutations.js";
+
+export interface EntityCanonicalIdMigrationHost {
+  readonly baseDir: string;
+  readonly entitiesDir: string;
+  readonly stateDir: string;
+  readonly archiveDir: string;
+  normalizeEntityName(raw: string, type: string): string;
+  resolveEntityFilePath(id: string): string | null;
+  readStorageSecureFile(filePath: string): Promise<string>;
+  writeStorageSecureFile(filePath: string, content: string, forceEncrypt?: boolean): Promise<void>;
+  isEncryptedFileHeader(filePath: string): Promise<boolean>;
+  snapshotBeforeWrite(filePath: string, trigger: "write"): Promise<void>;
+  readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
+  readAllMemories(): Promise<MemoryFile[]>;
+  readAllColdMemories(): Promise<MemoryFile[]>;
+  readArchivedMemories(): Promise<MemoryFile[]>;
+  invalidateKnowledgeIndexCache(): void;
+  invalidateAllMemoriesCache(): void;
+  invalidateColdMemoriesCache(): void;
+  bumpMemoryStatusVersion(): void;
+  getCorpusScanVersion(): string;
+}
+
+export async function runLegacyEntityCanonicalIdMigration(
+  host: EntityCanonicalIdMigrationHost,
+  parseEntityFile: (content: string) => EntityFile,
+  serializeEntityFile: (entity: EntityFile) => string,
+  serializeMemoryWithEntityRef: (memory: MemoryFile, entityRef: string) => string,
+): Promise<string> {
+  const readMigrationFingerprint = () =>
+    getFingerprint(host.baseDir, host.entitiesDir, () => host.getCorpusScanVersion());
+  const completionFingerprint = await migrateLegacyEntityCanonicalIds({
+    stateDir: host.stateDir,
+    entitiesDir: host.entitiesDir,
+    normalizeEntityName: host.normalizeEntityName.bind(host),
+    resolveEntityFilePath: host.resolveEntityFilePath.bind(host),
+    readStorageSecureFile: host.readStorageSecureFile.bind(host),
+    writeStorageSecureFile: host.writeStorageSecureFile.bind(host),
+    isEncryptedStorageFile: host.isEncryptedFileHeader.bind(host),
+    snapshotBeforeWrite: host.snapshotBeforeWrite.bind(host),
+    parseEntityFile,
+    serializeEntityFile,
+    serializeMemoryWithEntityRef,
+    readMemoryByPath: host.readMemoryByPath.bind(host),
+    readAllMemories: host.readAllMemories.bind(host),
+    readAllColdMemories: host.readAllColdMemories.bind(host),
+    readArchivedMemories: host.readArchivedMemories.bind(host),
+    validateMemoryScanRoots: () =>
+      validateRoots(host.baseDir, host.entitiesDir, host.stateDir, host.archiveDir),
+    rewriteProjectedEntityReferences: (mappings) =>
+      rewriteProjectedEntityReferences(host.baseDir, mappings),
+    rewriteProjectedMemoryEntityReference: (memoryId, previousEntityRef, nextEntityRef) =>
+      rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef),
+    invalidateKnowledgeIndexCache: host.invalidateKnowledgeIndexCache.bind(host),
+    invalidateAllMemoriesCache: host.invalidateAllMemoriesCache.bind(host),
+    invalidateColdMemoriesCache: host.invalidateColdMemoriesCache.bind(host),
+    bumpMemoryStatusVersion: host.bumpMemoryStatusVersion.bind(host),
+    readMigrationFingerprint,
+  } satisfies EntityCanonicalIdMigrationDependencies);
+  return completionFingerprint ?? readMigrationFingerprint();
+}

package/src/storage/entity-canonical-id-migration-runner.ts

@@ -0,0 +1,68 @@
+export class EntityCanonicalIdMigrationRunner {
+  private inFlight: Promise<void> | null = null;
+  private directoriesInitialized = false;
+  private migrationComplete = false;
+  private completedFingerprint: string | null = null;
+
+  public constructor(
+    private readonly canRun: () => boolean,
+    private readonly runMigration: () => Promise<string | void>,
+    private readonly readFingerprint: () => Promise<string> = async () => "static",
+  ) {}
+
+  public async markDirectoriesInitialized(): Promise<void> {
+    this.directoriesInitialized = true;
+    await this.ensure();
+  }
+
+  public ensure(): Promise<void> {
+    if (!this.canRun()) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+    const migration = this.runOrReuse();
+    this.inFlight = migration;
+    void migration.then(
+      () => this.clearInFlight(migration),
+      () => this.clearInFlight(migration),
+    );
+    return migration;
+  }
+
+  public triggerAfterUnlock(): Promise<void> {
+    if (!this.directoriesInitialized) return Promise.resolve();
+    return this.ensure();
+  }
+
+  private async runOrReuse(): Promise<void> {
+    let fingerprintAtStart = await this.readFingerprint();
+    if (this.migrationComplete && fingerprintAtStart === this.completedFingerprint) return;
+
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const completionFingerprint = await this.runMigration();
+      const fingerprintAfterMigration = await this.readFingerprint();
+      const fingerprintAfterStabilityRead = await this.readFingerprint();
+      const returnedFingerprint =
+        typeof completionFingerprint === "string" ? completionFingerprint : fingerprintAfterMigration;
+      if (
+        returnedFingerprint === fingerprintAfterMigration
+        && fingerprintAfterMigration === fingerprintAfterStabilityRead
+        && (
+          typeof completionFingerprint === "string"
+          || fingerprintAfterMigration === fingerprintAtStart
+        )
+      ) {
+        this.migrationComplete = true;
+        this.completedFingerprint = fingerprintAfterStabilityRead;
+        return;
+      }
+      fingerprintAtStart = fingerprintAfterStabilityRead;
+    }
+
+    this.migrationComplete = false;
+    this.completedFingerprint = null;
+    throw new Error("Entity canonical-id migration fingerprint changed while migration was completing; retry migration.");
+  }
+
+  private clearInFlight(migration: Promise<void>): void {
+    if (this.inFlight === migration) this.inFlight = null;
+  }
+}