@remnic/core 9.69.55 → 9.69.57

package/dist/chunk-CS2JO77A.js

@@ -0,0 +1,95 @@
+import {
+  defineOperation
+} from "./chunk-4ALOINQ4.js";
+import {
+  EngramAccessInputError
+} from "./chunk-3MUKQQ7A.js";
+
+// src/recall-navigation-operations.ts
+import { z } from "zod";
+function stripNulls(data) {
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data;
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (value !== null) cleaned[key] = value;
+    }
+    return cleaned;
+  }
+  return data;
+}
+function strictSchema(shape) {
+  return z.preprocess(stripNulls, z.object(shape).passthrough());
+}
+var str = z.string().optional();
+function optStr(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function optInt(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && Number.isFinite(Number(value))) return Number(value);
+  return void 0;
+}
+function reqStr(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramAccessInputError(`${field} is required`);
+  }
+  return value;
+}
+var baseShape = {
+  memoryId: z.string(),
+  sessionKey: z.string(),
+  namespace: str
+};
+defineOperation({
+  name: "memory_expand",
+  description: "Re-render one already-served recall result at a deeper disclosure level (chunk \u2192 section \u2192 raw).",
+  schema: strictSchema({ ...baseShape, disclosure: z.enum(["chunk", "section", "raw"]).optional() }),
+  handler: async (input, ctx) => {
+    const disclosure = optStr(input.disclosure);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "expand",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...disclosure === "chunk" || disclosure === "section" || disclosure === "raw" ? { disclosure } : {},
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal
+      })
+    };
+  }
+});
+defineOperation({
+  name: "memory_traverse",
+  description: "Follow typed frontmatter links from an already-served recall result; neighbors return as chunk-level summaries.",
+  schema: strictSchema({
+    ...baseShape,
+    relation: z.enum([
+      "supports",
+      "contradicts",
+      "elaborates",
+      "causes",
+      "caused_by",
+      "supersedes",
+      "follows",
+      "references",
+      "related"
+    ]).optional(),
+    limit: z.union([z.number(), z.string()]).optional()
+  }),
+  handler: async (input, ctx) => {
+    const relation = optStr(input.relation);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "traverse",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...relation !== void 0 ? { relation } : {},
+        limit: optInt(input.limit),
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal
+      })
+    };
+  }
+});
+//# sourceMappingURL=chunk-CS2JO77A.js.map

package/dist/chunk-DTABICJ3.js

