@remnic/core 9.65.7 → 9.65.8

package/src/config.ts

@@ -43,12 +43,10 @@ import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
 import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
 import { parseProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
+import { parseActiveContextFields } from "./active-context-config.js";
 import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
-import {
-  parseContradictionLocalizationConfig,
-  parseContradictionScanConfig,
-} from "./contradiction-config.js";
+import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
 import {
@@ -699,7 +697,6 @@ function resolveMemoryOsPreset(value: unknown): MemoryOsPresetName | undefined {
   }
   return MEMORY_OS_PRESET_ALIASES[normalized];
 }
-
 export function parseConfig(
   raw: unknown,
   rawOperatorConfig?: Record<string, unknown> | null,
@@ -3306,6 +3303,7 @@ export function parseConfig(
       typeof cfg.maxCompressionTokensPerHour === "number"
         ? Math.max(0, Math.floor(cfg.maxCompressionTokensPerHour))
         : 1500,
+    ...parseActiveContextFields(cfg),
     behaviorLoopAutoTuneEnabled: cfg.behaviorLoopAutoTuneEnabled === true,
     behaviorLoopLearningWindowDays:
       typeof cfg.behaviorLoopLearningWindowDays === "number"

package/src/context-summary.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure context summary seam (issue #2347).
+ *
+ * The only shared summary path: `LcmSummarizer` and active-context
+ * transforms both call `summarizeContextPure`. No DAG writes, no model
+ * client construction — callers inject the model seam (`SummarizeFn`).
+ */
+import { looksLikeMechanicalTelemetryTranscript } from "./telemetry-transcript.js";
+import { estimateTokenCount } from "./token-estimate.js";
+
+/** Model seam injected by the caller (orchestrator LLM path or a test stub). */
+export type SummarizeFn = (
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+) => Promise<string | null>;
+
+export type ContextSummaryMethod = "deterministic" | "llm" | "auto";
+
+export interface PureContextSummaryResult {
+  text: string;
+  method: "llm" | "deterministic";
+  /** True when the requested path degraded (auto mode only). */
+  fallback: boolean;
+  modelUsed?: string;
+  /**
+   * Escalation level preserved for LCM callers: 0 normal LLM, 1 aggressive
+   * LLM, 2 deterministic truncation. Undefined when never escalated.
+   */
+  escalation?: number;
+}
+
+export interface SummarizeContextPureOptions {
+  /** LLM seam. Required for `llm`; without it `auto` degrades to deterministic. */
+  llm?: SummarizeFn;
+  /** Hard ceiling for deterministic truncation output. */
+  deterministicMaxTokens?: number;
+  /** Route obvious mechanical telemetry straight to truncation. */
+  telemetryPrefilterEnabled?: boolean;
+  /** Recorded verbatim in the result for telemetry. */
+  modelUsed?: string;
+}
+
+/** Thrown when `llm` mode cannot produce usable text (no silent fallback). */
+export class ContextSummaryUnavailableError extends Error {
+  constructor(reason: string) {
+    super(`context summary unavailable: ${reason}`);
+    this.name = "ContextSummaryUnavailableError";
+  }
+}
+
+const DEFAULT_DETERMINISTIC_MAX_TOKENS = 256;
+/** LLM output tolerance before an attempt is rejected as too long (LCM parity). */
+const OUTPUT_TOKEN_TOLERANCE = 1.5;
+const MIN_DETERMINISTIC_TOKENS = 1;
+
+/**
+ * Summarize text through the shared seam.
+ *
+ * - `deterministic`: safe truncation only, never throws, never calls the LLM.
+ * - `llm`: exactly one non-aggressive LLM call; failure or unusable output
+ *   throws {@link ContextSummaryUnavailableError} (fallback is not allowed).
+ * - `auto`: escalation ladder (LLM → aggressive LLM → deterministic), with
+ *   `fallback: true` and an `escalation` level on degradation.
+ */
+export async function summarizeContextPure(
+  text: string,
+  targetTokens: number,
+  method: ContextSummaryMethod,
+  options: SummarizeContextPureOptions = {},
+): Promise<PureContextSummaryResult> {
+  const deterministicMaxTokens = Math.max(
+    MIN_DETERMINISTIC_TOKENS,
+    options.deterministicMaxTokens ?? DEFAULT_DETERMINISTIC_MAX_TOKENS,
+  );
+
+  if (method === "deterministic") {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: false,
+    };
+  }
+
+  const usableLlm = options.llm ?? null;
+  if (method === "llm") {
+    if (!usableLlm) {
+      throw new ContextSummaryUnavailableError("no llm seam configured");
+    }
+    const result = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (result === null) {
+      throw new ContextSummaryUnavailableError("llm path failed");
+    }
+    return { text: result, method: "llm", fallback: false, modelUsed: options.modelUsed };
+  }
+
+  // auto
+  if (options.telemetryPrefilterEnabled && looksLikeMechanicalTelemetryTranscript(text)) {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: true,
+      escalation: 2,
+    };
+  }
+
+  if (usableLlm) {
+    const normal = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (normal !== null) {
+      return { text: normal, method: "llm", fallback: false, escalation: 0, modelUsed: options.modelUsed };
+    }
+    const aggressiveTarget = Math.max(32, Math.ceil(targetTokens * 0.5));
+    const aggressive = await attemptLlm(usableLlm, text, aggressiveTarget, true);
+    if (aggressive !== null) {
+      return { text: aggressive, method: "llm", fallback: true, escalation: 1, modelUsed: options.modelUsed };
+    }
+  }
+
+  return {
+    text: deterministicTruncate(text, deterministicMaxTokens),
+    method: "deterministic",
+    fallback: true,
+    escalation: 2,
+  };
+}
+
+/** One LLM attempt; null on error, empty, or over-tolerance output. */
+async function attemptLlm(
+  llm: SummarizeFn,
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+): Promise<string | null> {
+  try {
+    const result = await llm(text, targetTokens, aggressive);
+    if (!result || result.trim().length === 0) return null;
+    if (estimateTokenCount(result) > targetTokens * OUTPUT_TOKEN_TOLERANCE) return null;
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/** Deterministic truncation: first and last sentence, plus middle truncation. */
+export function deterministicTruncate(text: string, maxTokens: number): string {
+  if (maxTokens <= 0 || estimateTokenCount(text) <= maxTokens) return text;
+
+  const sentences = text.split(/(?<=[.!?])\s+/).filter((s) => s.length > 0);
+  if (sentences.length <= 2) return clampToTokenBudget(text, maxTokens);
+
+  const first = sentences[0];
+  const last = sentences[sentences.length - 1];
+  const render = (middle: string[], truncated: boolean): string =>
+    `${first} ${middle.join(" ")}${truncated ? " [...] " : " "}${last}`;
+
+  const base = render([], false);
+  if (estimateTokenCount(base) > maxTokens) return clampToTokenBudget(text, maxTokens);
+  if (estimateTokenCount(render([], true)) > maxTokens) return base;
+
+  const middle: string[] = [];
+  for (let i = 1; i < sentences.length - 1; i++) {
+    const candidate = [...middle, sentences[i]];
+    const truncated = i < sentences.length - 2;
+    if (estimateTokenCount(render(candidate, truncated)) > maxTokens) break;
+    middle.push(sentences[i]);
+  }
+
+  const truncated = middle.length < sentences.length - 2;
+  return clampToTokenBudget(render(middle, truncated), maxTokens);
+}
+
+function clampToTokenBudget(text: string, maxTokens: number): string {
+  const codePoints = [...text];
+  let low = 0;
+  let high = codePoints.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (estimateTokenCount(codePoints.slice(0, mid).join("")) <= maxTokens) low = mid;
+    else high = mid - 1;
+  }
+  return codePoints.slice(0, low).join("");
+}

package/src/index.ts

@@ -1,17 +1,10 @@
 /**
- * @remnic/core
- *
- * Framework-agnostic Remnic memory engine.
- *
- * Exports the orchestrator, config parsing, storage, search,
- * extraction, graph, trust zones, and access layer.
- *
- * This package has ZERO OpenClaw imports — it can be consumed by
- * any host adapter (CLI, HTTP server, MCP server, etc.).
- *
+ * @remnic/core — framework-agnostic Remnic memory engine.
+ * Zero OpenClaw imports. Any host adapter can consume this package.
  */
-
 export { collapseWhitespace, displayWidth, graphemeUnits, padEndDisplay, truncateCodePointSafe, truncateGraphemeSafe } from "./whitespace.js";
+export * from "./context-summary.js";
+export * from "./active-context-transform.js";
 
 // ---------------------------------------------------------------------------
 // Plugin entry resolution

package/src/lcm/summarizer.ts

@@ -1,8 +1,6 @@
-import { log } from "../logger.js";
-import { looksLikeMechanicalTelemetryTranscript } from "../telemetry-transcript.js";
-import { estimateTokenCount } from "../token-estimate.js";
-import type { LcmArchive, LcmMessage } from "./archive.js";
+import { summarizeContextPure, type SummarizeFn } from "../context-summary.js";
 import { estimateTokens } from "./archive.js";
+import type { LcmArchive, LcmMessage } from "./archive.js";
 import type { LcmDag } from "./dag.js";
 
 /** Generate a ULID-like ID (timestamp + random). */
@@ -12,11 +10,9 @@ function generateNodeId(): string {
   return `lcm-${ts}-${rand}`;
 }
 
-export type SummarizeFn = (
-  text: string,
-  targetTokens: number,
-  aggressive: boolean,
-) => Promise<string | null>;
+// `SummarizeFn` moved to the shared pure summary seam (context-summary.ts,
+// #2347); re-exported here for back-compat with existing imports.
+export type { SummarizeFn };
 
 export interface LcmSummarizerConfig {
   leafBatchSize: number;
@@ -145,98 +141,23 @@ export class LcmSummarizer {
   }
 
   /**
-   * Three-level escalation:
-   * 0 = Normal LLM summary
-   * 1 = Aggressive bullet compression
-   * 2 = Deterministic truncation (no LLM)
+   * Three-level escalation, delegated to the shared pure summary seam
+   * (context-summary.ts): 0 = normal LLM, 1 = aggressive, 2 = deterministic.
    */
   private async summarizeWithEscalation(
     text: string,
     targetTokens: number,
   ): Promise<{ text: string; escalation: number }> {
-    const { telemetryPrefilterEnabled } = this.config;
-    if (
-      telemetryPrefilterEnabled &&
-      looksLikeMechanicalTelemetryTranscript(text)
-    ) {
-      return {
-        text: deterministicTruncate(
-          text,
-          Math.min(targetTokens, this.config.deterministicMaxTokens),
-        ),
-        escalation: 2,
-      };
-    }
-
-    // Level 0: Normal LLM summary
-    try {
-      const result = await this.summarizeFn(text, targetTokens, false);
-      if (result && estimateTokens(result) <= targetTokens * 1.5) {
-        return { text: result, escalation: 0 };
-      }
-      // If too long, try aggressive
-    } catch (err) {
-      log.debug(`LCM level-0 summary failed: ${err}`);
-    }
-
-    // Level 1: Aggressive bullet compression
-    try {
-      const aggressiveTarget = Math.max(32, Math.ceil(targetTokens * 0.5));
-      const result = await this.summarizeFn(text, aggressiveTarget, true);
-      if (result && estimateTokens(result) <= targetTokens * 1.5) {
-        return { text: result, escalation: 1 };
-      }
-    } catch (err) {
-      log.debug(`LCM level-1 summary failed: ${err}`);
-    }
-
-    // Level 2: Deterministic truncation (guaranteed, no LLM)
-    return {
-      text: deterministicTruncate(text, this.config.deterministicMaxTokens),
-      escalation: 2,
-    };
-  }
-}
-
-/** Deterministic truncation: first and last sentence, plus middle truncation. */
-function deterministicTruncate(text: string, maxTokens: number): string {
-  if (maxTokens <= 0 || estimateTokenCount(text) <= maxTokens) return text;
-
-  const sentences = text.split(/(?<=[.!?])\s+/).filter((s) => s.length > 0);
-  if (sentences.length <= 2) return clampToTokenBudget(text, maxTokens);
-
-  const first = sentences[0];
-  const last = sentences[sentences.length - 1];
-  const render = (middle: string[], truncated: boolean): string =>
-    `${first} ${middle.join(" ")}${truncated ? " [...] " : " "}${last}`;
-
-  const base = render([], false);
-  if (estimateTokenCount(base) > maxTokens) return clampToTokenBudget(text, maxTokens);
-  if (estimateTokenCount(render([], true)) > maxTokens) return base;
-
-  const middle: string[] = [];
-  for (let i = 1; i < sentences.length - 1; i++) {
-    const candidate = [...middle, sentences[i]];
-    const truncated = i < sentences.length - 2;
-    if (estimateTokenCount(render(candidate, truncated)) > maxTokens) break;
-    middle.push(sentences[i]);
+    const { deterministicMaxTokens, telemetryPrefilterEnabled } = this.config;
+    const result = await summarizeContextPure(text, targetTokens, "auto", {
+      llm: this.summarizeFn,
+      deterministicMaxTokens,
+      telemetryPrefilterEnabled,
+    });
+    return { text: result.text, escalation: result.escalation ?? 2 };
   }
-
-  const truncated = middle.length < sentences.length - 2;
-  return clampToTokenBudget(render(middle, truncated), maxTokens);
 }
 
-function clampToTokenBudget(text: string, maxTokens: number): string {
-  const codePoints = [...text];
-  let low = 0;
-  let high = codePoints.length;
-  while (low < high) {
-    const mid = Math.ceil((low + high) / 2);
-    if (estimateTokenCount(codePoints.slice(0, mid).join("")) <= maxTokens) low = mid;
-    else high = mid - 1;
-  }
-  return codePoints.slice(0, low).join("");
-}
 
 function chunkArray<T>(arr: T[], size: number): T[][] {
   const chunks: T[][] = [];

package/src/memory-action-policy.ts

@@ -78,3 +78,31 @@ export function evaluateMemoryActionPolicy(input: {
     eligibility,
   };
 }
+
+/**
+ * Gate for active-context SUMMARY/FILTER plans (issue #2347). The single
+ * deny rule is the shared `contextCompressionActionsEnabled` gate — a closed
+ * gate returns `feature_disabled` before any selection or model work. LLM
+ * summaries carry their own cap gate (`activeContextTransformLlmEnabled`)
+ * resolved at plan time, not here.
+ */
+export interface ActiveContextTransformPolicyResult {
+  decision: "allow" | "deny";
+  rationale: string;
+}
+
+export function evaluateActiveContextTransformPolicy(options: {
+  actionsEnabled: boolean;
+  operation: "SUMMARY" | "FILTER";
+}): ActiveContextTransformPolicyResult {
+  if (!options.actionsEnabled) {
+    return {
+      decision: "deny",
+      rationale: "contextCompressionActionsEnabled=false",
+    };
+  }
+  return {
+    decision: "allow",
+    rationale: `${options.operation.toLowerCase()}_eligible`,
+  };
+}

package/src/storage/context-transform-ledger.ts

@@ -0,0 +1,39 @@
+import type { ContextTransformTelemetryRecord } from "../active-context-transform.js";
+import { readContextTransformRecordRowsFromLines, readMaybeEncryptedLines } from "./secure-line-reader.js";
+
+export interface ContextTransformLedgerHost {
+  memoryActionsPath: string;
+  ensureDirectories(): Promise<void>;
+  appendStorageSecureFile(path: string, payload: string): Promise<void>;
+  readStorageSecureFile(path: string): Promise<string>;
+}
+
+export async function appendContextTransformRecords(
+  host: ContextTransformLedgerHost,
+  records: ContextTransformTelemetryRecord[],
+): Promise<number> {
+  if (records.length === 0) return 0;
+  await host.ensureDirectories();
+  await host.appendStorageSecureFile(
+    host.memoryActionsPath,
+    records.map((record) => `${JSON.stringify(record)}\n`).join(""),
+  );
+  return records.length;
+}
+
+export async function readContextTransformRecords(
+  host: ContextTransformLedgerHost,
+  limit = 200,
+): Promise<ContextTransformTelemetryRecord[]> {
+  const cappedLimit = Math.max(0, Math.floor(limit));
+  if (cappedLimit === 0 || Number.isNaN(cappedLimit)) return [];
+  try {
+    const rows = await readContextTransformRecordRowsFromLines(
+      readMaybeEncryptedLines(host.memoryActionsPath, () => host.readStorageSecureFile(host.memoryActionsPath)),
+      cappedLimit,
+    );
+    return rows.map((row) => row.record);
+  } catch {
+    return [];
+  }
+}

package/src/storage/secure-line-reader.ts

@@ -3,6 +3,7 @@ import { lstat, open } from "node:fs/promises";
 import { createInterface } from "node:readline";
 
 import { isEncryptedFile, MAGIC_HEADER_SIZE } from "../secure-store/secure-fs.js";
+import type { ContextTransformTelemetryRecord } from "../active-context-transform.js";
 import type { MemoryActionEvent, MemoryLifecycleEvent } from "../types.js";
 
 /**
@@ -89,7 +90,11 @@ export async function readMemoryActionEventRowsFromLines(
     const line = row.trim();
     if (!line) continue;
     try {
-      const parsed = JSON.parse(line) as Partial<MemoryActionEvent>;
+      const parsed = JSON.parse(line) as Partial<MemoryActionEvent> & { recordKind?: unknown };
+      // Ledger discriminated union (#2347): any row carrying a `recordKind`
+      // belongs to another record family (e.g. context_transform) and must
+      // be ignored here — the legacy parser stays strict for its own kind.
+      if (parsed.recordKind !== undefined) continue;
       const outcome = parsed.outcome === "applied" || parsed.outcome === "skipped" || parsed.outcome === "failed"
         ? parsed.outcome
         : null;
@@ -116,6 +121,50 @@ export async function readMemoryActionEventRowsFromLines(
   return writeIndex === 0 ? out : [...out.slice(writeIndex), ...out.slice(0, writeIndex)];
 }
 
+/**
+ * Tail read for context-transform telemetry rows (#2347). Selects ONLY
+ * records discriminated by `recordKind: "context_transform"` — the sibling
+ * of `readMemoryActionEventRowsFromLines`, with the same O(limit) ring
+ * buffer and line-number semantics. Malformed rows are skipped fail-open;
+ * legacy action rows are never returned here.
+ */
+export async function readContextTransformRecordRowsFromLines(
+  lines: AsyncIterable<string>,
+  limit: number,
+): Promise<Array<{ line: number; record: ContextTransformTelemetryRecord }>> {
+  const out: Array<{ line: number; record: ContextTransformTelemetryRecord }> = [];
+  let writeIndex = 0;
+  let lineNumber = 0;
+  for await (const row of lines) {
+    lineNumber += 1;
+    const line = row.trim();
+    if (!line) continue;
+    try {
+      const parsed = JSON.parse(line) as Partial<ContextTransformTelemetryRecord>;
+      if (
+        parsed.recordKind === "context_transform" &&
+        typeof parsed.timestamp === "string" &&
+        typeof parsed.actionId === "string" &&
+        typeof parsed.planHash === "string"
+      ) {
+        const entry = {
+          line: lineNumber,
+          record: parsed as ContextTransformTelemetryRecord,
+        };
+        if (out.length < limit) {
+          out.push(entry);
+        } else {
+          out[writeIndex] = entry;
+          writeIndex = (writeIndex + 1) % limit;
+        }
+      }
+    } catch {
+      // Ignore malformed rows (fail-open).
+    }
+  }
+  return writeIndex === 0 ? out : [...out.slice(writeIndex), ...out.slice(0, writeIndex)];
+}
+
 /**
  * Validate that a parsed row carries every required lifecycle-event field.
  * Shared by the tail reader and the per-memory reader so both apply the EXACT

package/src/storage.ts

@@ -29,6 +29,8 @@ import { runCommittedInvalidation } from "./storage/committed-invalidation.js";
 import { renderProfileWithLastUpdated, stripOkfProfileFrontmatter, withOkfProfileFrontmatter } from "./storage/profile-header.js";
 import { parseQuestionFile as parseQuestionFileText } from "./storage/questions-file.js";
 import { assertNotOkfReservedBasename, OKF_QUESTION_TYPE, okfTypeForEntityKind, okfTypeForMemory } from "./okf/type-mapping.js";
+import { appendContextTransformRecords, readContextTransformRecords } from "./storage/context-transform-ledger.js";
+import type { ContextTransformTelemetryRecord } from "./active-context-transform.js";
 import { readMaybeEncryptedLines, readMemoryActionEventRowsFromLines } from "./storage/secure-line-reader.js";
 import {
   appendLifecycleEventsSerialized,
@@ -5595,7 +5597,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     await this.appendStorageSecureFile(this.memoryActionsPath, payload);
     return events.length;
   }
-
+  async appendContextTransformRecords(records: ContextTransformTelemetryRecord[]) { return appendContextTransformRecords(this as never, records); }
+  async readContextTransformRecords(limit = 200) { return readContextTransformRecords(this as never, limit); }
   async appendMemoryLifecycleEvents(events: MemoryLifecycleEvent[]): Promise<number> {
     if (events.length === 0) return 0;
     await this.ensureDirectories();

package/src/types.ts

@@ -15,7 +15,7 @@ import type { DriftDetectionSettings, MemoryDriftProvenance, RecallDriftAnnotati
 import type { ProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
 import type { SkillProjectionConfig } from "./procedural/skill-projection.js";
 import type { ActionGateConfig } from "./coding/action-gate.js";
-
+import type { ActiveContextConfigFields } from "./active-context-config.js";
 import type { AmbientCaptureProvenance, BufferTurnOwner, SecurityConfig, OriginMetadata } from "./security/types.js";
 export type MemorySubject = "user" | "agent";
 export type SubjectGuardMode = "off" | "warn" | "enforce";
@@ -682,8 +682,7 @@ export interface SemanticChunkingConfigShape {
   fallbackToRecursive: boolean;
 }
 
-
-export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig, DriftDetectionSettings {
+export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig, DriftDetectionSettings, ActiveContextConfigFields {
   openaiApiKey: string | undefined;
   openaiBaseUrl: string | undefined;
   model: string;