@remnic/core 1.0.2 → 1.1.0

package/dist/{chunk-QY2BHY5O.js → chunk-MVTHXUBX.js}

@@ -1,8 +1,11 @@
 import {
-  canReadNamespace,
-  canWriteNamespace,
-  resolvePrincipal
-} from "./chunk-N5AKDXAI.js";
+  buildProposedActions,
+  buildQualityScore,
+  groupActionsByStatus,
+  listMemoryGovernanceRuns,
+  readMemoryGovernanceRunArtifact,
+  runMemoryGovernance
+} from "./chunk-ITRLGI2T.js";
 import {
   getTrustZoneStoreStatus,
   isTrustZoneName,
@@ -13,23 +16,39 @@ import {
   summarizeTrustZonePromotionReadiness
 } from "./chunk-EQINRHYR.js";
 import {
-  buildProposedActions,
-  buildQualityScore,
-  groupActionsByStatus,
-  listMemoryGovernanceRuns,
-  readMemoryGovernanceRunArtifact,
-  runMemoryGovernance
-} from "./chunk-J3BT33K7.js";
+  persistExplicitCapture,
+  queueExplicitCaptureForReview,
+  validateExplicitCaptureInput
+} from "./chunk-QDYXG4CS.js";
 import {
   wrapWorkLayerContext
 } from "./chunk-EEQLFRUM.js";
 import {
-  parseEntityFile
-} from "./chunk-QWUUMMIK.js";
+  buildProcedurePersistBody,
+  normalizeProcedureSteps
+} from "./chunk-QDW3E4RD.js";
 import {
-  inferMemoryStatus,
-  toMemoryPathRel
-} from "./chunk-TP4FZJIZ.js";
+  filterTrajectoriesByLookbackDays,
+  readCausalTrajectoryRecords
+} from "./chunk-4NRAJUDS.js";
+import {
+  canReadNamespace,
+  canWriteNamespace,
+  resolvePrincipal
+} from "./chunk-N5AKDXAI.js";
+import {
+  AccessIdempotencyStore,
+  hashAccessIdempotencyPayload
+} from "./chunk-XKECPATV.js";
+import {
+  FileCalendarSource,
+  buildBriefing,
+  parseBriefingFocus,
+  parseBriefingWindow
+} from "./chunk-4LACOVZX.js";
+import {
+  parseEntityFile
+} from "./chunk-GV6NLQ4X.js";
 import {
   normalizeProjectionPreview,
   normalizeProjectionTags
@@ -38,17 +57,12 @@ import {
   getMemoryProjectionPath
 } from "./chunk-BOUYNNYD.js";
 import {
-  persistExplicitCapture,
-  queueExplicitCaptureForReview,
-  validateExplicitCaptureInput
-} from "./chunk-YNCQ7E4M.js";
+  inferMemoryStatus,
+  toMemoryPathRel
+} from "./chunk-TP4FZJIZ.js";
 import {
   log
-} from "./chunk-KWBU5S5U.js";
-import {
-  AccessIdempotencyStore,
-  hashAccessIdempotencyPayload
-} from "./chunk-XKECPATV.js";
+} from "./chunk-2ODBA7MQ.js";
 
 // src/access-service.ts
 import { stat } from "fs/promises";
@@ -662,6 +676,102 @@ async function importWorkBoardSnapshot(options) {
   return { created, updated };
 }
 
