@remnic/core 1.0.3 → 1.1.1

package/dist/{semantic-consolidation-DrvSYRdB.d.ts → semantic-consolidation-CxJU6MJk.d.ts}

@@ -1,6 +1,7 @@
 import { PluginConfig, MemoryFile } from './types.js';
 import { R as RolloutSummaryInput, M as MaterializeResult } from './codex-materialize-CQlLTzke.js';
 import { LoggerBackend } from './logger.js';
+import { ConsolidationOperator } from './consolidation-operator.js';
 
 /**
  * memory-extension-host/types.ts — Types for third-party memory extension discovery.
@@ -92,6 +93,66 @@ declare function buildConsolidationPrompt(cluster: ConsolidationCluster): string
  * Parse the LLM response to extract the canonical content.
  */
 declare function parseConsolidationResponse(response: string): string;
+/**
+ * Structured result from an operator-aware consolidation LLM call.
+ *
+ * - `operator` — the consolidation operator the LLM chose for this cluster.
+ *   Falls back to the heuristic default when the LLM omits or returns an
+ *   unknown value (the parser never surfaces an invalid operator; see
+ *   `parseOperatorAwareConsolidationResponse`).
+ * - `output` — the canonical content (same format the legacy prompt
+ *   returns).  Callers persist this as the body of the new memory.
+ */
+interface OperatorAwareConsolidationResult {
+    operator: ConsolidationOperator;
+    output: string;
+}
+/**
+ * Heuristic default operator for a cluster.  Used as the fallback when the
+ * LLM does not return a parseable operator, and as the "floor" decision in
+ * `parseOperatorAwareConsolidationResponse`.
+ *
+ * Current heuristic (kept deliberately conservative — PR 3 only):
+ *
+ *   - Two or more memories being collapsed into one canonical blob is a
+ *     MERGE by definition.  This is the path the current clustering
+ *     pipeline exercises.
+ *   - A cluster of size 1 that still reaches consolidation (future path,
+ *     e.g. supersession of a single older memory by a newer value) is an
+ *     UPDATE.
+ *   - SPLIT is never selected by the heuristic because the current write
+ *     path emits exactly one canonical memory per cluster.  The prompt
+ *     reserves SPLIT for future cluster shapes where the LLM decides one
+ *     logical source actually encodes several distinct facts — at which
+ *     point the orchestrator would need to write multiple outputs.
+ */
+declare function chooseConsolidationOperator(cluster: ConsolidationCluster): ConsolidationOperator;
+/**
+ * Build the operator-aware LLM prompt.  The LLM is asked to return a
+ * JSON object `{ "operator": <split|merge|update>, "output": <content> }`.
+ *
+ * The prompt is additive: it still asks for a single canonical blob under
+ * `output`, so the upstream write path does not change.  Future expansions
+ * (SPLIT emitting multiple outputs) are explicitly documented as
+ * out-of-scope for the parser — `parseOperatorAwareConsolidationResponse`
+ * collapses any SPLIT response into a single canonical output for now.
+ */
+declare function buildOperatorAwareConsolidationPrompt(cluster: ConsolidationCluster): string;
+/**
+ * Parse an operator-aware consolidation response.
+ *
+ * Contract:
+ *   - Accepts strict JSON `{ "operator": "...", "output": "..." }`.
+ *   - Tolerates a JSON payload wrapped in a fenced code block (```json ...```).
+ *   - Falls back to the heuristic operator when the JSON is malformed,
+ *     the `operator` field is missing / unknown, or the raw response is
+ *     a plain blob with no JSON at all.  This keeps PR 3 backwards
+ *     compatible with older models that ignore the JSON instruction.
+ *   - Never throws.  A missing / empty `output` field falls back to the
+ *     trimmed raw response so the caller still writes something rather
+ *     than dropping the cluster.
+ */
+declare function parseOperatorAwareConsolidationResponse(response: string, cluster: ConsolidationCluster): OperatorAwareConsolidationResult;
 /**
  * Discover extensions and build the block to append to a consolidation prompt.
  * Returns "" when extensions are disabled or none are found.
@@ -116,4 +177,4 @@ declare function materializeAfterSemanticConsolidation(options: {
     now?: Date;
 }): Promise<MaterializeResult | null>;
 
-export { type ConsolidationCluster as C, type DiscoveredExtension as D, type ExtensionSchema as E, REMNIC_EXTENSIONS_TOTAL_TOKEN_LIMIT as R, type SemanticConsolidationResult as S, buildConsolidationPrompt as a, buildExtensionsBlockForConsolidation as b, discoverMemoryExtensions as d, findSimilarClusters as f, materializeAfterSemanticConsolidation as m, parseConsolidationResponse as p, resolveExtensionsRoot as r };
+export { type ConsolidationCluster as C, type DiscoveredExtension as D, type ExtensionSchema as E, type OperatorAwareConsolidationResult as O, REMNIC_EXTENSIONS_TOTAL_TOKEN_LIMIT as R, type SemanticConsolidationResult as S, buildConsolidationPrompt as a, buildExtensionsBlockForConsolidation as b, buildOperatorAwareConsolidationPrompt as c, discoverMemoryExtensions as d, chooseConsolidationOperator as e, findSimilarClusters as f, parseOperatorAwareConsolidationResponse as g, materializeAfterSemanticConsolidation as m, parseConsolidationResponse as p, resolveExtensionsRoot as r };

package/dist/semantic-consolidation.d.ts

@@ -1,4 +1,5 @@
 import './types.js';
 import './codex-materialize-CQlLTzke.js';
-export { C as ConsolidationCluster, S as SemanticConsolidationResult, a as buildConsolidationPrompt, b as buildExtensionsBlockForConsolidation, f as findSimilarClusters, m as materializeAfterSemanticConsolidation, p as parseConsolidationResponse, r as resolveExtensionsRoot } from './semantic-consolidation-DrvSYRdB.js';
+export { C as ConsolidationCluster, O as OperatorAwareConsolidationResult, S as SemanticConsolidationResult, a as buildConsolidationPrompt, b as buildExtensionsBlockForConsolidation, c as buildOperatorAwareConsolidationPrompt, e as chooseConsolidationOperator, f as findSimilarClusters, m as materializeAfterSemanticConsolidation, p as parseConsolidationResponse, g as parseOperatorAwareConsolidationResponse, r as resolveExtensionsRoot } from './semantic-consolidation-CxJU6MJk.js';
+export { CONSOLIDATION_OPERATORS, ConsolidationOperator, isConsolidationOperator, isValidDerivedFromEntry } from './consolidation-operator.js';
 import './logger.js';

package/dist/semantic-consolidation.js

@@ -1,33 +1,47 @@
 import {
   buildConsolidationPrompt,
   buildExtensionsBlockForConsolidation,
+  buildOperatorAwareConsolidationPrompt,
+  chooseConsolidationOperator,
   findSimilarClusters,
   materializeAfterSemanticConsolidation,
-  parseConsolidationResponse
-} from "./chunk-RCICHSHL.js";
+  parseConsolidationResponse,
+  parseOperatorAwareConsolidationResponse
+} from "./chunk-BGJGXLZ7.js";
 import {
   resolveExtensionsRoot
 } from "./chunk-EJI5XIBB.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import {
+  CONSOLIDATION_OPERATORS,
+  isConsolidationOperator,
+  isValidDerivedFromEntry
+} from "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
+  CONSOLIDATION_OPERATORS,
   buildConsolidationPrompt,
   buildExtensionsBlockForConsolidation,
+  buildOperatorAwareConsolidationPrompt,
+  chooseConsolidationOperator,
   findSimilarClusters,
+  isConsolidationOperator,
+  isValidDerivedFromEntry,
   materializeAfterSemanticConsolidation,
   parseConsolidationResponse,
+  parseOperatorAwareConsolidationResponse,
   resolveExtensionsRoot
 };
 //# sourceMappingURL=semantic-consolidation.js.map

package/dist/semantic-rule-promotion.js

@@ -1,18 +1,19 @@
 import {
   promoteSemanticRuleFromMemory
-} from "./chunk-KWP7T3DP.js";
-import "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+} from "./chunk-VDX363PS.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   promoteSemanticRuleFromMemory

package/dist/semantic-rule-verifier.js

@@ -1,19 +1,20 @@
 import {
   searchVerifiedSemanticRules
-} from "./chunk-MYQWXITD.js";
+} from "./chunk-SPI27QT6.js";
 import "./chunk-DT5TVLJE.js";
-import "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   searchVerifiedSemanticRules

package/dist/storage.d.ts

@@ -1,5 +1,6 @@
 import { VersioningConfig } from './page-versioning.js';
-import { PluginConfig, MemoryCategory, ImportanceScore, MemoryLink, MemoryFrontmatter, MemoryStatus, MemoryFile, EntityStructuredSection, BufferState, MetaState, MemoryActionEvent, MemoryLifecycleEvent, BehaviorSignalEvent, CompressionGuidelineOptimizerState, ContinuityIncidentOpenInput, ContinuityIncidentRecord, ContinuityIncidentCloseInput, ContinuityImprovementLoop, ContinuityLoopUpsertInput, ContinuityLoopReviewInput, FileHygieneConfig, EntityRelationship, EntityActivityEntry, EntityFile, AccessTrackingEntry, MemoryProjectionCurrentState, MemorySummary, TopicScore } from './types.js';
+import { ConsolidationOperator } from './consolidation-operator.js';
+import { PluginConfig, MemoryCategory, ImportanceScore, MemoryLink, MemoryFrontmatter, MemoryStatus, MemoryFile, EntityStructuredSection, BufferState, MetaState, MemoryActionEvent, MemoryLifecycleEvent, BufferSurpriseEvent, BehaviorSignalEvent, CompressionGuidelineOptimizerState, ContinuityIncidentOpenInput, ContinuityIncidentRecord, ContinuityIncidentCloseInput, ContinuityImprovementLoop, ContinuityLoopUpsertInput, ContinuityLoopReviewInput, FileHygieneConfig, EntityRelationship, EntityActivityEntry, EntityFile, AccessTrackingEntry, MemoryProjectionCurrentState, MemorySummary, TopicScore } from './types.js';
 import { P as ProjectedMemoryBrowseOptions, a as ProjectedMemoryBrowsePage, b as readProjectedGovernanceRecord } from './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 
@@ -132,6 +133,21 @@ declare class StorageManager {
      * No-op when versioning is disabled or the file does not yet exist.
      */
     private snapshotBeforeWrite;
