@remnic/core 1.0.2 → 1.1.0

package/dist/temporal-supersession.d.ts

@@ -0,0 +1,127 @@
+import { MemoryFrontmatter } from './types.js';
+import { StorageManager } from './storage.js';
+import './page-versioning.js';
+import './memory-projection-store-DeSXPh1j.js';
+import 'better-sqlite3';
+
+/**
+ * Temporal Supersession (issue #375)
+ *
+ * When a new fact lands with `structuredAttributes` keyed on a known
+ * `entityRef`, any prior fact whose supersession key collides with the new
+ * fact's key is marked `status: "superseded"` and linked via
+ * `supersededBy` / `supersededAt`.  Recall filters those superseded memories
+ * by default so agents see only the "current" value per entity attribute.
+ *
+ * The algorithm is intentionally O(N) over the memory corpus per write, but
+ * skips cheaply when the new fact has no structuredAttributes.  It reuses the
+ * cached `readAllMemories()` path so cost is amortized with the rest of the
+ * write pipeline.
+ */
+
+/**
+ * Shared normalization for supersession key components.
+ *
+ * Trims surrounding whitespace, lowercases, then collapses any run of
+ * whitespace OR hyphens to a single hyphen, and strips any leading/trailing
+ * hyphens that result.  Both `computeSupersessionKey` and
+ * `lookupAttributeByNormalizedKey` must use this so that keys produced at
+ * write time and keys used at lookup time are identical regardless of how
+ * the LLM encoded whitespace, hyphens, or casing (Finding B fix).
+ *
+ * Symmetry guarantee: `"foo bar"`, `"foo-bar"`, `"foo - bar"`, and
+ * `"foo  bar"` all canonicalize to `"foo-bar"`.
+ *
+ * Exported so external tests can verify the canonical form.
+ */
+declare function normalizeSupersessionKey(raw: string): string;
+/**
+ * Stable supersession key for an (entityRef, attributeName) pair.
+ *
+ * The algorithm is:
+ *  - normalize the entityRef (trim, lower-case, collapse whitespace)
+ *  - normalize the attributeName the same way
+ *  - join with `::`
+ *
+ * Exported so tests and tools can recompute it without depending on storage.
+ */
+declare function computeSupersessionKey(entityRef: string | undefined, attributeName: string): string | null;
+/**
+ * Compute the full set of supersession keys for a fact with structured
+ * attributes.  Returns an empty array if no keys can be derived.
+ */
+declare function supersessionKeysForFact(spec: {
+    entityRef?: string;
+    structuredAttributes?: Record<string, string>;
+}): string[];
+/**
+ * Look up a structured-attribute value by a raw key, normalizing both sides
+ * with `normalizeSupersessionKey` before comparing.  This ensures that keys
+ * written by the LLM with mixed case, surrounding whitespace, or internal
+ * whitespace (e.g. `"City"`, `" city "`, `"job   title"`, `"job-title"`)
+ * are all matched against normalized keys produced by `computeSupersessionKey`
+ * (Finding B fix — uses the same helper so both sides are identical).
+ *
+ * The storage format is NOT changed — we only normalize at lookup time.
+ */
+declare function lookupAttributeByNormalizedKey(attributes: Record<string, unknown>, rawKey: string): unknown;
+/**
+ * Decide whether an existing memory should be superseded by a newly-written
+ * memory that carries the supplied supersession key set.
+ *
+ * Only memories that:
+ *  - are currently `active`
+ *  - share an `entityRef` with the new fact
+ *  - share at least one supersession key with the new fact
+ *  - are older than the new fact
+ *  - have a conflicting value (different string) for the overlapping key
+ * are eligible.  This keeps supersession local to the attribute that actually
+ * changed — if fact A sets `{city: Austin, tool: vim}` and fact B sets
+ * `{city: NYC}`, only the city attribute is superseded, not the tool.
+ */
+declare function shouldSupersedeExisting(args: {
+    candidate: MemoryFrontmatter;
+    newEntityRef: string;
+    newAttributes: Record<string, string>;
+    newCreatedAt: string;
+    newMemoryId: string;
+}): {
+    matchedKeys: string[];
+} | null;
+interface TemporalSupersessionResult {
+    supersededIds: string[];
+    matchedKeys: string[];
+}
+/**
+ * Scan existing memories and mark any that are superseded by the
+ * just-written memory.  Fails open on I/O errors — the new memory is already
+ * on disk, and supersession is a best-effort hygiene step.
+ */
+declare function applyTemporalSupersession(args: {
+    storage: StorageManager;
+    newMemoryId: string;
+    entityRef?: string;
+    structuredAttributes?: Record<string, string>;
+    createdAt: string;
+    enabled: boolean;
+    /**
+     * When true, skip the persisted `frontmatter.created` lookup and use
+     * `args.createdAt` directly as the ordering anchor.  Set this on the
+     * hash-dedup short-circuit path where `newMemoryId` points to an existing
+     * OLD fact (no new file is written) and its persisted timestamp would be
+     * stale relative to the incoming promotion event (PR #402 Finding Uyui).
+     */
+    useCallerTimestamp?: boolean;
+}): Promise<TemporalSupersessionResult>;
+/**
+ * Recall-side filter: returns true when the candidate should be excluded
+ * from recall because it has been temporally superseded.  When
+ * `includeInRecall` is true, this always returns false (the fact is kept),
+ * matching the audit/history opt-in described in the config.
+ */
+declare function shouldFilterSupersededFromRecall(frontmatter: MemoryFrontmatter, options: {
+    enabled: boolean;
+    includeInRecall: boolean;
+}): boolean;
+
+export { type TemporalSupersessionResult, applyTemporalSupersession, computeSupersessionKey, lookupAttributeByNormalizedKey, normalizeSupersessionKey, shouldFilterSupersededFromRecall, shouldSupersedeExisting, supersessionKeysForFact };