@@ -0,0 +1,549 @@
+import {
+  StorageManager
+} from "./chunk-S2OBXHMN.js";
+import {
+  composeMemoryEnvelope
+} from "./chunk-GDYU6VF4.js";
+import {
+  isErrnoCode
+} from "./chunk-KNA3BXXL.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/semantic-rule-promotion.ts
+import { createHash, randomUUID } from "crypto";
+import { link, mkdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import path from "path";
+import { setTimeout as sleep } from "timers/promises";
+var PROMOTION_LOCK_TIMEOUT_MS = 10 * 60 * 1e3;
+var PROMOTION_LOCK_RETRY_MS = 25;
+var PROMOTION_LOCK_STALE_MS = 5 * 60 * 1e3;
+var PROMOTION_LOCK_OWNERLESS_GRACE_MS = 1e3;
+var PROMOTION_LOCK_HEARTBEAT_MS = 30 * 1e3;
+var testHooks = null;
+function setSemanticRulePromotionTestHooks(hooks) {
+  testHooks = hooks;
+}
+function promotionLockTimeoutMs() {
+  return testHooks?.lockTimeoutMs ?? PROMOTION_LOCK_TIMEOUT_MS;
+}
+function promotionLockRetryMs() {
+  return testHooks?.lockRetryMs ?? PROMOTION_LOCK_RETRY_MS;
+}
+function promotionLockStaleMs() {
+  return testHooks?.staleLockMs ?? PROMOTION_LOCK_STALE_MS;
+}
+function promotionLockOwnerlessGraceMs() {
+  return testHooks?.ownerlessGraceMs ?? PROMOTION_LOCK_OWNERLESS_GRACE_MS;
+}
+function promotionLockHeartbeatMs() {
+  return testHooks?.heartbeatMs ?? PROMOTION_LOCK_HEARTBEAT_MS;
+}
+function promotionLockDir(memoryDir, ruleKey) {
+  const digest = createHash("sha256").update(ruleKey).digest("hex");
+  return path.join(path.resolve(memoryDir), "state", "semantic-rule-promotion-locks", `${digest}.lock`);
+}
+function promotionHeartbeatPath(lockDir, token) {
+  return path.join(lockDir, `heartbeat.${token}.json`);
+}
+function promotionReapDir(lockDir) {
+  return `${lockDir}.reap`;
+}
+function promotionReleaseDir(lockDir) {
+  return `${lockDir}.release`;
+}
+async function pathExists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return false;
+    throw err;
+  }
+}
+async function readPromotionLockOwner(lockDir) {
+  try {
+    const owner = JSON.parse(await readFile(path.join(lockDir, "owner.json"), "utf8"));
+    const acquiredAtMs = typeof owner.acquiredAt === "string" ? Date.parse(owner.acquiredAt) : Number.NaN;
+    const heartbeatAtMs = typeof owner.heartbeatAt === "string" ? Date.parse(owner.heartbeatAt) : Number.NaN;
+    return {
+      acquiredAtMs: Number.isFinite(acquiredAtMs) ? acquiredAtMs : null,
+      heartbeatAtMs: Number.isFinite(heartbeatAtMs) ? heartbeatAtMs : null,
+      token: typeof owner.token === "string" ? owner.token : null
+    };
+  } catch {
+    return {
+      acquiredAtMs: null,
+      heartbeatAtMs: null,
+      token: null
+    };
+  }
+}
+async function tryWritePromotionLockOwner(lockDir, owner) {
+  const ownerPath = path.join(lockDir, "owner.json");
+  const tempPath = path.join(lockDir, `owner.${process.pid}.${randomUUID()}.tmp`);
+  await testHooks?.beforeLockOwnerWrite?.(lockDir, owner.token);
+  try {
+    await writeFile(
+      tempPath,
+      `${JSON.stringify(
+        {
+          pid: process.pid,
+          token: owner.token,
+          acquiredAt: owner.acquiredAt
+        },
+        null,
+        2
+      )}
+`
+    );
+    await link(tempPath, ownerPath);
+    return true;
+  } catch (err) {
+    if (isErrnoCode(err, "EEXIST") || isErrnoCode(err, "ENOENT")) {
+      return false;
+    }
+    throw err;
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+async function writePromotionLockHeartbeat(lockDir, token) {
+  const heartbeatPath = promotionHeartbeatPath(lockDir, token);
+  const tempPath = path.join(lockDir, `heartbeat.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(
+      tempPath,
+      `${JSON.stringify(
+        {
+          pid: process.pid,
+          token,
+          heartbeatAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )}
+`
+    );
+    await rename(tempPath, heartbeatPath);
+  } catch (err) {
+    await rm(tempPath, { force: true });
+    throw err;
+  }
+}
+async function refreshPromotionLockHeartbeat(lockDir, token) {
+  const owner = await readPromotionLockOwner(lockDir);
+  if (owner.token !== token) {
+    return false;
+  }
+  await writePromotionLockHeartbeat(lockDir, token);
+  return true;
+}
+async function readPromotionLockHeartbeatMs(lockDir, token) {
+  if (!token) return null;
+  try {
+    return (await stat(promotionHeartbeatPath(lockDir, token))).mtimeMs;
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return null;
+    throw err;
+  }
+}
+async function reapAbandonedPromotionGuard(guardDir) {
+  let reapStat;
+  try {
+    reapStat = await stat(guardDir);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return false;
+    throw err;
+  }
+  if (Date.now() - reapStat.mtimeMs < promotionLockStaleMs()) {
+    return false;
+  }
+  const staleReapDir = `${guardDir}.stale-${process.pid}-${randomUUID()}`;
+  try {
+    await rename(guardDir, staleReapDir);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return false;
+    throw err;
+  }
+  await rm(staleReapDir, { recursive: true, force: true });
+  return true;
+}
+async function reapAbandonedPromotionGuards(lockDir) {
+  const reapedReapGuard = await reapAbandonedPromotionGuard(promotionReapDir(lockDir));
+  const reapedReleaseGuard = await reapAbandonedPromotionGuard(promotionReleaseDir(lockDir));
+  return reapedReapGuard || reapedReleaseGuard;
+}
+async function hasPromotionGuard(lockDir) {
+  return await pathExists(promotionReapDir(lockDir)) || await pathExists(promotionReleaseDir(lockDir));
+}
+async function reapStalePromotionLock(lockDir) {
+  if (await hasPromotionGuard(lockDir)) {
+    await reapAbandonedPromotionGuards(lockDir);
+    return false;
+  }
+  const reapDir = promotionReapDir(lockDir);
+  try {
+    await mkdir(reapDir);
+  } catch (err) {
+    if (isErrnoCode(err, "EEXIST")) return false;
+    throw err;
+  }
+  let staleDir = null;
+  try {
+    return await reapStalePromotionLockWithGuard(lockDir, (value) => {
+      staleDir = value;
+    });
+  } finally {
+    if (staleDir) {
+      await rm(staleDir, { recursive: true, force: true });
+    }
+    await rm(reapDir, { recursive: true, force: true });
+  }
+}
+async function reapStalePromotionLockWithGuard(lockDir, setStaleDir) {
+  let lockStat;
+  try {
+    lockStat = await stat(lockDir);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return false;
+    throw err;
+  }
+  const owner = await readPromotionLockOwner(lockDir);
+  const heartbeatMs = await readPromotionLockHeartbeatMs(lockDir, owner.token);
+  const lockedAtMs = heartbeatMs ?? owner.heartbeatAtMs ?? owner.acquiredAtMs ?? lockStat.mtimeMs;
+  const ownerlessLock = owner.token === null && owner.heartbeatAtMs === null && owner.acquiredAtMs === null;
+  const staleAfterMs = ownerlessLock ? promotionLockOwnerlessGraceMs() : promotionLockStaleMs();
+  if (Date.now() - lockedAtMs < staleAfterMs) {
+    return false;
+  }
+  const staleDir = `${lockDir}.stale-${process.pid}-${randomUUID()}`;
+  try {
+    await rename(lockDir, staleDir);
+    setStaleDir(staleDir);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return false;
+    throw err;
+  }
+  const staleOwner = await readPromotionLockOwner(staleDir);
+  const staleHeartbeatMs = await readPromotionLockHeartbeatMs(staleDir, staleOwner.token);
+  const staleLockedAtMs = staleHeartbeatMs ?? staleOwner.heartbeatAtMs ?? staleOwner.acquiredAtMs ?? lockStat.mtimeMs;
+  const staleOwnerlessLock = staleOwner.token === null && staleOwner.heartbeatAtMs === null && staleOwner.acquiredAtMs === null;
+  const staleAfterRecheckMs = staleOwnerlessLock ? promotionLockOwnerlessGraceMs() : promotionLockStaleMs();
+  if (Date.now() - staleLockedAtMs < staleAfterRecheckMs) {
+    await rename(staleDir, lockDir);
+    setStaleDir("");
+    return false;
+  }
+  await rm(staleDir, { recursive: true, force: true });
+  setStaleDir("");
+  return true;
+}
+async function releasePromotionLock(lockDir, token) {
+  const releaseDir = promotionReleaseDir(lockDir);
+  const deadline = Date.now() + promotionLockTimeoutMs();
+  await testHooks?.beforeLockRelease?.(lockDir, token);
+  for (; ; ) {
+    try {
+      await mkdir(releaseDir);
+      break;
+    } catch (err) {
+      if (!isErrnoCode(err, "EEXIST")) {
+        throw err;
+      }
+      const owner = await readPromotionLockOwner(lockDir);
+      if (owner.token !== token) {
+        return;
+      }
+      await reapAbandonedPromotionGuard(releaseDir);
+      if (Date.now() >= deadline) {
+        throw new Error("Timed out releasing semantic rule promotion lock");
+      }
+      await sleep(promotionLockRetryMs());
+    }
+  }
+  try {
+    const owner = await readPromotionLockOwner(lockDir);
+    if (owner.token !== token) {
+      return;
+    }
+    await rm(lockDir, { recursive: true, force: true });
+  } finally {
+    await rm(releaseDir, { recursive: true, force: true });
+  }
+}
+async function withPromotionLock(memoryDir, ruleKey, fn) {
+  const lockDir = promotionLockDir(memoryDir, ruleKey);
+  const lockRoot = path.dirname(lockDir);
+  const deadline = Date.now() + promotionLockTimeoutMs();
+  let lockToken = null;
+  let heartbeat = null;
+  await mkdir(lockRoot, { recursive: true });
+  for (; ; ) {
+    try {
+      if (await hasPromotionGuard(lockDir)) {
+        await reapAbandonedPromotionGuards(lockDir);
+        if (Date.now() >= deadline) {
+          throw new Error("Timed out acquiring semantic rule promotion lock");
+        }
+        await sleep(promotionLockRetryMs());
+        continue;
+      }
+      await mkdir(lockDir);
+      if (await hasPromotionGuard(lockDir)) {
+        await reapAbandonedPromotionGuards(lockDir);
+        if (Date.now() >= deadline) {
+          throw new Error("Timed out acquiring semantic rule promotion lock");
+        }
+        await sleep(promotionLockRetryMs());
+        continue;
+      }
+      try {
+        lockToken = randomUUID();
+        const lockOwner = {
+          token: lockToken,
+          acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        const wroteOwner = await tryWritePromotionLockOwner(lockDir, lockOwner);
+        if (!wroteOwner) {
+          lockToken = null;
+          if (Date.now() >= deadline) {
+            throw new Error("Timed out acquiring semantic rule promotion lock");
+          }
+          await sleep(promotionLockRetryMs());
+          continue;
+        }
+        await writePromotionLockHeartbeat(lockDir, lockToken);
+        const heartbeatToken = lockToken;
+        const heartbeatMs = promotionLockHeartbeatMs();
+        if (heartbeatMs > 0) {
+          heartbeat = setInterval(() => {
+            void refreshPromotionLockHeartbeat(lockDir, heartbeatToken).then((ownsLock) => {
+              if (!ownsLock && heartbeat) {
+                clearInterval(heartbeat);
+                heartbeat = null;
+              }
+            }).catch(() => void 0);
+          }, heartbeatMs);
+        }
+      } catch (err) {
+        lockToken = null;
+        if (heartbeat) {
+          clearInterval(heartbeat);
+          heartbeat = null;
+        }
+        await rm(lockDir, { recursive: true, force: true });
+        throw err;
+      }
+      break;
+    } catch (err) {
+      if (!isErrnoCode(err, "EEXIST")) {
+        throw err;
+      }
+      if (await reapStalePromotionLock(lockDir)) {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("Timed out acquiring semantic rule promotion lock");
+      }
+      await sleep(promotionLockRetryMs());
+    }
+  }
+  const assertHeld = async () => {
+    if (!lockToken) {
+      throw new Error("Semantic rule promotion lock is no longer held");
+    }
+    const ownsLock = await refreshPromotionLockHeartbeat(lockDir, lockToken);
+    if (!ownsLock) {
+      throw new Error("Semantic rule promotion lock is no longer held");
+    }
+  };
+  let hasResult = false;
+  let result;
+  let callbackError;
+  let releaseError;
+  try {
+    await assertHeld();
+    result = await fn({
+      assertHeld,
+      beforePromotedRuleWrite: async () => {
+        if (!lockToken) {
+          throw new Error("Semantic rule promotion lock is no longer held");
+        }
+        await testHooks?.beforePromotedRuleWrite?.(lockDir, lockToken);
+        await assertHeld();
+      }
+    });
+    hasResult = true;
+  } catch (err) {
+    callbackError = err;
+  } finally {
+    if (heartbeat) {
+      clearInterval(heartbeat);
+    }
+    if (lockToken) {
+      try {
+        await releasePromotionLock(lockDir, lockToken);
+      } catch (err) {
+        if (!hasResult && !callbackError) {
+          releaseError = err;
+        }
+      }
+    }
+  }
+  if (releaseError) {
+    throw releaseError;
+  }
+  if (callbackError) {
+    throw callbackError;
+  }
+  return result;
+}
+function normalizeRuleWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function stripTrailingClausePunctuation(value) {
+  let end = value.length;
+  while (end > 0) {
+    const ch = value[end - 1];
+    if (ch === "," || ch === ":" || ch === ";") end--;
+    else break;
+  }
+  return value.slice(0, end).trim();
+}
+function canonicalizeRuleContent(value) {
+  return extractExplicitIfThenRule(value) ?? normalizeRuleWhitespace(value);
+}
+function canonicalizeRuleKey(value) {
+  return canonicalizeRuleContent(value).toLowerCase();
+}
+function extractExplicitIfThenRule(content) {
+  const match = content.match(/\bif\b([\s\S]+?)\bthen\b([\s\S]+?)(?:[.!?](?:\s|$)|$)/i);
+  if (!match) return null;
+  const condition = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[1] ?? ""));
+  const outcome = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[2] ?? ""));
+  if (condition.length === 0 || outcome.length === 0) return null;
+  return `IF ${condition} THEN ${outcome}.`;
+}
+function promotionConfidence(memory) {
+  const base = Number.isFinite(memory.frontmatter.confidence) ? memory.frontmatter.confidence : 0.8;
+  return Math.max(0.6, Math.min(0.98, base));
+}
+function promotionTags(memory) {
+  return Array.from(/* @__PURE__ */ new Set([...memory.frontmatter.tags ?? [], "semantic-rule", "promoted-rule"]));
+}
+function buildSupportLinks(sourceMemoryId, confidence) {
+  return [
+    {
+      targetId: sourceMemoryId,
+      linkType: "supports",
+      strength: confidence,
+      reason: "Promoted from verified episodic memory"
+    }
+  ];
+}
+async function promoteSemanticRuleFromMemory(options) {
+  const report = {
+    enabled: options.enabled,
+    dryRun: options.dryRun === true,
+    promoted: [],
+    skipped: []
+  };
+  if (!options.enabled) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "disabled"
+    });
+    return report;
+  }
+  const storage = new StorageManager(options.memoryDir);
+  const sourceMemory = await storage.getMemoryById(options.sourceMemoryId);
+  if (!sourceMemory) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-missing"
+    });
+    return report;
+  }
+  if (sourceMemory.frontmatter.status === "forgotten") {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-forgotten"
+    });
+    return report;
+  }
+  if (sourceMemory.frontmatter.status === "archived" || sourceMemory.frontmatter.memoryKind !== "episode") {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-not-episode"
+    });
+    return report;
+  }
+  const content = extractExplicitIfThenRule(sourceMemory.content);
+  if (!content) {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "no-explicit-rule"
+    });
+    return report;
+  }
+  const ruleKey = canonicalizeRuleKey(content);
+  const confidence = promotionConfidence(sourceMemory);
+  const candidateBase = {
+    sourceMemoryId: options.sourceMemoryId,
+    content,
+    confidence,
+    tags: promotionTags(sourceMemory),
+    memoryKind: "note",
+    lineage: [options.sourceMemoryId]
+  };
+  return withPromotionLock(options.memoryDir, ruleKey, async (lock) => {
+    storage.invalidateAllMemoriesCacheForDir();
+    const existingRule = (await storage.readAllMemories()).find(
+      (memory) => memory.frontmatter.category === "rule" && memory.frontmatter.status !== "archived" && memory.frontmatter.status !== "forgotten" && canonicalizeRuleKey(memory.content) === ruleKey
+    );
+    if (existingRule) {
+      report.skipped.push({
+        sourceMemoryId: options.sourceMemoryId,
+        reason: "duplicate-rule",
+        existingRuleId: existingRule.frontmatter.id
+      });
+      return report;
+    }
+    if (options.dryRun === true) {
+      await lock.assertHeld();
+      report.promoted.push({
+        id: `dry-run:${options.sourceMemoryId}`,
+        ...candidateBase
+      });
+      return report;
+    }
+    await lock.beforePromotedRuleWrite();
+    const ruleEnvelope = composeMemoryEnvelope(
+      { content, category: "rule", confidence, tags: candidateBase.tags, origin: sourceMemory.frontmatter.origin },
+      { source: "semantic-rule-promotion" },
+      { salvage: true }
+    );
+    if (ruleEnvelope.salvageNotes.length > 0) {
+      log.warn(`rule-promotion write salvaged invalid fields: ${ruleEnvelope.salvageNotes.join("; ")}`);
+    }
+    const { id } = await storage.writeSealedMemory(ruleEnvelope, {
+      lineage: candidateBase.lineage,
+      sourceMemoryId: options.sourceMemoryId,
+      memoryKind: "note",
+      links: buildSupportLinks(options.sourceMemoryId, confidence)
+    });
+    report.promoted.push({
+      id,
+      ...candidateBase
+    });
+    return report;
+  });
+}
+
+export {
+  setSemanticRulePromotionTestHooks,
+  promoteSemanticRuleFromMemory
+};
+//# sourceMappingURL=chunk-DTABICJ3.js.map