+    /**
+     * Consolidation provenance helper (issue #561 PR 2).
+     *
+     * Captures the current on-disk content of a source memory as a
+     * page-version snapshot so the downstream consolidated write can record a
+     * `derived_from` pointer that actually resolves.  Returns the
+     * `"<relative-path>:<versionId>"` entry expected by the `derived_from`
+     * frontmatter field.
+     *
+     * Returns `null` when versioning is disabled (snapshots would not be
+     * created), when the file does not exist (nothing to snapshot), or when
+     * the snapshot write itself fails (best-effort — callers skip the entry
+     * rather than block the consolidation).
+     */
+    snapshotForProvenance(filePath: string): Promise<string | null>;
     constructor(baseDir: string, entitySchemas?: PluginConfig["entitySchemas"]);
     /** The root directory of this storage instance. */
     get dir(): string;
@@ -146,6 +162,7 @@ declare class StorageManager {
     private get factsDir();
     private get correctionsDir();
     private get proceduresDir();
+    private get reasoningTracesDir();
     private get entitiesDir();
     private get stateDir();
     private get entitySynthesisQueuePath();
@@ -169,6 +186,17 @@ declare class StorageManager {
     private get compressionGuidelineStatePath();
     private get compressionGuidelineDraftStatePath();
     private get behaviorSignalsPath();
+    /**
+     * Buffer surprise telemetry ledger (issue #563 PR 3).
+     *
+     * Append-only JSONL of per-turn `BUFFER_SURPRISE` events emitted by
+     * `SmartBuffer` when `bufferSurpriseTriggerEnabled` is on. Each row
+     * captures the score, the threshold in force at the time, whether the
+     * turn caused an extract_now upgrade, and the buffer size. Kept in
+     * `state/` alongside the other append-only ledgers so cleanup and
+     * governance sweeps can treat it uniformly.
+     */
+    private get bufferSurpriseLedgerPath();
     /**
      * Load user-defined entity aliases from config/aliases.json in the memory store.
      * File format: { "variant": "canonical", "variant2": "canonical", ... }
@@ -208,6 +236,15 @@ declare class StorageManager {
          */
         contentHashSource?: string;
         status?: MemoryStatus;
+        /**
+         * Consolidation provenance (issue #561 PR 2).  When the caller is a
+         * consolidation / supersession / dedup-merge path, these fields wire
+         * the page-version snapshots the new memory was derived from and the
+         * operator that produced it.  Persisted onto frontmatter as
+         * `derived_from` + `derived_via`; validated at serialize time.
+         */
+        derivedFrom?: string[];
+        derivedVia?: ConsolidationOperator;
     }): Promise<string>;
     hasFactContentHash(content: string): Promise<boolean>;
     isFactContentHashAuthoritative(): Promise<boolean>;