package/dist/temporal-supersession.js

@@ -0,0 +1,20 @@
+import {
+  applyTemporalSupersession,
+  computeSupersessionKey,
+  lookupAttributeByNormalizedKey,
+  normalizeSupersessionKey,
+  shouldFilterSupersededFromRecall,
+  shouldSupersedeExisting,
+  supersessionKeysForFact
+} from "./chunk-W6SL7OFG.js";
+import "./chunk-2ODBA7MQ.js";
+export {
+  applyTemporalSupersession,
+  computeSupersessionKey,
+  lookupAttributeByNormalizedKey,
+  normalizeSupersessionKey,
+  shouldFilterSupersededFromRecall,
+  shouldSupersedeExisting,
+  supersessionKeysForFact
+};
+//# sourceMappingURL=temporal-supersession.js.map

package/dist/temporal-supersession.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/threading.js

@@ -1,7 +1,7 @@
 import {
   ThreadingManager
-} from "./chunk-UCYSTFZR.js";
-import "./chunk-KWBU5S5U.js";
+} from "./chunk-JRNQ3RNA.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   ThreadingManager
 };

package/dist/tier-migration.d.ts

@@ -2,7 +2,8 @@ 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 './memory-projection-store-NxMkbocT.js';
+import './page-versioning.js';
+import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 import './lifecycle.js';
 

package/dist/tier-routing.js

@@ -1,8 +1,8 @@
 import {
   computeTierValueScore,
   decideTierTransition
-} from "./chunk-4A24LIM2.js";
-import "./chunk-QCCCQT3O.js";
+} from "./chunk-S75M5ZRK.js";
+import "./chunk-TBBDFYXW.js";
 export {
   computeTierValueScore,
   decideTierTransition

package/dist/tokens.d.ts

@@ -14,6 +14,26 @@ interface TokenStore {
 }
 declare function loadTokenStore(tokensPath?: string): TokenStore;
 declare function saveTokenStore(store: TokenStore, tokensPath?: string): void;
+/**
+ * Build a TokenEntry candidate WITHOUT saving it to the store.
+ * Callers use this when they need to defer the save until after a
+ * dependent write (e.g. Hermes config.yaml) succeeds — see
+ * commitTokenEntry() to persist the candidate.
+ */
+declare function buildTokenEntry(connector: string): TokenEntry;
+/**
+ * Persist a pre-built TokenEntry into the store, replacing any existing
+ * entry for the same connector. Used together with buildTokenEntry() when
+ * the caller wants to defer the save until after a dependent write succeeds.
+ *
+ * For transactional rollback, callers should snapshot the full store via
+ * loadTokenStore() BEFORE calling commitTokenEntry() and restore it with
+ * saveTokenStore() on failure. A full-store snapshot handles partial writes
+ * of tokens.json atomically — single-entry restore via the return value is
+ * insufficient because if this function throws during saveTokenStore, the
+ * return statement never executes (UXJI/UXJT fix).
+ */
+declare function commitTokenEntry(entry: TokenEntry, tokensPath?: string): void;
 declare function generateToken(connector: string, tokensPath?: string): TokenEntry;
 declare function listTokens(tokensPath?: string): TokenEntry[];
 declare function revokeToken(connector: string, tokensPath?: string): boolean;
@@ -21,4 +41,4 @@ declare function getAllValidTokens(tokensPath?: string): string[];
 declare function getAllValidTokensCached(tokensPath?: string): string[];
 declare function resolveConnectorFromToken(token: string, tokensPath?: string): string | undefined;
 
-export { type TokenEntry, type TokenStore, generateToken, getAllValidTokens, getAllValidTokensCached, listTokens, loadTokenStore, resolveConnectorFromToken, revokeToken, saveTokenStore };
+export { type TokenEntry, type TokenStore, buildTokenEntry, commitTokenEntry, generateToken, getAllValidTokens, getAllValidTokensCached, listTokens, loadTokenStore, resolveConnectorFromToken, revokeToken, saveTokenStore };

package/dist/tokens.js

@@ -1,4 +1,6 @@
 import {
+  buildTokenEntry,
+  commitTokenEntry,
   generateToken,
   getAllValidTokens,
   getAllValidTokensCached,
@@ -7,8 +9,10 @@ import {
   resolveConnectorFromToken,
   revokeToken,
   saveTokenStore
-} from "./chunk-KL4CP4SB.js";
+} from "./chunk-O5ETUNBT.js";
 export {
+  buildTokenEntry,
+  commitTokenEntry,
   generateToken,
   getAllValidTokens,
   getAllValidTokensCached,

package/dist/transcript.js

@@ -1,8 +1,8 @@
 import {
   TranscriptManager
-} from "./chunk-UV2FO7J4.js";
+} from "./chunk-E6K4NIEU.js";
 import "./chunk-YRMVARQP.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   TranscriptManager
 };

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 };