@remnic/core 1.0.2 → 1.1.0

package/dist/skills-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * skills-registry.ts
+ *
+ * Built-in Remnic procedural memory skills — the canonical SKILL.md sources
+ * shipped with the monorepo. Consumers (e.g. the Codex materializer in #378)
+ * read this registry to discover which skills to materialize into
+ * `~/.codex/memories/skills/<slug>/SKILL.md`.
+ *
+ * This module is intentionally free of Codex/Claude Code host coupling —
+ * it only exposes the static metadata each host needs.
+ */
+/**
+ * A single procedural-memory skill source that Remnic ships.
+ *
+ * - `slug` is the canonical folder name under `skills/` and the file on disk
+ *   must live at `<pluginRoot>/skills/<slug>/SKILL.md`.
+ * - `staticPath`, when set, points at a pre-authored SKILL.md on disk.
+ * - `generator`, when set, produces a SKILL.md body at materialization time.
+ *   Exactly one of `staticPath` or `generator` should be provided.
+ * - `disableModelInvocation` mirrors the `disable-model-invocation` frontmatter
+ *   key and indicates a skill that writes or mutates state and therefore
+ *   should not be auto-invoked by a model without explicit opt-in.
+ */
+interface RemnicSkillSource {
+    slug: string;
+    staticPath?: string;
+    generator?: () => Promise<string>;
+    disableModelInvocation: boolean;
+}
+/**
+ * Validate a Remnic skill slug. Rules:
+ *
+ * - lowercase letters, digits, and `-` only
+ * - must start with a letter or digit
+ * - 1–64 characters
+ *
+ * This is the same shape the Codex skills directory expects.
+ */
+declare function isValidSkillSlug(slug: string): boolean;
+/**
+ * The canonical list of Remnic procedural memory skills shipped with the
+ * monorepo. The Codex materializer (#378) copies these into
+ * `~/.codex/memories/skills/<slug>/SKILL.md`.
+ */
+declare const BUILTIN_SKILLS: RemnicSkillSource[];
+
+export { BUILTIN_SKILLS, type RemnicSkillSource, isValidSkillSlug };

package/dist/skills-registry.js

@@ -0,0 +1,48 @@
+// src/skills-registry.ts
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+function isValidSkillSlug(slug) {
+  return /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,63}$/.test(slug);
+}
+var HERE = dirname(fileURLToPath(import.meta.url));
+var PLUGIN_CODEX_SKILLS_DIR = resolve(HERE, "..", "..", "plugin-codex", "skills");
+function codexSkillPath(slug) {
+  return resolve(PLUGIN_CODEX_SKILLS_DIR, slug, "SKILL.md");
+}
+var BUILTIN_SKILLS = [
+  {
+    slug: "remnic-memory-workflow",
+    staticPath: codexSkillPath("remnic-memory-workflow"),
+    disableModelInvocation: true
+  },
+  {
+    slug: "remnic-recall",
+    staticPath: codexSkillPath("remnic-recall"),
+    disableModelInvocation: false
+  },
+  {
+    slug: "remnic-remember",
+    staticPath: codexSkillPath("remnic-remember"),
+    disableModelInvocation: true
+  },
+  {
+    slug: "remnic-search",
+    staticPath: codexSkillPath("remnic-search"),
+    disableModelInvocation: false
+  },
+  {
+    slug: "remnic-entities",
+    staticPath: codexSkillPath("remnic-entities"),
+    disableModelInvocation: false
+  },
+  {
+    slug: "remnic-status",
+    staticPath: codexSkillPath("remnic-status"),
+    disableModelInvocation: false
+  }
+];
+export {
+  BUILTIN_SKILLS,
+  isValidSkillSlug
+};
+//# sourceMappingURL=skills-registry.js.map