@@ -391,6 +428,50 @@ declare class StorageManager {
     saveMeta(state: MetaState): Promise<void>;
     appendMemoryActionEvents(events: MemoryActionEvent[]): Promise<number>;
     appendMemoryLifecycleEvents(events: MemoryLifecycleEvent[]): Promise<number>;
+    /**
+     * Append a batch of `BUFFER_SURPRISE` telemetry events (issue #563 PR 3).
+     *
+     * Each event records a single buffer flush decision driven by the
+     * surprise gate. The ledger is consumed by
+     * `reportBufferSurpriseDistribution` (Doctor report) and by downstream
+     * benchmark analysis. This method is fire-and-forget by contract:
+     * callers log but do not fail the hot path if the append throws.
+     */
+    appendBufferSurpriseEvents(events: BufferSurpriseEvent[]): Promise<number>;
+    /**
+     * Read the buffer-surprise ledger, most recent rows last.
+     *
+     * `limit` bounds the number of **valid rows** returned (not the
+     * number of raw lines parsed). We parse every row, discard malformed
+     * ones, then take the tail — so a partial/truncated trailing line
+     * (the common failure mode after an interrupted append) cannot hide
+     * otherwise-valid recent data above it.
+     *
+     * Non-positive / non-integer / non-finite limits return `[]` rather
+     * than the entire file, matching the other ledger readers in this
+     * class and protecting against `slice(-0.5)` → `slice(-0)` silently
+     * devolving into an unbounded parse.
+     *
+     * # Performance note
+     *
+     * For very large ledgers (issue #563 follow-up), a tail-first reader
+     * would avoid parsing the full file when only a recent window is
+     * needed. We keep the full-scan implementation here because:
+     *
+     *   - the ledger is opt-in (flag off by default), so early deployments
+     *     accumulate rows slowly;
+     *   - telemetry rows are small (~200 bytes), so even 100k rows parse
+     *     in well under a second;
+     *   - the governance archive/cleanup flow can trim the ledger when
+     *     size becomes a concern, reusing the existing maintenance hooks.
+     *
+     * Swap to a chunked tail-reader if production logs show this is a
+     * hot path — leaving that work for a follow-up keeps this PR scoped
+     * to correctness, not optimization.
+     */
+    readBufferSurpriseEvents(options?: {
+        limit?: number;
+    }): Promise<BufferSurpriseEvent[]>;
     appendBehaviorSignals(events: BehaviorSignalEvent[]): Promise<number>;
     appendReextractJobs(events: ReextractJobRequest[]): Promise<number>;
     readReextractJobs(limit?: number): Promise<ReextractJobRequest[]>;

package/dist/storage.js

@@ -8,18 +8,19 @@ import {
   normalizeEntityName,
   parseEntityFile,
   serializeEntityFile
-} from "./chunk-POMSFKTB.js";
-import "./chunk-U2IQTSBY.js";
+} from "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-QSVPYQPG.js";
 import "./chunk-DM2T26WE.js";