+// src/procedural/procedure-miner.ts
+var PROCEDURE_CLUSTER_ATTR_MAX = 500;
+function clusterKey(record) {
+  const goal = record.goal.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 120);
+  const refs = [...record.entityRefs ?? []].map((r) => r.trim().toLowerCase()).sort();
+  return `${goal}|${refs.join(",")}`;
+}
+function successRate(group) {
+  if (group.length === 0) return 0;
+  const ok = group.filter((g) => g.outcomeKind === "success" || g.outcomeKind === "partial").length;
+  return ok / group.length;
+}
+function pseudoStepsFromCluster(group) {
+  const sentences = [];
+  const pushUnique = (raw) => {
+    const t = raw.trim();
+    if (t.length < 8) return;
+    if (!sentences.includes(t)) sentences.push(t);
+  };
+  for (const g of group) {
+    const parts = [g.actionSummary, g.observationSummary, g.outcomeSummary].join(" ").split(/[.!?]\s+|;|\n+/).map((s) => s.trim()).filter((s) => s.length > 12);
+    for (const p of parts) pushUnique(p);
+    if (sentences.length >= 5) break;
+  }
+  if (sentences.length < 2 && group[0]) {
+    pushUnique(`${group[0].goal.trim()} \u2014 confirm prerequisites and context.`);
+    pushUnique("Execute the planned actions, then record the outcome.");
+  }
+  return sentences.slice(0, 6).map((intent, i) => ({
+    order: i + 1,
+    intent
+  }));
+}
+async function hasExistingClusterWrite(storage, cluster) {
+  const clusterKey2 = cluster.slice(0, PROCEDURE_CLUSTER_ATTR_MAX);
+  const memories = await storage.readAllMemories();
+  for (const m of memories) {
+    if (m.frontmatter.category !== "procedure") continue;
+    const c = m.frontmatter.structuredAttributes?.procedure_cluster;
+    if (c === clusterKey2) return true;
+  }
+  return false;
+}
+async function runProcedureMining(options) {
+  const cfg = options.config.procedural;
+  if (!cfg?.enabled) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "procedural_disabled" };
+  }
+  if (cfg.minOccurrences <= 0) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "minOccurrences_zero" };
+  }
+  const trajectoryDir = typeof options.config.causalTrajectoryStoreDir === "string" && options.config.causalTrajectoryStoreDir.trim().length > 0 ? options.config.causalTrajectoryStoreDir.trim() : void 0;
+  const { trajectories } = await readCausalTrajectoryRecords({
+    memoryDir: options.memoryDir,
+    causalTrajectoryStoreDir: trajectoryDir
+  });
+  const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
+  const clusters = /* @__PURE__ */ new Map();
+  for (const t of recent) {
+    const key = clusterKey(t);
+    const arr = clusters.get(key) ?? [];
+    arr.push(t);
+    clusters.set(key, arr);
+  }
+  let clustersProcessed = 0;
+  let proceduresWritten = 0;
+  for (const [key, group] of clusters) {
+    if (group.length < cfg.minOccurrences) continue;
+    const rate = successRate(group);
+    if (rate < cfg.successFloor) continue;
+    clustersProcessed += 1;
+    if (await hasExistingClusterWrite(options.storage, key)) {
+      log.debug(`procedure-miner: skip duplicate cluster key=${key.slice(0, 40)}\u2026`);
+      continue;
+    }
+    const steps = normalizeProcedureSteps(pseudoStepsFromCluster(group));
+    if (steps.length < 2) continue;
+    const title = `When you work on goals like: ${group[0].goal.trim().slice(0, 140)}`;
+    const body = buildProcedurePersistBody(title, steps);
+    const promote = cfg.autoPromoteEnabled === true && group.length >= cfg.autoPromoteOccurrences && rate >= cfg.successFloor;
+    await options.storage.writeMemory("procedure", body, {
+      source: "procedure-miner",
+      status: promote ? "active" : "pending_review",
+      tags: ["procedure-miner", "causal-trajectory"],
+      structuredAttributes: {
+        procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
+        trajectory_ids: group.map((g) => g.trajectoryId).join(",").slice(0, 1900),
+        trajectory_count: String(group.length),
+        success_rate: rate.toFixed(4)
+      }
+    });
+    proceduresWritten += 1;
+  }
+  return { clustersProcessed, proceduresWritten };
+}
+
 // src/access-service.ts
 var EngramAccessInputError = class extends Error {
 };
