@remnic/plugin-openclaw 1.0.10 → 1.0.12

package/dist/chunk-6IWEAUN6.js

@@ -0,0 +1,148 @@
+// ../remnic-core/src/secure-store/kdf.ts
+import { scryptSync, timingSafeEqual } from "crypto";
+import { createRequire } from "module";
+var requireArgon2 = createRequire(import.meta.url);
+var argon2Runtime;
+function loadArgon2Runtime() {
+  try {
+    argon2Runtime ??= requireArgon2("@node-rs/argon2");
+    return argon2Runtime;
+  } catch (cause) {
+    throw new Error(
+      "Argon2id KDF requires @node-rs/argon2 to be installed and loadable on this platform. Use scrypt compatibility mode for stores that must run without the Argon2 native binding.",
+      { cause }
+    );
+  }
+}
+var DEFAULT_SCRYPT_PARAMS = Object.freeze({
+  // 2^17. Hex-coding the literal would obscure the doubling chain.
+  N: 1 << 17,
+  r: 8,
+  p: 1,
+  keyLength: 32,
+  // 256 MiB ceiling — comfortably above the 128 MiB scrypt needs at N=2^17.
+  maxmem: 256 * 1024 * 1024
+});
+var DEFAULT_ARGON2ID_PARAMS = Object.freeze({
+  memoryKiB: 64 * 1024,
+  iterations: 3,
+  parallelism: 4,
+  keyLength: 32
+});
+var KDF_SALT_LENGTH = 16;
+var KDF_KEY_LENGTH = 32;
+function validateScryptParams(params) {
+  const { N, r, p, keyLength, maxmem } = params;
+  if (!Number.isInteger(N) || N < 2) {
+    throw new Error(`scrypt N must be an integer \u2265 2, got ${N}`);
+  }
+  if (N > 2 ** 30) {
+    throw new Error(`scrypt N is unreasonably large (max 2^30), got ${N}`);
+  }
+  if (!Number.isInteger(Math.log2(N))) {
+    throw new Error(`scrypt N must be a power of 2, got ${N}`);
+  }
+  if (!Number.isInteger(r) || r < 1) {
+    throw new Error(`scrypt r must be a positive integer, got ${r}`);
+  }
+  if (!Number.isInteger(p) || p < 1) {
+    throw new Error(`scrypt p must be a positive integer, got ${p}`);
+  }
+  if (!Number.isInteger(keyLength) || keyLength < 16) {
+    throw new Error(
+      `scrypt keyLength must be \u2265 16 (need 32 for AES-256), got ${keyLength}`
+    );
+  }
+  if (!Number.isInteger(maxmem) || maxmem < 1024) {
+    throw new Error(`scrypt maxmem must be a sane positive integer, got ${maxmem}`);
+  }
+}
+function validateArgon2idParams(params) {
+  const { memoryKiB, iterations, parallelism, keyLength } = params;
+  if (!Number.isInteger(memoryKiB) || memoryKiB < 8) {
+    throw new Error(`argon2id memoryKiB must be an integer \u2265 8, got ${memoryKiB}`);
+  }
+  if (!Number.isInteger(iterations) || iterations < 1) {
+    throw new Error(`argon2id iterations must be a positive integer, got ${iterations}`);
+  }
+  if (!Number.isInteger(parallelism) || parallelism < 1 || parallelism > 255) {
+    throw new Error(`argon2id parallelism must be an integer in [1, 255], got ${parallelism}`);
+  }
+  if (!Number.isInteger(keyLength) || keyLength !== KDF_KEY_LENGTH) {
+    throw new Error(
+      `argon2id keyLength must be ${KDF_KEY_LENGTH} (AES-256 requires a 32-byte key), got ${keyLength}`
+    );
+  }
+}
+function deriveKeyScrypt(passphrase, salt, params = DEFAULT_SCRYPT_PARAMS) {
+  if (typeof passphrase !== "string") {
+    throw new Error("passphrase must be a string");
+  }
+  if (passphrase.length === 0) {
+    throw new Error("passphrase must not be empty");
+  }
+  if (!(salt instanceof Uint8Array) || salt.length < 8) {
+    throw new Error(
+      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? "non-buffer"}`
+    );
+  }
+  validateScryptParams(params);
+  return scryptSync(passphrase, Buffer.from(salt), params.keyLength, {
+    N: params.N,
+    r: params.r,
+    p: params.p,
+    maxmem: params.maxmem
+  });
+}
+function deriveKeyArgon2id(passphrase, salt, params = DEFAULT_ARGON2ID_PARAMS) {
+  if (typeof passphrase !== "string") {
+    throw new Error("passphrase must be a string");
+  }
+  if (passphrase.length === 0) {
+    throw new Error("passphrase must not be empty");
+  }
+  if (!(salt instanceof Uint8Array) || salt.length < 8) {
+    throw new Error(
+      `salt must be a Uint8Array of at least 8 bytes, got ${salt?.length ?? "non-buffer"}`
+    );
+  }
+  validateArgon2idParams(params);
+  const { Algorithm, Version, hashRawSync } = loadArgon2Runtime();
+  return hashRawSync(passphrase, {
+    algorithm: Algorithm.Argon2id,
+    version: Version.V0x13,
+    memoryCost: params.memoryKiB,
+    timeCost: params.iterations,
+    parallelism: params.parallelism,
+    outputLen: params.keyLength,
+    salt
+  });
+}
+function deriveKey(algorithm, passphrase, salt, params) {
+  if (algorithm === "scrypt") {
+    return deriveKeyScrypt(passphrase, salt, params);
+  }
+  if (algorithm === "argon2id") {
+    return deriveKeyArgon2id(passphrase, salt, params);
+  }
+  throw new Error(`unknown KDF algorithm: ${algorithm}`);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+export {
+  DEFAULT_SCRYPT_PARAMS,
+  DEFAULT_ARGON2ID_PARAMS,
+  KDF_SALT_LENGTH,
+  KDF_KEY_LENGTH,
+  validateScryptParams,
+  validateArgon2idParams,
+  deriveKeyScrypt,
+  deriveKeyArgon2id,
+  deriveKey,
+  constantTimeEqual
+};

package/dist/{chunk-LN5UZQVG.js → chunk-6UFI73TJ.js}

@@ -1,14 +1,16 @@
+import {
+  countRecallTokenOverlap,
+  normalizeRecallTokens
+} from "./chunk-WPINX4MF.js";
 import {
   assertIsoRecordedAt,
   assertSafePathSegment,
   assertString,
-  countRecallTokenOverlap,
   isRecord,
-  normalizeRecallTokens,
   optionalString,
   optionalStringArray,
   validateStringRecord
-} from "./chunk-YHH3SXKD.js";
+} from "./chunk-3G7FAF6S.js";
 import {
   listJsonFiles,
   readJsonFile

package/dist/chunk-7OQEPGQF.js

@@ -0,0 +1,529 @@
+import {
+  clamp01,
+  computeLifecycleValueInputs,
+  daysSince
+} from "./chunk-4G2XCSD2.js";
+import {
+  assertIsoRecordedAt,
+  assertSafePathSegment,
+  assertString,
+  isRecord,
+  optionalStringArray,
+  recordStoreDay,
+  validateStringRecord
+} from "./chunk-3G7FAF6S.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-5LE4HTVL.js";
+
+// ../remnic-core/src/tier-routing.ts
+function computeTierValueScore(memory, now, signals) {
+  const fm = memory.frontmatter;
+  const inputs = computeLifecycleValueInputs(memory, now, signals);
+  const correctionBoost = fm.category === "correction" ? 0.08 : 0;
+  const confirmedBoost = fm.verificationState === "user_confirmed" ? 0.05 : 0;
+  const score = inputs.confidence * 0.24 + inputs.access * 0.26 + inputs.recency * 0.2 + inputs.importance * 0.2 + inputs.feedback * 0.1 + correctionBoost + confirmedBoost - inputs.disputedPenalty * 0.5;
+  return clamp01(score);
+}
+function decideTierTransition(memory, currentTier, policy, now, signals) {
+  const valueScore = computeTierValueScore(memory, now, signals);
+  if (!policy.enabled) {
+    return {
+      currentTier,
+      nextTier: currentTier,
+      valueScore,
+      changed: false,
+      reason: "tier_migration_disabled"
+    };
+  }
+  if (currentTier === "hot") {
+    const ageDays = daysSince(memory.frontmatter.updated ?? memory.frontmatter.created, now.getTime());
+    if (ageDays >= policy.demotionMinAgeDays && valueScore <= policy.demotionValueThreshold) {
+      return {
+        currentTier,
+        nextTier: "cold",
+        valueScore,
+        changed: true,
+        reason: "value_below_demotion_threshold"
+      };
+    }
+    return {
+      currentTier,
+      nextTier: currentTier,
+      valueScore,
+      changed: false,
+      reason: ageDays < policy.demotionMinAgeDays ? "demotion_min_age_not_met" : "value_above_demotion_threshold"
+    };
+  }
+  if (valueScore >= policy.promotionValueThreshold) {
+    return {
+      currentTier,
+      nextTier: "hot",
+      valueScore,
+      changed: true,
+      reason: "value_above_promotion_threshold"
+    };
+  }
+  return {
+    currentTier,
+    nextTier: currentTier,
+    valueScore,
+    changed: false,
+    reason: "value_below_promotion_threshold"
+  };
+}
+
+// ../remnic-core/src/utility-learner.ts
+import path2 from "path";
+import { mkdir as mkdir2, readFile, rename, writeFile as writeFile2 } from "fs/promises";
+
+// ../remnic-core/src/utility-telemetry.ts
+import path from "path";
+import { mkdir, writeFile } from "fs/promises";
+function resolveUtilityTelemetryDir(memoryDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path.join(memoryDir, "state", "utility-telemetry");
+}
+function assertUtilityScore(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error("utilityScore must be a finite number");
+  }
+  if (value < -1 || value > 1) {
+    throw new Error("utilityScore must be between -1 and 1");
+  }
+  return value;
+}
+function validateUtilityTelemetryEvent(raw) {
+  if (!isRecord(raw)) throw new Error("utility telemetry event must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  const source = assertString(raw.source, "source");
+  if (!["cli", "system", "benchmark", "tool_result"].includes(source)) {
+    throw new Error("source must be one of cli|system|benchmark|tool_result");
+  }
+  const target = assertString(raw.target, "target");
+  if (!["promotion", "ranking"].includes(target)) {
+    throw new Error("target must be one of promotion|ranking");
+  }
+  const decision = assertString(raw.decision, "decision");
+  if (!["promote", "demote", "hold", "boost", "suppress"].includes(decision)) {
+    throw new Error("decision must be one of promote|demote|hold|boost|suppress");
+  }
+  const outcome = assertString(raw.outcome, "outcome");
+  if (!["helpful", "neutral", "harmful"].includes(outcome)) {
+    throw new Error("outcome must be one of helpful|neutral|harmful");
+  }
+  return {
+    schemaVersion: 1,
+    eventId: assertSafePathSegment(assertString(raw.eventId, "eventId"), "eventId"),
+    recordedAt: assertIsoRecordedAt(assertString(raw.recordedAt, "recordedAt")),
+    sessionKey: assertString(raw.sessionKey, "sessionKey"),
+    source,
+    target,
+    decision,
+    outcome,
+    utilityScore: assertUtilityScore(raw.utilityScore),
+    summary: assertString(raw.summary, "summary"),
+    memoryIds: optionalStringArray(raw.memoryIds, "memoryIds"),
+    entityRefs: optionalStringArray(raw.entityRefs, "entityRefs"),
+    tags: optionalStringArray(raw.tags, "tags"),
+    metadata: validateStringRecord(raw.metadata, "metadata")
+  };
+}
+async function recordUtilityTelemetryEvent(options) {
+  const rootDir = resolveUtilityTelemetryDir(options.memoryDir, options.utilityTelemetryDir);
+  const validated = validateUtilityTelemetryEvent(options.event);
+  const day = recordStoreDay(validated.recordedAt);
+  const eventsDir = path.join(rootDir, "events", day);
+  const filePath = path.join(eventsDir, `${validated.eventId}.json`);
+  await mkdir(eventsDir, { recursive: true });
+  await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  return filePath;
+}
+async function readUtilityTelemetryEvents(options) {
+  const rootDir = resolveUtilityTelemetryDir(options.memoryDir, options.utilityTelemetryDir);
+  const files = await listJsonFiles(path.join(rootDir, "events"));
+  const events = [];
+  const invalidEvents = [];
+  for (const filePath of files) {
+    try {
+      events.push(validateUtilityTelemetryEvent(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidEvents.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return { files, events, invalidEvents };
+}
+async function getUtilityTelemetryStatus(options) {
+  const rootDir = resolveUtilityTelemetryDir(options.memoryDir, options.utilityTelemetryDir);
+  const eventsDir = path.join(rootDir, "events");
+  if (!options.enabled) {
+    return {
+      enabled: false,
+      promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,
+      rootDir,
+      eventsDir,
+      events: {
+        total: 0,
+        valid: 0,
+        invalid: 0,
+        byTarget: {},
+        byDecision: {},
+        byOutcome: {}
+      },
+      invalidEvents: []
+    };
+  }
+  const { files, events, invalidEvents } = await readUtilityTelemetryEvents(options);
+  events.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byTarget = {};
+  const byDecision = {};
+  const byOutcome = {};
+  for (const event of events) {
+    byTarget[event.target] = (byTarget[event.target] ?? 0) + 1;
+    byDecision[event.decision] = (byDecision[event.decision] ?? 0) + 1;
+    byOutcome[event.outcome] = (byOutcome[event.outcome] ?? 0) + 1;
+  }
+  return {
+    enabled: true,
+    promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,
+    rootDir,
+    eventsDir,
+    events: {
+      total: files.length,
+      valid: events.length,
+      invalid: invalidEvents.length,
+      byTarget,
+      byDecision,
+      byOutcome,
+      latestEventId: events[0]?.eventId,
+      latestRecordedAt: events[0]?.recordedAt,
+      latestSessionKey: events[0]?.sessionKey
+    },
+    latestEvent: events[0],
+    invalidEvents
+  };
+}
+
+// ../remnic-core/src/utility-learner.ts
+var UTILITY_LEARNING_SNAPSHOT_VERSION = 1;
+var UTILITY_LEARNING_STATE_FILE = "learning-state.json";
+function clampWeight(value, maxWeightMagnitude) {
+  const limit = Number.isFinite(maxWeightMagnitude) && maxWeightMagnitude > 0 ? maxWeightMagnitude : 0;
+  return Math.max(-limit, Math.min(limit, value));
+}
+function coerceLearningWindowDays(value) {
+  if (!Number.isFinite(value)) return 14;
+  return Math.max(1, Math.floor(value));
+}
+function coerceMinEventCount(value) {
+  if (!Number.isFinite(value)) return 3;
+  return Math.max(1, Math.floor(value));
+}
+function coerceMaxWeightMagnitude(value) {
+  if (!Number.isFinite(value)) return 0.35;
+  return Math.max(0, Math.min(1, value));
+}
+function roundWeight(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+function outcomeCountsFor(events) {
+  const counts = {};
+  for (const event of events) {
+    counts[event.outcome] = (counts[event.outcome] ?? 0) + 1;
+  }
+  return counts;
+}
+function selectRecentEvents(events, now, windowDays) {
+  if (!Number.isFinite(windowDays) || windowDays <= 0) return [...events];
+  const minTimestamp = now.getTime() - windowDays * 864e5;
+  return events.filter((event) => {
+    const ts = Date.parse(event.recordedAt);
+    return Number.isFinite(ts) && ts >= minTimestamp;
+  });
+}
+function confidenceFromEvents(eventCount, averageUtilityScore) {
+  if (eventCount <= 0) return 0;
+  return roundWeight(clamp01(Math.abs(averageUtilityScore) * Math.min(1, eventCount / 10)));
+}
+function validateUtilityLearningSnapshot(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("utility learning snapshot must be an object");
+  }
+  const record = raw;
+  if (record.version !== UTILITY_LEARNING_SNAPSHOT_VERSION) {
+    throw new Error("utility learning snapshot version must be 1");
+  }
+  if (typeof record.updatedAt !== "string" || record.updatedAt.length === 0) {
+    throw new Error("utility learning snapshot updatedAt must be a string");
+  }
+  if (typeof record.windowDays !== "number" || !Number.isFinite(record.windowDays) || record.windowDays < 0) {
+    throw new Error("utility learning snapshot windowDays must be a non-negative number");
+  }
+  if (typeof record.minEventCount !== "number" || !Number.isFinite(record.minEventCount) || record.minEventCount < 1) {
+    throw new Error("utility learning snapshot minEventCount must be >= 1");
+  }
+  if (typeof record.maxWeightMagnitude !== "number" || !Number.isFinite(record.maxWeightMagnitude) || record.maxWeightMagnitude < 0) {
+    throw new Error("utility learning snapshot maxWeightMagnitude must be >= 0");
+  }
+  if (!Array.isArray(record.weights)) {
+    throw new Error("utility learning snapshot weights must be an array");
+  }
+  const weights = record.weights.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error("utility learning weight must be an object");
+    }
+    const weight = entry;
+    const target = weight.target;
+    const decision = weight.decision;
+    if (target !== "promotion" && target !== "ranking") {
+      throw new Error("utility learning weight target must be promotion|ranking");
+    }
+    if (!["promote", "demote", "hold", "boost", "suppress"].includes(String(decision))) {
+      throw new Error("utility learning weight decision is invalid");
+    }
+    if (typeof weight.eventCount !== "number" || !Number.isFinite(weight.eventCount) || weight.eventCount < 0) {
+      throw new Error("utility learning weight eventCount must be >= 0");
+    }
+    if (typeof weight.learnedWeight !== "number" || !Number.isFinite(weight.learnedWeight)) {
+      throw new Error("utility learning weight learnedWeight must be finite");
+    }
+    if (typeof weight.averageUtilityScore !== "number" || !Number.isFinite(weight.averageUtilityScore)) {
+      throw new Error("utility learning weight averageUtilityScore must be finite");
+    }
+    if (typeof weight.confidence !== "number" || !Number.isFinite(weight.confidence)) {
+      throw new Error("utility learning weight confidence must be finite");
+    }
+    if (typeof weight.updatedAt !== "string" || weight.updatedAt.length === 0) {
+      throw new Error("utility learning weight updatedAt must be a string");
+    }
+    const outcomeCounts = weight.outcomeCounts ?? {};
+    return {
+      target,
+      decision,
+      eventCount: weight.eventCount,
+      learnedWeight: roundWeight(weight.learnedWeight),
+      averageUtilityScore: roundWeight(weight.averageUtilityScore),
+      confidence: roundWeight(clamp01(weight.confidence)),
+      outcomeCounts,
+      updatedAt: weight.updatedAt
+    };
+  });
+  return {
+    version: 1,
+    updatedAt: record.updatedAt,
+    windowDays: record.windowDays,
+    minEventCount: record.minEventCount,
+    maxWeightMagnitude: record.maxWeightMagnitude,
+    weights
+  };
+}
+function resolveUtilityLearningStatePath(memoryDir, utilityTelemetryDir) {
+  return path2.join(resolveUtilityTelemetryDir(memoryDir, utilityTelemetryDir), UTILITY_LEARNING_STATE_FILE);
+}
+async function readUtilityLearningSnapshot(memoryDir, utilityTelemetryDir) {
+  const statePath = resolveUtilityLearningStatePath(memoryDir, utilityTelemetryDir);
+  try {
+    const raw = JSON.parse(await readFile(statePath, "utf8"));
+    return validateUtilityLearningSnapshot(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeUtilityLearningSnapshot(statePath, snapshot) {
+  const tempPath = `${statePath}.tmp`;
+  await mkdir2(path2.dirname(statePath), { recursive: true });
+  await writeFile2(tempPath, `${JSON.stringify(snapshot, null, 2)}
+`, "utf8");
+  await rename(tempPath, statePath);
+}
+async function learnUtilityPromotionWeights(options) {
+  const statePath = resolveUtilityLearningStatePath(options.memoryDir, options.utilityTelemetryDir);
+  if (!options.enabled) {
+    return {
+      applied: false,
+      reason: "disabled",
+      statePath,
+      snapshot: null
+    };
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const updatedAt = now.toISOString();
+  const windowDays = coerceLearningWindowDays(options.learningWindowDays);
+  const minEventCount = coerceMinEventCount(options.minEventCount);
+  const maxWeightMagnitude = coerceMaxWeightMagnitude(options.maxWeightMagnitude);
+  const recentEvents = selectRecentEvents(
+    (await readUtilityTelemetryEvents({
+      memoryDir: options.memoryDir,
+      utilityTelemetryDir: options.utilityTelemetryDir
+    })).events,
+    now,
+    windowDays
+  );
+  const grouped = /* @__PURE__ */ new Map();
+  for (const event of recentEvents) {
+    const key = `${event.target}:${event.decision}`;
+    const existing = grouped.get(key);
+    if (existing) {
+      existing.push(event);
+    } else {
+      grouped.set(key, [event]);
+    }
+  }
+  const weights = [];
+  for (const events of grouped.values()) {
+    if (events.length < minEventCount) continue;
+    const target = events[0].target;
+    const decision = events[0].decision;
+    const averageUtilityScore = events.reduce((sum, event) => sum + event.utilityScore, 0) / events.length;
+    const confidence = confidenceFromEvents(events.length, averageUtilityScore);
+    const learnedWeight = roundWeight(
+      clampWeight(averageUtilityScore * confidence, maxWeightMagnitude)
+    );
+    weights.push({
+      target,
+      decision,
+      eventCount: events.length,
+      learnedWeight,
+      averageUtilityScore: roundWeight(averageUtilityScore),
+      confidence,
+      outcomeCounts: outcomeCountsFor(events),
+      updatedAt
+    });
+  }
+  weights.sort((left, right) => {
+    const targetCompare = left.target.localeCompare(right.target);
+    if (targetCompare !== 0) return targetCompare;
+    return left.decision.localeCompare(right.decision);
+  });
+  const snapshot = {
+    version: 1,
+    updatedAt,
+    windowDays,
+    minEventCount,
+    maxWeightMagnitude,
+    weights
+  };
+  if (weights.length === 0) {
+    return {
+      applied: false,
+      reason: "insufficient_events",
+      statePath,
+      snapshot
+    };
+  }
+  await writeUtilityLearningSnapshot(statePath, snapshot);
+  return {
+    applied: true,
+    reason: "learned",
+    statePath,
+    snapshot
+  };
+}
+async function getUtilityLearningStatus(options) {
+  const rootDir = resolveUtilityTelemetryDir(options.memoryDir, options.utilityTelemetryDir);
+  const statePath = resolveUtilityLearningStatePath(options.memoryDir, options.utilityTelemetryDir);
+  if (!options.enabled) {
+    return {
+      enabled: false,
+      promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,
+      rootDir,
+      statePath,
+      snapshot: null,
+      weights: {
+        total: 0,
+        positive: 0,
+        negative: 0,
+        zero: 0
+      }
+    };
+  }
+  const snapshot = await readUtilityLearningSnapshot(options.memoryDir, options.utilityTelemetryDir);
+  const weights = snapshot?.weights ?? [];
+  return {
+    enabled: true,
+    promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,
+    rootDir,
+    statePath,
+    snapshot,
+    weights: {
+      total: weights.length,
+      positive: weights.filter((entry) => entry.learnedWeight > 0).length,
+      negative: weights.filter((entry) => entry.learnedWeight < 0).length,
+      zero: weights.filter((entry) => entry.learnedWeight === 0).length,
+      latestUpdatedAt: snapshot?.updatedAt
+    }
+  };
+}
+
+// ../remnic-core/src/utility-runtime.ts
+var RANKING_MULTIPLIER_LIMIT = 0.12;
+var PROMOTION_THRESHOLD_DELTA_LIMIT = 0.07;
+var PROMOTION_THRESHOLD_WEIGHT_FACTOR = 0.2;
+function roundRuntimeValue(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+function clampSigned(value, limit) {
+  if (!Number.isFinite(value) || limit <= 0) return 0;
+  return Math.max(-limit, Math.min(limit, value));
+}
+function learnedWeightFor(snapshot, target, decision) {
+  const entry = snapshot.weights.find((weight) => weight.target === target && weight.decision === decision);
+  return entry?.learnedWeight ?? 0;
+}
+async function loadUtilityRuntimeValues(options) {
+  if (!options.memoryUtilityLearningEnabled || !options.promotionByOutcomeEnabled) return null;
+  const snapshot = await readUtilityLearningSnapshot(options.memoryDir, options.utilityTelemetryDir);
+  if (!snapshot) return null;
+  return {
+    rankingBoostMultiplier: roundRuntimeValue(
+      1 + clampSigned(learnedWeightFor(snapshot, "ranking", "boost"), RANKING_MULTIPLIER_LIMIT)
+    ),
+    rankingSuppressMultiplier: roundRuntimeValue(
+      1 + clampSigned(learnedWeightFor(snapshot, "ranking", "suppress"), RANKING_MULTIPLIER_LIMIT)
+    ),
+    promoteThresholdDelta: roundRuntimeValue(
+      clampSigned(
+        learnedWeightFor(snapshot, "promotion", "promote") * -PROMOTION_THRESHOLD_WEIGHT_FACTOR,
+        PROMOTION_THRESHOLD_DELTA_LIMIT
+      )
+    ),
+    demoteThresholdDelta: roundRuntimeValue(
+      clampSigned(
+        learnedWeightFor(snapshot, "promotion", "demote") * PROMOTION_THRESHOLD_WEIGHT_FACTOR,
+        PROMOTION_THRESHOLD_DELTA_LIMIT
+      )
+    ),
+    snapshotUpdatedAt: snapshot.updatedAt
+  };
+}
+function applyUtilityRankingRuntimeDelta(delta, runtime, mode) {
+  if (!runtime || !Number.isFinite(delta) || delta === 0) return delta;
+  const multiplier = mode === "boost" ? runtime.rankingBoostMultiplier : runtime.rankingSuppressMultiplier;
+  return roundRuntimeValue(delta * multiplier);
+}
+function applyUtilityPromotionRuntimePolicy(policy, runtime) {
+  if (!runtime) return policy;
+  return {
+    ...policy,
+    demotionValueThreshold: roundRuntimeValue(clamp01(policy.demotionValueThreshold + runtime.demoteThresholdDelta)),
+    promotionValueThreshold: roundRuntimeValue(clamp01(policy.promotionValueThreshold + runtime.promoteThresholdDelta))
+  };
+}
+
+export {
+  computeTierValueScore,
+  decideTierTransition,
+  recordUtilityTelemetryEvent,
+  getUtilityTelemetryStatus,
+  learnUtilityPromotionWeights,
+  getUtilityLearningStatus,
+  loadUtilityRuntimeValues,
+  applyUtilityRankingRuntimeDelta,
+  applyUtilityPromotionRuntimePolicy
+};