+import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   ContentHashIndex,

package/dist/summarizer.js

@@ -1,12 +1,12 @@
 import {
   HourlySummarizer
-} from "./chunk-BTY5RRRF.js";
+} from "./chunk-ZEM3OK2K.js";
 import "./chunk-ETOW6ACV.js";
-import "./chunk-UPMD5XND.js";
 import "./chunk-FEMOX5AD.js";
+import "./chunk-JL2PU6AI.js";
 import "./chunk-LK6SGL53.js";
-import "./chunk-QKAH5B6E.js";
-import "./chunk-KEG4GNGI.js";
+import "./chunk-3GXCSUXR.js";
+import "./chunk-XZ2TIKGC.js";
 import "./chunk-ODWDQNRE.js";
 import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";

package/dist/temporal-supersession.d.ts

@@ -1,6 +1,7 @@
 import { MemoryFrontmatter } from './types.js';
 import { StorageManager } from './storage.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 

package/dist/tier-migration.d.ts

@@ -1,8 +1,9 @@
 import { MemoryFile } from './types.js';
 import { StorageManager } from './storage.js';
 import { MemoryTier } from './tier-routing.js';
-import { S as SearchBackend } from './port-C1GZFv8h.js';
+import { S as SearchBackend } from './port-BADbLZU5.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 import './lifecycle.js';