@@ -785,6 +895,9 @@ var EngramAccessService = class {
   orchestrator;
   idempotency;
   idempotencyLocks = /* @__PURE__ */ new Map();
+  get briefingEnabled() {
+    return this.orchestrator.config.briefing?.enabled === true;
+  }
   resolveNamespace(namespace) {
     const requested = namespace?.trim();
     if (!requested) return this.orchestrator.config.defaultNamespace;
@@ -825,7 +938,16 @@ var EngramAccessService = class {
   }
   resolveReadableNamespace(namespace, principal) {
     const resolved = this.resolveNamespace(namespace);
-    if (principal && !canReadNamespace(principal, resolved, this.orchestrator.config)) {
+    const namespacesEnabled = this.orchestrator.config.namespacesEnabled;
+    if (!namespacesEnabled) {
+      return resolved;
+    }
+    if (!principal) {
+      throw new EngramAccessInputError(
+        "authentication required: namespaces are enabled and no principal was supplied"
+      );
+    }
+    if (!canReadNamespace(principal, resolved, this.orchestrator.config)) {
       throw new EngramAccessInputError(`namespace is not readable: ${resolved}`);
     }
     return resolved;
@@ -969,6 +1091,62 @@ var EngramAccessService = class {
     }
     return this.orchestrator.generateDaySummary(memories);
   }
+  /**
+   * Build a daily context briefing. Gracefully degrades when the OpenAI key
+   * or Responses API is unavailable — never throws for LLM-related problems.
+   */
+  async briefing(request) {
+    const config = this.orchestrator.config;
+    if (!config.briefing.enabled) {
+      throw new EngramAccessInputError("briefing is disabled");
+    }
+    const namespace = this.resolveReadableNamespace(request.namespace, request.principal);
+    const storage = await this.orchestrator.getStorage(namespace);
+    const token = typeof request.since === "string" && request.since.trim().length > 0 ? request.since.trim() : config.briefing.defaultWindow;
+    const window = parseBriefingWindow(token);
+    if (!window) {
+      throw new EngramAccessInputError(`invalid briefing window: ${token}`);
+    }
+    const rawFocus = typeof request.focus === "string" ? request.focus.trim() : "";
+    let focus = null;
+    if (rawFocus.length > 0) {
+      focus = parseBriefingFocus(rawFocus);
+      if (!focus) {
+        throw new EngramAccessInputError(
+          `invalid briefing focus filter: ${request.focus}`
+        );
+      }
+    }
+    const SUPPORTED_FORMATS = ["markdown", "json"];
+    if (typeof request.format === "string" && !SUPPORTED_FORMATS.includes(request.format)) {
+      throw new EngramAccessInputError(
+        `unsupported briefing format: "${request.format}". Accepted: ${SUPPORTED_FORMATS.join(", ")}.`
+      );
+    }
+    const format = request.format === "json" ? "json" : request.format === "markdown" ? "markdown" : config.briefing.defaultFormat;
+    const maxFollowups = typeof request.maxFollowups === "number" && Number.isFinite(request.maxFollowups) ? Math.max(0, Math.min(10, Math.floor(request.maxFollowups))) : config.briefing.maxFollowups;
+    const calendarSource = config.briefing.calendarSource ? new FileCalendarSource(config.briefing.calendarSource) : void 0;
+    const result = await buildBriefing({
+      storage,
+      namespace,
+      window,
+      focus,
+      calendarSource,
+      maxFollowups,
+      allowLlm: config.briefing.llmFollowups,
+      openaiApiKey: config.openaiApiKey,
+      openaiBaseUrl: config.openaiBaseUrl,
+      model: config.model
+    });
+    return {
+      format,
+      window: result.window,
+      namespace,
+      markdown: result.markdown,
+      json: result.json,
+      followupsUnavailableReason: result.followupsUnavailableReason
+    };
+  }
   async recall(request) {
     const query = request.query.trim();
     if (query.length === 0) {
@@ -1320,14 +1498,15 @@ var EngramAccessService = class {
     for (const name of names) {
       const raw = await storage.readEntity(name);
       if (!raw) continue;
-      const entity = parseEntityFile(raw);
+      const entity = parseEntityFile(raw, this.orchestrator.config.entitySchemas);
       if (query) {
         const haystack = [
           entity.name,
           entity.type,
-          entity.summary ?? "",
+          entity.synthesis || entity.summary || "",
           ...entity.aliases,
-          ...entity.facts
+          ...entity.facts,
+          ...(entity.structuredSections ?? []).flatMap((section) => [section.title, ...section.facts])
         ].join("\n").toLowerCase();
         if (!haystack.includes(query)) continue;
       }
@@ -1335,7 +1514,7 @@ var EngramAccessService = class {
         name: entity.name,
         type: entity.type,
         updated: entity.updated,
-        summary: entity.summary,
+        summary: entity.synthesis || entity.summary,
         aliases: entity.aliases
       });
     }
@@ -1358,7 +1537,7 @@ var EngramAccessService = class {
     return {
       found: true,
       namespace: resolvedNamespace,
-      entity: parseEntityFile(raw)
+      entity: parseEntityFile(raw, this.orchestrator.config.entitySchemas)
     };
   }
   async reviewQueue(runId, namespace, principal) {
@@ -1502,13 +1681,25 @@ var EngramAccessService = class {
       request.authenticatedPrincipal ?? principal
     );
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const mode = request.mode === "apply" ? "apply" : "shadow";
+    const boundedBatchSize = typeof request.batchSize === "number" && Number.isFinite(request.batchSize) ? Math.max(1, Math.floor(request.batchSize)) : void 0;
     const result = await runMemoryGovernance({
       memoryDir: storage.dir,
-      mode: request.mode === "apply" ? "apply" : "shadow",
+      mode,
       recentDays: typeof request.recentDays === "number" && Number.isFinite(request.recentDays) ? Math.max(1, Math.floor(request.recentDays)) : void 0,
       maxMemories: typeof request.maxMemories === "number" && Number.isFinite(request.maxMemories) ? Math.max(1, Math.floor(request.maxMemories)) : void 0,
-      batchSize: typeof request.batchSize === "number" && Number.isFinite(request.batchSize) ? Math.max(1, Math.floor(request.batchSize)) : void 0
+      batchSize: boundedBatchSize
     });
+    if (mode === "apply") {
+      try {
+        await this.orchestrator.processEntitySynthesisQueue(
+          resolvedNamespace,
+          Math.min(boundedBatchSize ?? 5, 5)
+        );
+      } catch (error) {
+        log.debug(`governanceRun: entity synthesis refresh failed after governance apply: ${error}`);
+      }
+    }
     return {
       namespace: resolvedNamespace,
       runId: result.runId,
@@ -1521,6 +1712,25 @@ var EngramAccessService = class {
       reportPath: result.reportPath
     };
   }
+  async procedureMiningRun(request, principal) {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const result = await runProcedureMining({
+      memoryDir: storage.dir,
+      storage,
+      config: this.orchestrator.config
+    });
+    return {
+      namespace: resolvedNamespace,
+      clustersProcessed: result.clustersProcessed,
+      proceduresWritten: result.proceduresWritten,
+      skippedReason: result.skippedReason
+    };
+  }
   async trustZoneStatus(namespace, principal) {
     const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
@@ -2367,6 +2577,59 @@ ${next}`);
       }
     };
   }
+  /**
+   * Record citation usage from an observed oai-mem-citation block.
+   * For each citation entry, extract the memory ID from the path and
+   * increment its access tracking via the orchestrator. Returns the
+   * count of submitted IDs and the count of IDs that matched real memories.
+   */
+  async recordCitationUsage(request) {
+    if (request.entries.length === 0) return { submitted: 0, matched: 0 };
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionId,
+      request.authenticatedPrincipal
+    );
+    const memoryIds = [];
+    for (const entry of request.entries) {
+      const basename = entry.path.split("/").pop() ?? entry.path;
+      const id = basename.endsWith(".md") ? basename.slice(0, -3) : basename;
+      if (id.length > 0) {
+        memoryIds.push(id);
+      }
+    }
+    if (memoryIds.length === 0) return { submitted: 0, matched: 0 };
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const existingIds = await storage.filterExistingMemoryIds(memoryIds);
+    const matchedIds = memoryIds.filter((id) => existingIds.has(id));
+    if (matchedIds.length > 0) {
+      try {
+        this.orchestrator.trackMemoryAccess(matchedIds);
+      } catch {
+        log.debug("citation usage tracking: failed to record access for cited memories");
+      }
+    }
+    return { submitted: memoryIds.length, matched: matchedIds.length };
+  }
+  // ── Contradiction Review (issue #520) ──────────────────────────────────────
+  get memoryDir() {
+    return this.orchestrator.config.memoryDir;
+  }
+  get storageRef() {
+    return this.orchestrator.storage;
+  }
+  get configRef() {
+    return this.orchestrator.config;
+  }
+  get localLlmRef() {
+    return this.orchestrator.localLlm ?? null;
+  }
+  get fallbackLlmRef() {
+    return null;
+  }
+  get embeddingLookupRef() {
+    return void 0;
+  }
 };
 
 export {
@@ -2375,4 +2638,4 @@ export {
   ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
   EngramAccessService
 };
-//# sourceMappingURL=chunk-QY2BHY5O.js.map
+//# sourceMappingURL=chunk-MVTHXUBX.js.map