@remnic/core 1.0.0

package/dist/chunk-ORZMT74A.js

@@ -0,0 +1,209 @@
+import {
+  countRecallTokenOverlap,
+  normalizeRecallTokens
+} from "./chunk-DT5TVLJE.js";
+import {
+  assertIsoRecordedAt,
+  assertSafePathSegment,
+  assertString,
+  isRecord,
+  optionalString,
+  optionalStringArray,
+  recordStoreDay,
+  validateStringRecord
+} from "./chunk-DGXUHMOV.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-LPSF4OQH.js";
+
+// src/causal-trajectory.ts
+import path from "path";
+import { mkdir, writeFile } from "fs/promises";
+function validateMetadata(raw) {
+  return validateStringRecord(raw, "metadata");
+}
+function resolveCausalTrajectoryStoreDir(memoryDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path.join(memoryDir, "state", "causal-trajectories");
+}
+function validateCausalTrajectoryRecord(raw) {
+  if (!isRecord(raw)) throw new Error("causal trajectory record must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  const outcomeKind = assertString(raw.outcomeKind, "outcomeKind");
+  if (!["success", "failure", "partial", "unknown"].includes(outcomeKind)) {
+    throw new Error("outcomeKind must be one of success|failure|partial|unknown");
+  }
+  return {
+    schemaVersion: 1,
+    trajectoryId: assertSafePathSegment(assertString(raw.trajectoryId, "trajectoryId"), "trajectoryId"),
+    recordedAt: assertIsoRecordedAt(assertString(raw.recordedAt, "recordedAt")),
+    sessionKey: assertString(raw.sessionKey, "sessionKey"),
+    goal: assertString(raw.goal, "goal"),
+    actionSummary: assertString(raw.actionSummary, "actionSummary"),
+    observationSummary: assertString(raw.observationSummary, "observationSummary"),
+    outcomeKind,
+    outcomeSummary: assertString(raw.outcomeSummary, "outcomeSummary"),
+    followUpSummary: optionalString(raw.followUpSummary),
+    objectiveStateSnapshotRefs: optionalStringArray(raw.objectiveStateSnapshotRefs, "objectiveStateSnapshotRefs"),
+    entityRefs: optionalStringArray(raw.entityRefs, "entityRefs"),
+    tags: optionalStringArray(raw.tags, "tags"),
+    metadata: validateMetadata(raw.metadata)
+  };
+}
+async function recordCausalTrajectory(options) {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  const validated = validateCausalTrajectoryRecord(options.record);
+  const day = recordStoreDay(validated.recordedAt);
+  const trajectoriesDir = path.join(rootDir, "trajectories", day);
+  const filePath = path.join(trajectoriesDir, `${validated.trajectoryId}.json`);
+  await mkdir(trajectoriesDir, { recursive: true });
+  await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  if (options.actionGraphRecallEnabled === true) {
+    try {
+      const { appendCausalTrajectoryGraphEdges } = await import("./causal-trajectory-graph.js");
+      await appendCausalTrajectoryGraphEdges({
+        memoryDir: options.memoryDir,
+        record: validated
+      });
+    } catch (error) {
+      const { log } = await import("./logger.js");
+      log.warn(
+        `[causal-trajectory] action-conditioned graph write failed for ${validated.trajectoryId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  if (options.cmcEnabled === true) {
+    try {
+      const { stitchCausalChain } = await import("./causal-chain.js");
+      await stitchCausalChain({
+        memoryDir: options.memoryDir,
+        causalTrajectoryStoreDir: options.causalTrajectoryStoreDir,
+        newTrajectory: validated,
+        config: {
+          lookbackDays: options.cmcStitchLookbackDays ?? 7,
+          minScore: options.cmcStitchMinScore ?? 2.5,
+          maxEdgesPerTrajectory: options.cmcStitchMaxEdgesPerTrajectory ?? 3
+        }
+      });
+    } catch (error) {
+      const { log } = await import("./logger.js");
+      log.warn(
+        `[cmc] causal chain stitching failed for ${validated.trajectoryId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return filePath;
+}
+async function readCausalTrajectoryRecords(options) {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  const files = await listJsonFiles(path.join(rootDir, "trajectories"));
+  const trajectories = [];
+  const invalidTrajectories = [];
+  for (const filePath of files) {
+    try {
+      trajectories.push(validateCausalTrajectoryRecord(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidTrajectories.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return { files, trajectories, invalidTrajectories };
+}
+async function getCausalTrajectoryStoreStatus(options) {
+  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);
+  const trajectoriesDir = path.join(rootDir, "trajectories");
+  const { files, trajectories, invalidTrajectories } = await readCausalTrajectoryRecords(options);
+  trajectories.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byOutcome = {};
+  for (const trajectory of trajectories) {
+    byOutcome[trajectory.outcomeKind] = (byOutcome[trajectory.outcomeKind] ?? 0) + 1;
+  }
+  return {
+    enabled: options.enabled,
+    rootDir,
+    trajectoriesDir,
+    trajectories: {
+      total: files.length,
+      valid: trajectories.length,
+      invalid: invalidTrajectories.length,
+      byOutcome,
+      latestTrajectoryId: trajectories[0]?.trajectoryId,
+      latestRecordedAt: trajectories[0]?.recordedAt,
+      latestSessionKey: trajectories[0]?.sessionKey
+    },
+    latestTrajectory: trajectories[0],
+    invalidTrajectories
+  };
+}
+function lexicalScoreCausalTrajectoryRecord(record, queryTokens) {
+  const weightedFields = [
+    ["goal", record.goal, 4],
+    ["action", record.actionSummary, 3],
+    ["observation", record.observationSummary, 3],
+    ["outcome", record.outcomeSummary, 3],
+    ["follow_up", record.followUpSummary, 2],
+    ["outcome_kind", record.outcomeKind, 1],
+    ["tags", record.tags?.join(" "), 2],
+    ["entity_refs", record.entityRefs?.join(" "), 2],
+    ["objective_state_refs", record.objectiveStateSnapshotRefs?.join(" "), 1]
+  ];
+  let score = 0;
+  const matchedFields = [];
+  for (const [field, value, weight] of weightedFields) {
+    const matches = countRecallTokenOverlap(queryTokens, value, ["make"]);
+    if (matches > 0) matchedFields.push(field);
+    score += matches * weight;
+  }
+  return { score, matchedFields };
+}
+function scoreCausalTrajectoryRecord(record, lexicalScore, sessionKey) {
+  let score = lexicalScore;
+  if (sessionKey && record.sessionKey === sessionKey) score += 1.5;
+  const recordedAtMs = Date.parse(record.recordedAt);
+  if (Number.isFinite(recordedAtMs)) {
+    const ageHours = Math.max(0, (Date.now() - recordedAtMs) / 36e5);
+    score += 1 / (1 + ageHours);
+  }
+  return score;
+}
+async function searchCausalTrajectories(options) {
+  const maxResults = Math.max(0, Math.floor(options.maxResults));
+  if (maxResults === 0) return [];
+  const { trajectories } = await readCausalTrajectoryRecords(options);
+  if (trajectories.length === 0) return [];
+  const queryTokens = new Set(normalizeRecallTokens(options.query, ["make"]));
+  if (queryTokens.size === 0) return [];
+  const scored = trajectories.map((record) => {
+    const lexical = lexicalScoreCausalTrajectoryRecord(record, queryTokens);
+    return {
+      record,
+      matchedFields: lexical.matchedFields,
+      lexicalScore: lexical.score,
+      score: scoreCausalTrajectoryRecord(record, lexical.score, options.sessionKey)
+    };
+  });
+  const filtered = scored.filter((result) => result.lexicalScore > 0);
+  filtered.sort((left, right) => {
+    if (right.score !== left.score) return right.score - left.score;
+    return right.record.recordedAt.localeCompare(left.record.recordedAt);
+  });
+  return filtered.slice(0, maxResults).map(({ record, score, matchedFields }) => ({
+    record,
+    score,
+    matchedFields
+  }));
+}
+
+export {
+  resolveCausalTrajectoryStoreDir,
+  validateCausalTrajectoryRecord,
+  recordCausalTrajectory,
+  getCausalTrajectoryStoreStatus,
+  searchCausalTrajectories
+};
+//# sourceMappingURL=chunk-ORZMT74A.js.map

package/dist/chunk-ORZMT74A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/causal-trajectory.ts"],"sourcesContent":["import path from \"node:path\";\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { listJsonFiles, readJsonFile } from \"./json-store.js\";\nimport type { ObjectiveStateOutcome } from \"./objective-state.js\";\nimport { countRecallTokenOverlap, normalizeRecallTokens } from \"./recall-tokenization.js\";\nimport {\n  assertIsoRecordedAt,\n  assertSafePathSegment,\n  assertString,\n  isRecord,\n  optionalString,\n  optionalStringArray,\n  recordStoreDay,\n  validateStringRecord,\n} from \"./store-contract.js\";\n\nexport interface CausalTrajectoryRecord {\n  schemaVersion: 1;\n  trajectoryId: string;\n  recordedAt: string;\n  sessionKey: string;\n  goal: string;\n  actionSummary: string;\n  observationSummary: string;\n  outcomeKind: ObjectiveStateOutcome;\n  outcomeSummary: string;\n  followUpSummary?: string;\n  objectiveStateSnapshotRefs?: string[];\n  entityRefs?: string[];\n  tags?: string[];\n  metadata?: Record<string, string>;\n}\n\nexport interface CausalTrajectoryStoreStatus {\n  enabled: boolean;\n  rootDir: string;\n  trajectoriesDir: string;\n  trajectories: {\n    total: number;\n    valid: number;\n    invalid: number;\n    byOutcome: Partial<Record<ObjectiveStateOutcome, number>>;\n    latestTrajectoryId?: string;\n    latestRecordedAt?: string;\n    latestSessionKey?: string;\n  };\n  latestTrajectory?: CausalTrajectoryRecord;\n  invalidTrajectories: Array<{\n    path: string;\n    error: string;\n  }>;\n}\n\nexport interface CausalTrajectorySearchResult {\n  record: CausalTrajectoryRecord;\n  score: number;\n  matchedFields: string[];\n}\n\nfunction validateMetadata(raw: unknown): Record<string, string> | undefined {\n  return validateStringRecord(raw, \"metadata\");\n}\n\nexport function resolveCausalTrajectoryStoreDir(memoryDir: string, overrideDir?: string): string {\n  if (typeof overrideDir === \"string\" && overrideDir.trim().length > 0) {\n    return overrideDir.trim();\n  }\n  return path.join(memoryDir, \"state\", \"causal-trajectories\");\n}\n\nexport function validateCausalTrajectoryRecord(raw: unknown): CausalTrajectoryRecord {\n  if (!isRecord(raw)) throw new Error(\"causal trajectory record must be an object\");\n  if (raw.schemaVersion !== 1) throw new Error(\"schemaVersion must be 1\");\n\n  const outcomeKind = assertString(raw.outcomeKind, \"outcomeKind\");\n  if (![\"success\", \"failure\", \"partial\", \"unknown\"].includes(outcomeKind)) {\n    throw new Error(\"outcomeKind must be one of success|failure|partial|unknown\");\n  }\n\n  return {\n    schemaVersion: 1,\n    trajectoryId: assertSafePathSegment(assertString(raw.trajectoryId, \"trajectoryId\"), \"trajectoryId\"),\n    recordedAt: assertIsoRecordedAt(assertString(raw.recordedAt, \"recordedAt\")),\n    sessionKey: assertString(raw.sessionKey, \"sessionKey\"),\n    goal: assertString(raw.goal, \"goal\"),\n    actionSummary: assertString(raw.actionSummary, \"actionSummary\"),\n    observationSummary: assertString(raw.observationSummary, \"observationSummary\"),\n    outcomeKind: outcomeKind as ObjectiveStateOutcome,\n    outcomeSummary: assertString(raw.outcomeSummary, \"outcomeSummary\"),\n    followUpSummary: optionalString(raw.followUpSummary),\n    objectiveStateSnapshotRefs: optionalStringArray(raw.objectiveStateSnapshotRefs, \"objectiveStateSnapshotRefs\"),\n    entityRefs: optionalStringArray(raw.entityRefs, \"entityRefs\"),\n    tags: optionalStringArray(raw.tags, \"tags\"),\n    metadata: validateMetadata(raw.metadata),\n  };\n}\n\nexport async function recordCausalTrajectory(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  actionGraphRecallEnabled?: boolean;\n  cmcEnabled?: boolean;\n  cmcStitchLookbackDays?: number;\n  cmcStitchMinScore?: number;\n  cmcStitchMaxEdgesPerTrajectory?: number;\n  record: CausalTrajectoryRecord;\n}): Promise<string> {\n  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);\n  const validated = validateCausalTrajectoryRecord(options.record);\n  const day = recordStoreDay(validated.recordedAt);\n  const trajectoriesDir = path.join(rootDir, \"trajectories\", day);\n  const filePath = path.join(trajectoriesDir, `${validated.trajectoryId}.json`);\n  await mkdir(trajectoriesDir, { recursive: true });\n  await writeFile(filePath, JSON.stringify(validated, null, 2), \"utf8\");\n  if (options.actionGraphRecallEnabled === true) {\n    try {\n      const { appendCausalTrajectoryGraphEdges } = await import(\"./causal-trajectory-graph.js\");\n      await appendCausalTrajectoryGraphEdges({\n        memoryDir: options.memoryDir,\n        record: validated,\n      });\n    } catch (error) {\n      const { log } = await import(\"./logger.js\");\n      log.warn(\n        `[causal-trajectory] action-conditioned graph write failed for ${validated.trajectoryId}: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n  if (options.cmcEnabled === true) {\n    try {\n      const { stitchCausalChain } = await import(\"./causal-chain.js\");\n      await stitchCausalChain({\n        memoryDir: options.memoryDir,\n        causalTrajectoryStoreDir: options.causalTrajectoryStoreDir,\n        newTrajectory: validated,\n        config: {\n          lookbackDays: options.cmcStitchLookbackDays ?? 7,\n          minScore: options.cmcStitchMinScore ?? 2.5,\n          maxEdgesPerTrajectory: options.cmcStitchMaxEdgesPerTrajectory ?? 3,\n        },\n      });\n    } catch (error) {\n      const { log } = await import(\"./logger.js\");\n      log.warn(\n        `[cmc] causal chain stitching failed for ${validated.trajectoryId}: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n  return filePath;\n}\n\nasync function readCausalTrajectoryRecords(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n}): Promise<{\n  files: string[];\n  trajectories: CausalTrajectoryRecord[];\n  invalidTrajectories: Array<{ path: string; error: string }>;\n}> {\n  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);\n  const files = await listJsonFiles(path.join(rootDir, \"trajectories\"));\n  const trajectories: CausalTrajectoryRecord[] = [];\n  const invalidTrajectories: Array<{ path: string; error: string }> = [];\n  for (const filePath of files) {\n    try {\n      trajectories.push(validateCausalTrajectoryRecord(await readJsonFile(filePath)));\n    } catch (error) {\n      invalidTrajectories.push({\n        path: filePath,\n        error: error instanceof Error ? error.message : String(error),\n      });\n    }\n  }\n  return { files, trajectories, invalidTrajectories };\n}\n\nexport async function getCausalTrajectoryStoreStatus(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  enabled: boolean;\n}): Promise<CausalTrajectoryStoreStatus> {\n  const rootDir = resolveCausalTrajectoryStoreDir(options.memoryDir, options.causalTrajectoryStoreDir);\n  const trajectoriesDir = path.join(rootDir, \"trajectories\");\n  const { files, trajectories, invalidTrajectories } = await readCausalTrajectoryRecords(options);\n\n  trajectories.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));\n  const byOutcome: Partial<Record<ObjectiveStateOutcome, number>> = {};\n  for (const trajectory of trajectories) {\n    byOutcome[trajectory.outcomeKind] = (byOutcome[trajectory.outcomeKind] ?? 0) + 1;\n  }\n\n  return {\n    enabled: options.enabled,\n    rootDir,\n    trajectoriesDir,\n    trajectories: {\n      total: files.length,\n      valid: trajectories.length,\n      invalid: invalidTrajectories.length,\n      byOutcome,\n      latestTrajectoryId: trajectories[0]?.trajectoryId,\n      latestRecordedAt: trajectories[0]?.recordedAt,\n      latestSessionKey: trajectories[0]?.sessionKey,\n    },\n    latestTrajectory: trajectories[0],\n    invalidTrajectories,\n  };\n}\n\nfunction lexicalScoreCausalTrajectoryRecord(\n  record: CausalTrajectoryRecord,\n  queryTokens: Set<string>,\n): { score: number; matchedFields: string[] } {\n  const weightedFields: Array<[field: string, value: string | undefined, weight: number]> = [\n    [\"goal\", record.goal, 4],\n    [\"action\", record.actionSummary, 3],\n    [\"observation\", record.observationSummary, 3],\n    [\"outcome\", record.outcomeSummary, 3],\n    [\"follow_up\", record.followUpSummary, 2],\n    [\"outcome_kind\", record.outcomeKind, 1],\n    [\"tags\", record.tags?.join(\" \"), 2],\n    [\"entity_refs\", record.entityRefs?.join(\" \"), 2],\n    [\"objective_state_refs\", record.objectiveStateSnapshotRefs?.join(\" \"), 1],\n  ];\n\n  let score = 0;\n  const matchedFields: string[] = [];\n  for (const [field, value, weight] of weightedFields) {\n    const matches = countRecallTokenOverlap(queryTokens, value, [\"make\"]);\n    if (matches > 0) matchedFields.push(field);\n    score += matches * weight;\n  }\n  return { score, matchedFields };\n}\n\nfunction scoreCausalTrajectoryRecord(\n  record: CausalTrajectoryRecord,\n  lexicalScore: number,\n  sessionKey?: string,\n): number {\n  let score = lexicalScore;\n  if (sessionKey && record.sessionKey === sessionKey) score += 1.5;\n\n  const recordedAtMs = Date.parse(record.recordedAt);\n  if (Number.isFinite(recordedAtMs)) {\n    const ageHours = Math.max(0, (Date.now() - recordedAtMs) / 3_600_000);\n    score += 1 / (1 + ageHours);\n  }\n  return score;\n}\n\nexport async function searchCausalTrajectories(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  query: string;\n  maxResults: number;\n  sessionKey?: string;\n}): Promise<CausalTrajectorySearchResult[]> {\n  const maxResults = Math.max(0, Math.floor(options.maxResults));\n  if (maxResults === 0) return [];\n\n  const { trajectories } = await readCausalTrajectoryRecords(options);\n  if (trajectories.length === 0) return [];\n\n  const queryTokens = new Set(normalizeRecallTokens(options.query, [\"make\"]));\n  if (queryTokens.size === 0) return [];\n  const scored = trajectories.map((record) => {\n    const lexical = lexicalScoreCausalTrajectoryRecord(record, queryTokens);\n    return {\n      record,\n      matchedFields: lexical.matchedFields,\n      lexicalScore: lexical.score,\n      score: scoreCausalTrajectoryRecord(record, lexical.score, options.sessionKey),\n    };\n  });\n\n  const filtered = scored.filter((result) => result.lexicalScore > 0);\n\n  filtered.sort((left, right) => {\n    if (right.score !== left.score) return right.score - left.score;\n    return right.record.recordedAt.localeCompare(left.record.recordedAt);\n  });\n\n  return filtered.slice(0, maxResults).map(({ record, score, matchedFields }) => ({\n    record,\n    score,\n    matchedFields,\n  }));\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-OTAVQCSF.js

@@ -0,0 +1,268 @@
+import {
+  readUtilityTelemetryEvents,
+  resolveUtilityTelemetryDir
+} from "./chunk-3QKK7QOS.js";
+import {
+  clamp01
+} from "./chunk-QCCCQT3O.js";
+
+// src/utility-learner.ts
+import path from "path";
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+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 path.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 mkdir(path.dirname(statePath), { recursive: true });
+  await writeFile(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
+    }
+  };
+}
+
+export {
+  resolveUtilityLearningStatePath,
+  readUtilityLearningSnapshot,
+  learnUtilityPromotionWeights,
+  getUtilityLearningStatus
+};
+//# sourceMappingURL=chunk-OTAVQCSF.js.map

package/dist/chunk-OTAVQCSF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utility-learner.ts"],"sourcesContent":["import path from \"node:path\";\nimport { mkdir, readFile, rename, writeFile } from \"node:fs/promises\";\nimport { clamp01 } from \"./lifecycle.js\";\nimport {\n  readUtilityTelemetryEvents,\n  resolveUtilityTelemetryDir,\n  type UtilityTelemetryDecision,\n  type UtilityTelemetryEvent,\n  type UtilityTelemetryOutcome,\n  type UtilityTelemetryTarget,\n} from \"./utility-telemetry.js\";\n\nexport interface UtilityLearningWeight {\n  target: UtilityTelemetryTarget;\n  decision: UtilityTelemetryDecision;\n  eventCount: number;\n  learnedWeight: number;\n  averageUtilityScore: number;\n  confidence: number;\n  outcomeCounts: Partial<Record<UtilityTelemetryOutcome, number>>;\n  updatedAt: string;\n}\n\nexport interface UtilityLearningSnapshot {\n  version: 1;\n  updatedAt: string;\n  windowDays: number;\n  minEventCount: number;\n  maxWeightMagnitude: number;\n  weights: UtilityLearningWeight[];\n}\n\nexport interface UtilityLearningStatus {\n  enabled: boolean;\n  promotionByOutcomeEnabled: boolean;\n  rootDir: string;\n  statePath: string;\n  snapshot: UtilityLearningSnapshot | null;\n  weights: {\n    total: number;\n    positive: number;\n    negative: number;\n    zero: number;\n    latestUpdatedAt?: string;\n  };\n}\n\nexport interface UtilityLearningResult {\n  applied: boolean;\n  reason: \"disabled\" | \"insufficient_events\" | \"learned\";\n  statePath: string;\n  snapshot: UtilityLearningSnapshot | null;\n}\n\nconst UTILITY_LEARNING_SNAPSHOT_VERSION = 1;\nconst UTILITY_LEARNING_STATE_FILE = \"learning-state.json\";\n\nfunction clampWeight(value: number, maxWeightMagnitude: number): number {\n  const limit = Number.isFinite(maxWeightMagnitude) && maxWeightMagnitude > 0\n    ? maxWeightMagnitude\n    : 0;\n  return Math.max(-limit, Math.min(limit, value));\n}\n\nfunction coerceLearningWindowDays(value: number): number {\n  if (!Number.isFinite(value)) return 14;\n  return Math.max(1, Math.floor(value));\n}\n\nfunction coerceMinEventCount(value: number): number {\n  if (!Number.isFinite(value)) return 3;\n  return Math.max(1, Math.floor(value));\n}\n\nfunction coerceMaxWeightMagnitude(value: number): number {\n  if (!Number.isFinite(value)) return 0.35;\n  return Math.max(0, Math.min(1, value));\n}\n\nfunction roundWeight(value: number): number {\n  return Math.round(value * 1000) / 1000;\n}\n\nfunction outcomeCountsFor(events: UtilityTelemetryEvent[]): Partial<Record<UtilityTelemetryOutcome, number>> {\n  const counts: Partial<Record<UtilityTelemetryOutcome, number>> = {};\n  for (const event of events) {\n    counts[event.outcome] = (counts[event.outcome] ?? 0) + 1;\n  }\n  return counts;\n}\n\nfunction selectRecentEvents(events: UtilityTelemetryEvent[], now: Date, windowDays: number): UtilityTelemetryEvent[] {\n  if (!Number.isFinite(windowDays) || windowDays <= 0) return [...events];\n  const minTimestamp = now.getTime() - windowDays * 86_400_000;\n  return events.filter((event) => {\n    const ts = Date.parse(event.recordedAt);\n    return Number.isFinite(ts) && ts >= minTimestamp;\n  });\n}\n\nfunction confidenceFromEvents(eventCount: number, averageUtilityScore: number): number {\n  if (eventCount <= 0) return 0;\n  return roundWeight(clamp01(Math.abs(averageUtilityScore) * Math.min(1, eventCount / 10)));\n}\n\nfunction validateUtilityLearningSnapshot(raw: unknown): UtilityLearningSnapshot {\n  if (!raw || typeof raw !== \"object\" || Array.isArray(raw)) {\n    throw new Error(\"utility learning snapshot must be an object\");\n  }\n  const record = raw as Record<string, unknown>;\n  if (record.version !== UTILITY_LEARNING_SNAPSHOT_VERSION) {\n    throw new Error(\"utility learning snapshot version must be 1\");\n  }\n  if (typeof record.updatedAt !== \"string\" || record.updatedAt.length === 0) {\n    throw new Error(\"utility learning snapshot updatedAt must be a string\");\n  }\n  if (typeof record.windowDays !== \"number\" || !Number.isFinite(record.windowDays) || record.windowDays < 0) {\n    throw new Error(\"utility learning snapshot windowDays must be a non-negative number\");\n  }\n  if (typeof record.minEventCount !== \"number\" || !Number.isFinite(record.minEventCount) || record.minEventCount < 1) {\n    throw new Error(\"utility learning snapshot minEventCount must be >= 1\");\n  }\n  if (\n    typeof record.maxWeightMagnitude !== \"number\" ||\n    !Number.isFinite(record.maxWeightMagnitude) ||\n    record.maxWeightMagnitude < 0\n  ) {\n    throw new Error(\"utility learning snapshot maxWeightMagnitude must be >= 0\");\n  }\n  if (!Array.isArray(record.weights)) {\n    throw new Error(\"utility learning snapshot weights must be an array\");\n  }\n\n  const weights = record.weights.map((entry) => {\n    if (!entry || typeof entry !== \"object\" || Array.isArray(entry)) {\n      throw new Error(\"utility learning weight must be an object\");\n    }\n    const weight = entry as Record<string, unknown>;\n    const target = weight.target;\n    const decision = weight.decision;\n    if (target !== \"promotion\" && target !== \"ranking\") {\n      throw new Error(\"utility learning weight target must be promotion|ranking\");\n    }\n    if (![\"promote\", \"demote\", \"hold\", \"boost\", \"suppress\"].includes(String(decision))) {\n      throw new Error(\"utility learning weight decision is invalid\");\n    }\n    if (typeof weight.eventCount !== \"number\" || !Number.isFinite(weight.eventCount) || weight.eventCount < 0) {\n      throw new Error(\"utility learning weight eventCount must be >= 0\");\n    }\n    if (typeof weight.learnedWeight !== \"number\" || !Number.isFinite(weight.learnedWeight)) {\n      throw new Error(\"utility learning weight learnedWeight must be finite\");\n    }\n    if (typeof weight.averageUtilityScore !== \"number\" || !Number.isFinite(weight.averageUtilityScore)) {\n      throw new Error(\"utility learning weight averageUtilityScore must be finite\");\n    }\n    if (typeof weight.confidence !== \"number\" || !Number.isFinite(weight.confidence)) {\n      throw new Error(\"utility learning weight confidence must be finite\");\n    }\n    if (typeof weight.updatedAt !== \"string\" || weight.updatedAt.length === 0) {\n      throw new Error(\"utility learning weight updatedAt must be a string\");\n    }\n    const outcomeCounts = (weight.outcomeCounts ?? {}) as Partial<Record<UtilityTelemetryOutcome, number>>;\n    return {\n      target,\n      decision: decision as UtilityTelemetryDecision,\n      eventCount: weight.eventCount,\n      learnedWeight: roundWeight(weight.learnedWeight),\n      averageUtilityScore: roundWeight(weight.averageUtilityScore),\n      confidence: roundWeight(clamp01(weight.confidence)),\n      outcomeCounts,\n      updatedAt: weight.updatedAt,\n    } satisfies UtilityLearningWeight;\n  });\n\n  return {\n    version: 1,\n    updatedAt: record.updatedAt,\n    windowDays: record.windowDays,\n    minEventCount: record.minEventCount,\n    maxWeightMagnitude: record.maxWeightMagnitude,\n    weights,\n  };\n}\n\nexport function resolveUtilityLearningStatePath(memoryDir: string, utilityTelemetryDir?: string): string {\n  return path.join(resolveUtilityTelemetryDir(memoryDir, utilityTelemetryDir), UTILITY_LEARNING_STATE_FILE);\n}\n\nexport async function readUtilityLearningSnapshot(\n  memoryDir: string,\n  utilityTelemetryDir?: string,\n): Promise<UtilityLearningSnapshot | null> {\n  const statePath = resolveUtilityLearningStatePath(memoryDir, utilityTelemetryDir);\n  try {\n    const raw = JSON.parse(await readFile(statePath, \"utf8\")) as unknown;\n    return validateUtilityLearningSnapshot(raw);\n  } catch {\n    return null;\n  }\n}\n\nasync function writeUtilityLearningSnapshot(\n  statePath: string,\n  snapshot: UtilityLearningSnapshot,\n): Promise<void> {\n  const tempPath = `${statePath}.tmp`;\n  await mkdir(path.dirname(statePath), { recursive: true });\n  await writeFile(tempPath, `${JSON.stringify(snapshot, null, 2)}\\n`, \"utf8\");\n  await rename(tempPath, statePath);\n}\n\nexport async function learnUtilityPromotionWeights(options: {\n  memoryDir: string;\n  utilityTelemetryDir?: string;\n  enabled: boolean;\n  now?: Date;\n  learningWindowDays: number;\n  minEventCount: number;\n  maxWeightMagnitude: number;\n}): Promise<UtilityLearningResult> {\n  const statePath = resolveUtilityLearningStatePath(options.memoryDir, options.utilityTelemetryDir);\n  if (!options.enabled) {\n    return {\n      applied: false,\n      reason: \"disabled\",\n      statePath,\n      snapshot: null,\n    };\n  }\n\n  const now = options.now ?? new Date();\n  const updatedAt = now.toISOString();\n  const windowDays = coerceLearningWindowDays(options.learningWindowDays);\n  const minEventCount = coerceMinEventCount(options.minEventCount);\n  const maxWeightMagnitude = coerceMaxWeightMagnitude(options.maxWeightMagnitude);\n  const recentEvents = selectRecentEvents(\n    (\n      await readUtilityTelemetryEvents({\n        memoryDir: options.memoryDir,\n        utilityTelemetryDir: options.utilityTelemetryDir,\n      })\n    ).events,\n    now,\n    windowDays,\n  );\n\n  const grouped = new Map<string, UtilityTelemetryEvent[]>();\n  for (const event of recentEvents) {\n    const key = `${event.target}:${event.decision}`;\n    const existing = grouped.get(key);\n    if (existing) {\n      existing.push(event);\n    } else {\n      grouped.set(key, [event]);\n    }\n  }\n\n  const weights: UtilityLearningWeight[] = [];\n  for (const events of grouped.values()) {\n    if (events.length < minEventCount) continue;\n    const target = events[0].target;\n    const decision = events[0].decision;\n    const averageUtilityScore = events.reduce((sum, event) => sum + event.utilityScore, 0) / events.length;\n    const confidence = confidenceFromEvents(events.length, averageUtilityScore);\n    const learnedWeight = roundWeight(\n      clampWeight(averageUtilityScore * confidence, maxWeightMagnitude),\n    );\n    weights.push({\n      target,\n      decision,\n      eventCount: events.length,\n      learnedWeight,\n      averageUtilityScore: roundWeight(averageUtilityScore),\n      confidence,\n      outcomeCounts: outcomeCountsFor(events),\n      updatedAt,\n    });\n  }\n\n  weights.sort((left, right) => {\n    const targetCompare = left.target.localeCompare(right.target);\n    if (targetCompare !== 0) return targetCompare;\n    return left.decision.localeCompare(right.decision);\n  });\n\n  const snapshot: UtilityLearningSnapshot = {\n    version: 1,\n    updatedAt,\n    windowDays,\n    minEventCount,\n    maxWeightMagnitude,\n    weights,\n  };\n\n  if (weights.length === 0) {\n    return {\n      applied: false,\n      reason: \"insufficient_events\",\n      statePath,\n      snapshot,\n    };\n  }\n\n  await writeUtilityLearningSnapshot(statePath, snapshot);\n  return {\n    applied: true,\n    reason: \"learned\",\n    statePath,\n    snapshot,\n  };\n}\n\nexport async function getUtilityLearningStatus(options: {\n  memoryDir: string;\n  utilityTelemetryDir?: string;\n  enabled: boolean;\n  promotionByOutcomeEnabled?: boolean;\n}): Promise<UtilityLearningStatus> {\n  const rootDir = resolveUtilityTelemetryDir(options.memoryDir, options.utilityTelemetryDir);\n  const statePath = resolveUtilityLearningStatePath(options.memoryDir, options.utilityTelemetryDir);\n  if (!options.enabled) {\n    return {\n      enabled: false,\n      promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,\n      rootDir,\n      statePath,\n      snapshot: null,\n      weights: {\n        total: 0,\n        positive: 0,\n        negative: 0,\n        zero: 0,\n      },\n    };\n  }\n\n  const snapshot = await readUtilityLearningSnapshot(options.memoryDir, options.utilityTelemetryDir);\n  const weights = snapshot?.weights ?? [];\n  return {\n    enabled: true,\n    promotionByOutcomeEnabled: options.promotionByOutcomeEnabled === true,\n    rootDir,\n    statePath,\n    snapshot,\n    weights: {\n      total: weights.length,\n      positive: weights.filter((entry) => entry.learnedWeight > 0).length,\n      negative: weights.filter((entry) => entry.learnedWeight < 0).length,\n      zero: weights.filter((entry) => entry.learnedWeight === 0).length,\n      latestUpdatedAt: snapshot?.updatedAt,\n    },\n  };\n}\n"],"mappings":"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","names":[]}