package/dist/types-DJhqDJUV.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Taxonomy types for the MECE knowledge directory.
+ *
+ * A taxonomy defines a set of categories that partition the knowledge
+ * space so that every memory maps to exactly one category (Mutually
+ * Exclusive, Collectively Exhaustive).
+ */
+/**
+ * A single category in the taxonomy.
+ *
+ * @property id          - Slug: lowercase letters, digits, hyphens; max 32 chars.
+ * @property name        - Human-readable display name.
+ * @property description - What belongs in this category.
+ * @property filingRules - Prose rules used by the resolver decision tree.
+ * @property parentId    - Optional parent category for nesting.
+ * @property priority    - Tie-breaker: lower number wins when a memory
+ *                         could belong to multiple categories.
+ * @property memoryCategories - Which MemoryCategory values map here.
+ */
+interface TaxonomyCategory {
+    id: string;
+    name: string;
+    description: string;
+    filingRules: string[];
+    parentId?: string;
+    priority: number;
+    memoryCategories: string[];
+}
+/**
+ * A versioned taxonomy comprising an ordered list of categories.
+ */
+interface Taxonomy {
+    version: number;
+    categories: TaxonomyCategory[];
+}
+/**
+ * The output of the resolver: which category a piece of knowledge
+ * belongs to, with confidence and alternatives.
+ */
+interface ResolverDecision {
+    categoryId: string;
+    confidence: number;
+    reason: string;
+    alternatives: Array<{
+        categoryId: string;
+        reason: string;
+    }>;
+}
+
+export type { ResolverDecision as R, Taxonomy as T, TaxonomyCategory as a };