package/dist/skills-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/skills-registry.ts"],"sourcesContent":["/**\n * skills-registry.ts\n *\n * Built-in Remnic procedural memory skills — the canonical SKILL.md sources\n * shipped with the monorepo. Consumers (e.g. the Codex materializer in #378)\n * read this registry to discover which skills to materialize into\n * `~/.codex/memories/skills/<slug>/SKILL.md`.\n *\n * This module is intentionally free of Codex/Claude Code host coupling —\n * it only exposes the static metadata each host needs.\n */\n\nimport { fileURLToPath } from \"node:url\";\nimport { dirname, resolve } from \"node:path\";\n\n/**\n * A single procedural-memory skill source that Remnic ships.\n *\n * - `slug` is the canonical folder name under `skills/` and the file on disk\n *   must live at `<pluginRoot>/skills/<slug>/SKILL.md`.\n * - `staticPath`, when set, points at a pre-authored SKILL.md on disk.\n * - `generator`, when set, produces a SKILL.md body at materialization time.\n *   Exactly one of `staticPath` or `generator` should be provided.\n * - `disableModelInvocation` mirrors the `disable-model-invocation` frontmatter\n *   key and indicates a skill that writes or mutates state and therefore\n *   should not be auto-invoked by a model without explicit opt-in.\n */\nexport interface RemnicSkillSource {\n  slug: string;\n  staticPath?: string;\n  generator?: () => Promise<string>;\n  disableModelInvocation: boolean;\n}\n\n/**\n * Validate a Remnic skill slug. Rules:\n *\n * - lowercase letters, digits, and `-` only\n * - must start with a letter or digit\n * - 1–64 characters\n *\n * This is the same shape the Codex skills directory expects.\n */\nexport function isValidSkillSlug(slug: string): boolean {\n  // Must start with alphanumeric; each dash must be followed by alphanumeric\n  // (no trailing dashes, no consecutive dashes); 1–64 characters total.\n  return /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,63}$/.test(slug);\n}\n\n// ---------------------------------------------------------------------------\n// Built-in skill paths — resolved relative to this source file.\n// ---------------------------------------------------------------------------\n//\n// This file lives at `packages/remnic-core/src/skills-registry.ts`.\n// After tsup build it lives at `packages/remnic-core/dist/skills-registry.js`.\n// In both cases, the shipped skill sources live four levels up at\n// `packages/plugin-codex/skills/<slug>/SKILL.md`.\n//\n// We compute the absolute path from the current module so that callers in any\n// cwd can resolve the files.\n\nconst HERE = dirname(fileURLToPath(import.meta.url));\nconst PLUGIN_CODEX_SKILLS_DIR = resolve(HERE, \"..\", \"..\", \"plugin-codex\", \"skills\");\n\nfunction codexSkillPath(slug: string): string {\n  return resolve(PLUGIN_CODEX_SKILLS_DIR, slug, \"SKILL.md\");\n}\n\n/**\n * The canonical list of Remnic procedural memory skills shipped with the\n * monorepo. The Codex materializer (#378) copies these into\n * `~/.codex/memories/skills/<slug>/SKILL.md`.\n */\nexport const BUILTIN_SKILLS: RemnicSkillSource[] = [\n  {\n    slug: \"remnic-memory-workflow\",\n    staticPath: codexSkillPath(\"remnic-memory-workflow\"),\n    disableModelInvocation: true,\n  },\n  {\n    slug: \"remnic-recall\",\n    staticPath: codexSkillPath(\"remnic-recall\"),\n    disableModelInvocation: false,\n  },\n  {\n    slug: \"remnic-remember\",\n    staticPath: codexSkillPath(\"remnic-remember\"),\n    disableModelInvocation: true,\n  },\n  {\n    slug: \"remnic-search\",\n    staticPath: codexSkillPath(\"remnic-search\"),\n    disableModelInvocation: false,\n  },\n  {\n    slug: \"remnic-entities\",\n    staticPath: codexSkillPath(\"remnic-entities\"),\n    disableModelInvocation: false,\n  },\n  {\n    slug: \"remnic-status\",\n    staticPath: codexSkillPath(\"remnic-status\"),\n    disableModelInvocation: false,\n  },\n];\n"],"mappings":";AAYA,SAAS,qBAAqB;AAC9B,SAAS,SAAS,eAAe;AA8B1B,SAAS,iBAAiB,MAAuB;AAGtD,SAAO,6CAA6C,KAAK,IAAI;AAC/D;AAcA,IAAM,OAAO,QAAQ,cAAc,YAAY,GAAG,CAAC;AACnD,IAAM,0BAA0B,QAAQ,MAAM,MAAM,MAAM,gBAAgB,QAAQ;AAElF,SAAS,eAAe,MAAsB;AAC5C,SAAO,QAAQ,yBAAyB,MAAM,UAAU;AAC1D;AAOO,IAAM,iBAAsC;AAAA,EACjD;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,wBAAwB;AAAA,IACnD,wBAAwB;AAAA,EAC1B;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,eAAe;AAAA,IAC1C,wBAAwB;AAAA,EAC1B;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,iBAAiB;AAAA,IAC5C,wBAAwB;AAAA,EAC1B;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,eAAe;AAAA,IAC1C,wBAAwB;AAAA,EAC1B;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,iBAAiB;AAAA,IAC5C,wBAAwB;AAAA,EAC1B;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,YAAY,eAAe,eAAe;AAAA,IAC1C,wBAAwB;AAAA,EAC1B;AACF;","names":[]}

package/dist/source-attribution.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Inline Source Attribution Protocol (issue #369)
+ *
+ * Extracted facts carry provenance inline inside the fact body, so the
+ * citation survives prompt injection, copy/paste, and LLM quoting. This
+ * complements — never replaces — the YAML frontmatter provenance stored on
+ * disk.
+ *
+ * Default format (matches issue #369 proposal):
+ *
+ *   The foo service uses Redis for rate limiting. [Source: agent=planner, session=abc123, ts=2026-04-10T14:25:07Z]
+ *
+ * Key properties:
+ *   - Inline (part of the body, not metadata).
+ *   - Compact (typically <80 chars of overhead per fact).
+ *   - Machine-parseable by a single regex.
+ *   - Opt-in via `inlineSourceAttributionEnabled` config flag (default off
+ *     for backwards compatibility with existing downstream consumers).
+ *   - Legacy facts without a citation remain fully readable.
+ *
+ * The format template is configurable via `inlineSourceAttributionFormat`
+ * with supported placeholders:
+ *
+ *   {agent}     — principal / agent identifier
+ *   {session}   — full session key (colon-delimited)
+ *   {sessionId} — short stable session id (trailing component)
+ *   {ts}        — extraction timestamp (ISO 8601)
+ *   {date}      — extraction date (YYYY-MM-DD)
+ *
+ * Any privacy-sensitive identifiers should be normalized before being passed
+ * to `formatCitation` — the helper treats them as opaque strings.
+ */
+/** Default citation format template (matches issue #369). */
+declare const DEFAULT_CITATION_FORMAT = "[Source: agent={agent}, session={sessionId}, ts={ts}]";
+/** Sentinel value used when a provenance field is missing. */
+declare const CITATION_UNKNOWN = "unknown";
+interface CitationContext {
+    /** Principal / agent identifier (e.g. resolved via resolvePrincipal). */
+    agent?: string;
+    /** Full session key (e.g. "agent:planner:main"). */
+    session?: string;
+    /**
+     * Opaque short session id. Derived from the trailing component of the
+     * session key when not provided explicitly. Use this for compact formats
+     * that do not need the full colon-delimited session key.
+     */
+    sessionId?: string;
+    /** Extraction timestamp as an ISO 8601 string. */
+    ts?: string;
+}
+interface ParsedCitation {
+    /** Agent identifier parsed from the citation (never crashes on malformed input). */
+    agent?: string;
+    /** Session identifier parsed from the citation. */
+    session?: string;
+    /** Extraction timestamp parsed from the citation. */
+    ts?: string;
+    /** The full matched citation substring. */
+    raw: string;
+}
+/**
+ * Derive a short session id from a full session key.
+ * Falls back to the raw session string if no colon is present.
+ */
+declare function deriveSessionId(session: string | undefined): string | undefined;
+/**
+ * Format an inline citation tag using the provided template.
+ *
+ * Missing context fields fall back to {@link CITATION_UNKNOWN} — the caller
+ * should always get a non-empty, parseable tag.
+ *
+ * Uses a single-pass substitution so that values which themselves contain
+ * placeholder syntax (e.g. an agent literally named `"{ts}"`) cannot be
+ * re-interpreted by subsequent replacement steps. Each placeholder slot
+ * receives exactly one lookup and the substituted value is treated as
+ * terminal text, not template source.
+ */
+declare function formatCitation(ctx: CitationContext, template?: string): string;
+/**
+ * Returns true if the text already carries at least one citation marker.
+ * Safe to call on any string — never throws.
+ */
+declare function hasCitation(text: string): boolean;
+/**
+ * Returns true if `text` already carries a citation produced by `template`
+ * **or** by the default `[Source: ...]` format (for facts that were tagged
+ * before a config change).
+ *
+ * Use this instead of {@link hasCitation} whenever the caller has access to
+ * the configured `inlineSourceAttributionFormat`.
+ *
+ * All-placeholder templates such as `{agent}{sessionId}` have no literal
+ * content to anchor on and therefore cannot be reliably detected without
+ * dedicated sentinel markers. In that case the function returns `false` —
+ * callers that need idempotent dedup for such templates should either adopt
+ * a template with literal delimiters (recommended) or rely on the default
+ * `[Source: ...]` marker detection which is always available via
+ * {@link hasCitation}.
+ */
+declare function hasCitationForTemplate(text: string, template: string): boolean;
+/**
+ * Attach an inline citation to fact text.
+ *
+ * If the text already has a citation — either the default `[Source: ...]`
+ * marker or one produced by the configured template — it is returned unchanged.
+ * Existing provenance is respected and never overwritten. Otherwise the
+ * citation is appended to the trimmed text with a single space separator,
+ * which keeps the marker visually adjacent to the fact body.
+ */
+declare function attachCitation(text: string, ctx: CitationContext, template?: string): string;
+/**
+ * Parse a single inline citation from a piece of text. Returns the first
+ * citation encountered or `null` when none is present. Malformed citations
+ * do not throw — fields that cannot be parsed simply remain `undefined`.
+ */
+declare function parseCitation(text: string): ParsedCitation | null;
+/**
+ * Parse every citation embedded in the text. Always returns an array; empty
+ * when none are present.
+ */
+declare function parseAllCitations(text: string): ParsedCitation[];
+/**
+ * Remove all inline citations from a piece of text.
+ *
+ * Callers that want the raw fact body (for dedup hashing, display, or
+ * comparison) should use this helper instead of hand-rolled regexes so the
+ * whole codebase agrees on the citation syntax.
+ *
+ * Finding 2 fix: when the input contains no citation marker, the input is
+ * returned byte-for-byte unchanged. When a citation IS removed, whitespace
+ * normalization is applied only at each join seam (the single space between
+ * the preceding text and where the citation was), rather than across the
+ * entire string. This preserves markdown hard-break spacing, aligned text,
+ * and code-like snippets in fact bodies that happen to carry a citation.
+ *
+ * Implementation: each citation match is replaced by its "seam fix" — the
+ * content before the match has its trailing whitespace trimmed and then a
+ * single space is appended if any text remains, collapsing only the gap
+ * left by the removed marker. Whitespace elsewhere in the body is untouched.
+ */
+declare function stripCitation(text: string): string;
+/**
+ * Strip an inline citation from text using a specific template regex.
+ *
+ * This is the template-aware counterpart to {@link stripCitation}. When the
+ * caller holds the configured `inlineSourceAttributionFormat`, use this
+ * function to strip citations produced by that template — including custom
+ * templates that differ from the default `[Source: ...]` pattern.
+ *
+ * Behaviour:
+ *  - If the text has a **default-format** citation, delegates to
+ *    {@link stripCitation} (always safe).
+ *  - If the text has a **custom-template** citation detected by
+ *    `hasCitationForTemplate`, builds the template regex and removes every
+ *    occurrence (citations are appended at the end of the fact body by
+ *    {@link attachCitation}).
+ *  - All-placeholder templates (no literal prefix/suffix/separator) cannot
+ *    produce a reliable matcher. `hasCitationForTemplate` already returns
+ *    `false` for such templates, so this function never attempts to strip an
+ *    undetectable citation. The text is returned unchanged when no citation
+ *    is detected.
+ *  - If no citation is detected for the given template, returns the text
+ *    unchanged.
+ *
+ * @returns The stripped text (or the original text when no citation is found).
+ */
+declare function stripCitationForTemplate(text: string, template: string): string;
+
+export { CITATION_UNKNOWN, type CitationContext, DEFAULT_CITATION_FORMAT, type ParsedCitation, attachCitation, deriveSessionId, formatCitation, hasCitation, hasCitationForTemplate, parseAllCitations, parseCitation, stripCitation, stripCitationForTemplate };

package/dist/source-attribution.js

@@ -0,0 +1,27 @@
+import {
+  CITATION_UNKNOWN,
+  DEFAULT_CITATION_FORMAT,
+  attachCitation,
+  deriveSessionId,
+  formatCitation,
+  hasCitation,
+  hasCitationForTemplate,
+  parseAllCitations,
+  parseCitation,
+  stripCitation,
+  stripCitationForTemplate
+} from "./chunk-4KAN3GZ3.js";
+export {
+  CITATION_UNKNOWN,
+  DEFAULT_CITATION_FORMAT,
+  attachCitation,
+  deriveSessionId,
+  formatCitation,
+  hasCitation,
+  hasCitationForTemplate,
+  parseAllCitations,
+  parseCitation,
+  stripCitation,
+  stripCitationForTemplate
+};
+//# sourceMappingURL=source-attribution.js.map

package/dist/source-attribution.js.map

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

package/dist/storage.d.ts

@@ -1,5 +1,6 @@
-import { MemoryCategory, ImportanceScore, MemoryLink, MemoryFrontmatter, MemoryFile, BufferState, MetaState, MemoryActionEvent, MemoryLifecycleEvent, BehaviorSignalEvent, CompressionGuidelineOptimizerState, ContinuityIncidentOpenInput, ContinuityIncidentRecord, ContinuityIncidentCloseInput, ContinuityImprovementLoop, ContinuityLoopUpsertInput, ContinuityLoopReviewInput, FileHygieneConfig, EntityRelationship, EntityActivityEntry, EntityFile, PluginConfig, AccessTrackingEntry, MemoryProjectionCurrentState, MemorySummary, TopicScore } from './types.js';
-import { P as ProjectedMemoryBrowseOptions, i as ProjectedMemoryBrowsePage, j as readProjectedGovernanceRecord } from './memory-projection-store-NxMkbocT.js';
+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 { P as ProjectedMemoryBrowseOptions, a as ProjectedMemoryBrowsePage, b as readProjectedGovernanceRecord } from './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 
 interface ReextractJobRequest {
@@ -46,37 +47,92 @@ declare class ContentHashIndex {
     save(): Promise<void>;
     /** Remove a hash from the index (used when archiving/deleting). */
     remove(content: string): void;
+    /**
+     * Remove a pre-computed SHA-256 hash directly from the index without
+     * re-hashing.  Use this when the caller already holds the stored hash
+     * (e.g. `memory.frontmatter.contentHash`) to avoid the double-hash bug
+     * where `remove(hash)` would compute `hash(hash)` and never match the
+     * entry.
+     */
+    removeByHash(hash: string): void;
+    /**
+     * Add a pre-computed SHA-256 hash directly to the index without re-hashing.
+     * Use this when the caller already holds the stored hash
+     * (e.g. `memory.frontmatter.contentHash`) so that the index records the raw
+     * content hash rather than re-hashing the citation-annotated body.
+     *
+     * @internal Only called from `StorageManager.ensureFactHashIndexAuthoritative`.
+     * Not part of the public API — prefer `add(content)` for external callers.
+     */
+    addByHash(hash: string): void;
     /** Normalize content and compute SHA-256 hash. */
     static normalizeContent(content: string): string;
     /** Normalize content and compute SHA-256 hash. */
     static computeHash(content: string): string;
 }
+/**
+ * Render a structured-attributes map into a stable, canonical string fragment
+ * suitable for appending to enriched memory content before hashing.
+ *
+ * Normalization rules:
+ *   - Keys are trimmed and lowercased (values are trimmed but preserve case)
+ *   - Key-value pairs are sorted alphabetically by normalized key
+ *   - Pairs are joined with "; " and rendered as "key: value"
+ *
+ * Using this helper at BOTH the write path (enrichedContent) and the
+ * dedup-lookup path (dedupContent) guarantees identical output regardless of
+ * the insertion order or casing used by the caller.
+ *
+ * @example
+ *   normalizeAttributePairs({ foo: "bar", BAZ: "qux" })
+ *   // → "baz: qux; foo: bar"
+ */
+declare function normalizeAttributePairs(pairs: Record<string, string>): string;
+declare function compareEntityTimestamps(left?: string, right?: string): number;
+declare function fingerprintEntityStructuredFacts(entity: Pick<EntityFile, "structuredSections">): string | undefined;
+declare function isEntitySynthesisStale(entity: EntityFile): boolean;
 /**
  * Parse an entity markdown file into a structured EntityFile.
  * Backward compatible: old files without new sections get empty arrays.
  */
-declare function parseEntityFile(content: string): EntityFile;
+declare function parseEntityFile(content: string, entitySchemas?: PluginConfig["entitySchemas"]): EntityFile;
 /**
  * Serialize an EntityFile back to markdown.
- * Only emits sections that have content (except Facts which is always emitted).
+ * Writes the compiled-truth + timeline format while remaining parse-compatible
+ * with the legacy in-memory `summary` and `facts` fields.
  */
-declare function serializeEntityFile(entity: EntityFile): string;
+declare function serializeEntityFile(entity: EntityFile, entitySchemas?: PluginConfig["entitySchemas"]): string;
 declare class StorageManager {
     private readonly baseDir;
+    private readonly entitySchemas?;
     private knowledgeIndexCache;
     private static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS;
     private artifactIndexCache;
     private static readonly ARTIFACT_INDEX_CACHE_TTL_MS;
     private static readonly artifactWriteVersionByDir;
     private static readonly memoryStatusVersionByDir;
+    private static readonly coldWriteVersionByDir;
     private static readonly allMemoriesInFlight;
+    private static readonly COLD_SCAN_CACHE_TTL_MS;
+    private static readonly coldMemoriesCache;
     private static readonly QUESTIONS_CACHE_TTL_MS;
     private static readonly questionsCache;
     private factHashIndex;
     private factHashIndexLoadPromise;
     private factHashIndexAuthoritative;
     private factHashIndexAuthoritativePromise;
-    constructor(baseDir: string);
+    /** Optional: set by the orchestrator after construction to enable template-aware citation stripping during legacy hash rebuild. */
+    citationTemplate: string;
+    /** Page-versioning configuration.  Set by the orchestrator after construction. */
+    private _versioningConfig;
+    /** Set the page-versioning configuration.  When `enabled` is false (default), all versioning calls are no-ops. */
+    setVersioningConfig(config: VersioningConfig): void;
+    /**
+     * Snapshot the current content of a page before overwriting.
+     * No-op when versioning is disabled or the file does not yet exist.
+     */
+    private snapshotBeforeWrite;
+    constructor(baseDir: string, entitySchemas?: PluginConfig["entitySchemas"]);
     /** The root directory of this storage instance. */
     get dir(): string;
     private identityFilePath;
@@ -89,8 +145,10 @@ declare class StorageManager {
     private getArtifactWriteVersion;
     private get factsDir();
     private get correctionsDir();
+    private get proceduresDir();
     private get entitiesDir();
     private get stateDir();
+    private get entitySynthesisQueuePath();
     private get factHashIndexReadyPath();
     private getFactHashIndex;
     private ensureFactHashIndexAuthoritative;
@@ -137,6 +195,19 @@ declare class StorageManager {
         memoryKind?: MemoryFrontmatter["memoryKind"];
         expiresAt?: string;
         structuredAttributes?: Record<string, string>;
+        /**
+         * When provided, this string is used as the source for the fact-content
+         * dedup hash index instead of the persisted body (`content`).
+         *
+         * Use this when the persisted body differs from the canonical fact text
+         * — for example when `content` is a citation-annotated variant of a raw
+         * fact. Passing the raw fact as `contentHashSource` ensures that
+         * `hasFactContentHash(rawFact)` returns `true` after the write, so
+         * subsequent extractions of the same logical fact are correctly deduped
+         * even when their citation timestamp differs.
+         */
+        contentHashSource?: string;
+        status?: MemoryStatus;
     }): Promise<string>;
     hasFactContentHash(content: string): Promise<boolean>;
     isFactContentHashAuthoritative(): Promise<boolean>;
@@ -153,7 +224,13 @@ declare class StorageManager {
     }): Promise<string>;
     private readAllArtifactsCached;
     searchArtifacts(query: string, maxResults: number): Promise<MemoryFile[]>;
-    writeEntity(name: string, type: string, facts: string[]): Promise<string>;
+    writeEntity(name: string, type: string, facts: string[], options?: {
+        timestamp?: string;
+        source?: string;
+        sessionKey?: string;
+        principal?: string;
+        structuredSections?: EntityStructuredSection[];
+    }): Promise<string>;
     readProfile(): Promise<string>;
     writeProfile(content: string): Promise<void>;
     /**
@@ -177,8 +254,38 @@ declare class StorageManager {
      *  (bypassing StorageManager.writeMemory) to avoid stale reads. */
     static clearAllStaticCaches(): void;
     /** Cancel any in-flight concurrent read so the next readAllMemories()
-     *  starts a fresh disk scan and sees the just-written data. */
+     *  starts a fresh disk scan and sees the just-written data.
+     *
+     *  Finding UvBq (PR #402 round-11): this method intentionally does NOT
+     *  invalidate the cold-scan cache.  Ordinary hot-tier writes (writeMemory)
+     *  do not change cold-tier content, so evicting the cold cache on every hot
+     *  write was defeating the burst-dedup optimisation — the cold cache was
+     *  cleared before applyTemporalSupersession ran, causing a full cold-tree
+     *  disk scan on every write in a burst.  Cold cache invalidation is handled
+     *  exclusively by invalidateColdMemoriesCache(), which is called only when
+     *  cold content actually changes (hot→cold demotions, writeMemoryFileAtomic
+     *  inside cold/, archiveMemory, etc.). */
     private invalidateAllMemoriesCache;
+    /**
+     * Invalidate the cold-scan cache for this storage root and bump the
+     * on-disk cold-version sentinel so that other processes (gateway, CLI) see
+     * the change immediately on their next readAllColdMemories() call.
+     *
+     * Must be called whenever a memory is written INTO the cold tier — hot→cold
+     * demotion, atomic writes inside cold/, archiving a cold memory, etc.
+     * NOT called on ordinary hot-tier writes (those don't change cold contents).
+     *
+     * Finding UvUy (PR #402 round-11): bumping the sentinel here makes the
+     * per-process in-memory cache safe across process boundaries.
+     */
+    private invalidateColdMemoriesCache;
+    /** Return the current cold-write version counter for this storage root.
+     *  Reads the on-disk sentinel (state/cold-write.log) so it reflects writes
+     *  made by other processes. */
+    private readColdWriteVersion;
+    /** Bump the on-disk cold-write version sentinel and update the in-process
+     *  fallback map.  Called by invalidateColdMemoriesCache(). */
+    private bumpColdWriteVersion;
     private normalizeMemoryReadBatchSize;
     private collectActiveMemoryPaths;
     private readParsedMemoriesFromPaths;
@@ -195,6 +302,32 @@ declare class StorageManager {
         filePaths: string[];
     }>;
     private _readAllMemoriesFromDisk;
+    /**
+     * Read all memories from the cold tier by scanning the entire cold/ root
+     * tree.  Previously this only scanned cold/facts/ and cold/corrections/, but
+     * structuredAttributes can appear on any MemoryCategory (preference, decision,
+     * entity, etc.).  Although buildTierMemoryPath currently routes all
+     * non-correction, non-artifact memories to cold/facts/, scanning the full
+     * coldRoot ensures correctness if that routing ever changes and guards against
+     * files placed in unexpected subdirectories during manual operations or future
+     * refactors.
+     *
+     * Broadened in PR #402 round-6 (Finding UTsP): scanning only facts/ and
+     * corrections/ was a narrower-than-necessary subset of the cold directory
+     * tree.  Correctness trumps the minor performance difference — cold scans
+     * already happen at most once per supersession write.
+     *
+     * Used by applyTemporalSupersession so that memories already demoted to
+     * cold/ can still be marked superseded when a newer hot fact arrives.
+     *
+     * Cached with a TTL (Finding UOGi, PR #402 round-6): back-to-back
+     * structured-attribute writes in the same burst reuse the cached result
+     * instead of re-scanning the cold tree on every call.  The cache is
+     * invalidated whenever a write calls invalidateAllMemoriesCache() (which
+     * covers any hot→cold demotion that changes cold-tier contents) and
+     * expires after COLD_SCAN_CACHE_TTL_MS as a safety net.
+     */
+    readAllColdMemories(): Promise<MemoryFile[]>;
     /**
      * Read archived memory markdown files under archive/.
      * Used by long-term recall fallback when hot recall has no hits.
@@ -340,9 +473,27 @@ declare class StorageManager {
      */
     addEntityAlias(name: string, alias: string): Promise<void>;
     /**
-     * Set or update the summary of an entity file.
+     * Set or rewrite the synthesis layer of an entity file.
+     */
+    updateEntitySynthesis(name: string, synthesis: string, options?: {
+        entityUpdatedAt?: string;
+        synthesisStructuredFactCount?: number;
+        synthesisStructuredFactDigest?: string;
+        synthesisTimelineCount?: number;
+        updatedAt?: string;
+        incrementVersion?: boolean;
+    }): Promise<void>;
+    /**
+     * Backward-compatible alias for legacy callers/tests.
      */
     updateEntitySummary(name: string, summary: string): Promise<void>;
+    readEntitySynthesisQueue(): Promise<string[]>;
+    refreshEntitySynthesisQueue(): Promise<string[]>;
+    removeEntitySynthesisQueueEntries(entityNames: string[]): Promise<void>;
+    migrateEntityFilesToCompiledTruthTimeline(): Promise<{
+        total: number;
+        migrated: number;
+    }>;
     /**
      * Read all entity files and return lightweight EntityFile objects.
      * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
@@ -386,6 +537,16 @@ declare class StorageManager {
      * Get a memory by its ID.
      */
     getMemoryById(id: string): Promise<MemoryFile | null>;
+    /**
+     * Check which of the given memory IDs actually exist on disk.
+     *
+     * Uses a lightweight directory scan (collectActiveMemoryPaths) that reads
+     * file names without parsing frontmatter — much cheaper than readAllMemories()
+     * for simple existence checks like citation usage tracking.
+     *
+     * Returns the subset of `ids` that correspond to real memory files.
+     */
+    filterExistingMemoryIds(ids: string[]): Promise<Set<string>>;
     getProjectedMemoryState(id: string): Promise<MemoryProjectionCurrentState | null>;
     browseProjectedMemories(options: ProjectedMemoryBrowseOptions): Promise<ProjectedMemoryBrowsePage | null>;
     getProjectedGovernanceRecord(): Promise<ReturnType<typeof readProjectedGovernanceRecord>>;
@@ -450,4 +611,4 @@ declare class StorageManager {
     private appendGeneratedMemoryLifecycleEventFailOpen;
 }
 
-export { ContentHashIndex, type MemoryLifecycleEventWriteOptions, type ReextractJobRequest, StorageManager, normalizeEntityName, parseEntityFile, serializeEntityFile };
+export { ContentHashIndex, type MemoryLifecycleEventWriteOptions, type ReextractJobRequest, StorageManager, compareEntityTimestamps, fingerprintEntityStructuredFacts, isEntitySynthesisStale, normalizeAttributePairs, normalizeEntityName, parseEntityFile, serializeEntityFile };

package/dist/storage.js

@@ -1,22 +1,33 @@
 import {
   ContentHashIndex,
   StorageManager,
+  compareEntityTimestamps,
+  fingerprintEntityStructuredFacts,
+  isEntitySynthesisStale,
+  normalizeAttributePairs,
   normalizeEntityName,
   parseEntityFile,
   serializeEntityFile
-} from "./chunk-QWUUMMIK.js";
-import "./chunk-U4PV25RD.js";
-import "./chunk-ESSMF2FR.js";
-import "./chunk-TP4FZJIZ.js";
+} from "./chunk-GV6NLQ4X.js";
+import "./chunk-3WHVNEN7.js";
+import "./chunk-4KAN3GZ3.js";
+import "./chunk-6ZH4TU6I.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
+import "./chunk-6PFRXT4K.js";
+import "./chunk-TP4FZJIZ.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   ContentHashIndex,
   StorageManager,
+  compareEntityTimestamps,
+  fingerprintEntityStructuredFacts,
+  isEntitySynthesisStale,
+  normalizeAttributePairs,
   normalizeEntityName,
   parseEntityFile,
   serializeEntityFile

package/dist/summarizer.js

@@ -1,17 +1,17 @@
 import {
   HourlySummarizer
-} from "./chunk-LP47L3ZX.js";
+} from "./chunk-N42IWANG.js";
 import "./chunk-ETOW6ACV.js";
-import "./chunk-ONRU4L2N.js";
-import "./chunk-MDDAA2AO.js";
+import "./chunk-FEMOX5AD.js";
+import "./chunk-JL2PU6AI.js";
 import "./chunk-LK6SGL53.js";
-import "./chunk-XUHI52HK.js";
-import "./chunk-M5ZBBBJI.js";
-import "./chunk-OOSWAUYB.js";
+import "./chunk-44ICJRF3.js";
+import "./chunk-XZ2TIKGC.js";
 import "./chunk-Y27UJK6V.js";
+import "./chunk-ODWDQNRE.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   HourlySummarizer
 };