@remnic/core 9.69.55 → 9.69.57

package/dist/storage.d.ts

@@ -1,33 +1,1362 @@
-export { C as ContentHashIndex, t as ContentHashIndexLockOptions, u as FactHashIndexNotAuthoritativeError, v as MemoryLifecycleEventWriteOptions, M as MemoryWriteResult, R as ReextractJobRequest, w as SealedWriteExtras, S as StorageManager, W as WriteMemoryOptions, x as buildEntitySchemaCacheKey, y as compareEntityTimestamps, z as compileEntityFacts, A as countEntityStructuredFacts, B as fingerprintEntityStructuredFacts, D as isEntitySynthesisStale, E as isValidBufferSurpriseEvent, G as normalizeFrontmatterForPath, H as normalizeStructuredSectionFacts, I as normalizeStructuredSectionFactsWithOrigins, p as parseEntityFile, J as parseFrontmatter, K as parseFrontmatterStringValue, s as serializeEntityFile } from './storage-CMm-3aD3.js';
-import './types-Du6VdoAg.js';
-import './corpus-read-cancellation.js';
-import './artifact-search.js';
-import './active-context-transform.js';
-export { normalizeEntityName } from './entity-id-normalization.js';
-import './page-versioning.js';
-import './consolidation-operator.js';
-import './memory-projection-store.js';
-import './write-envelope.js';
-export { normalizeAttributePairs, stripAttributesSuffix } from './structured-attributes.js';
-import './types-continuity.js';
-import './utils/serialize-mutations.js';
-import './message-parts/index.js';
-import './bounded-jsonl-state.js';
-import './operator-doctor-types.js';
-import './external-wiki-config.js';
-import './recall-state-view.js';
-import './contradiction-config.js';
-import './graph-path-scoring-config.js';
-import './background-generation-config.js';
-import './deep-recall-config.js';
-import './recall-navigation-config.js';
-import './recall-recognition-tier.js';
-import './causal-trajectory.js';
-import './objective-state.js';
-import './active-context-config.js';
-import './local-llm-config.js';
-import './semantic-merge-config.js';
-import './context-summary.js';
-import './maintenance/memory-governance.js';
-import './runtime/better-sqlite.js';
-import 'better-sqlite3';
+import { type CorpusReadOptions } from "./corpus-read-cancellation.js";
+import { type ArtifactSearchOptions } from "./artifact-search.js";
+import { type WindowedMemoryReadOptions, type WindowedMemoryReadResult } from "./storage/memory-read-store.js";
+import type { ContextTransformTelemetryRecord } from "./active-context-transform.js";
+import { type DrainPendingLifecycleForSyncResult } from "./storage/memory-lifecycle-ledger-access.js";
+export { normalizeEntityName } from "./entity-id-normalization.js";
+import { type VersioningConfig } from "./page-versioning.js";
+import { FusionArtifactStore } from "./wearables/fusion/index.js";
+import { MeetingRecordStore } from "./meetings/store.js";
+import { type ConsolidationOperator } from "./consolidation-operator.js";
+import { TombstoneStore, type TombstoneReason, type TombstoneCreatedBy, type TombstoneStats } from "./lifecycle/tombstones.js";
+import { type SupersessionAuditOptions } from "./storage/supersession-side-effects.js";
+import type { AccessTrackingEntry, BufferState, ContinuityIncidentCloseInput, ContinuityIncidentOpenInput, ContinuityIncidentRecord, ContinuityImprovementLoop, ContinuityLoopReviewInput, ContinuityLoopUpsertInput, EntityActivityEntry, EntityFile, EntityRelationship, EntityStructuredSection, ImportanceScore, MemoryCategory, MemoryFile, MemoryFrontmatter, MemoryLink, MemoryStatus, MemorySubject, MemoryActionEvent, MemoryLifecycleEvent, MemoryProjectionCurrentState, BehaviorSignalEvent, BufferSurpriseEvent, MemorySummary, MetaState, CompressionGuidelineOptimizerState, PluginConfig, TopicScore, FileHygieneConfig, ProvenanceSource } from "./types.js";
+import { ContentHashIndex, FactHashIndexNotAuthoritativeError, type ContentHashIndexLockOptions } from "./storage/content-hash-index.js";
+import { TombstoneBlockedCaptureIndexHost, type TombstoneBlockedCaptureIndexOptions } from "./storage/tombstone-blocked-capture-index.js";
+export { ContentHashIndex, FactHashIndexNotAuthoritativeError };
+export type { ContentHashIndexLockOptions };
+export { compareEntityTimestamps, compileEntityFacts, countEntityStructuredFacts, fingerprintEntityStructuredFacts, isEntitySynthesisStale, normalizeStructuredSectionFacts, normalizeStructuredSectionFactsWithOrigins, } from "./storage/entity-timeline.js";
+import { type ProjectedMemoryBrowseOptions, type ProjectedMemoryBrowsePage, readProjectedGovernanceRecord } from "./memory-projection-store.js";
+import { type SealedMemoryEnvelope } from "./write-envelope.js";
+export interface ReextractJobRequest {
+    memoryId: string;
+    model: string;
+    requestedAt: string;
+    source: "cli-migrate";
+}
+export interface MemoryLifecycleEventWriteOptions {
+    at?: Date;
+    actor?: string;
+    reasonCode?: string;
+    ruleVersion?: string;
+    relatedMemoryIds?: string[];
+    correlationId?: string;
+}
+export declare function parseFrontmatterStringValue(rawValue: string | undefined): string | undefined;
+export declare function parseFrontmatter(raw: string): {
+    frontmatter: MemoryFrontmatter;
+    content: string;
+} | null;
+export declare function normalizeFrontmatterForPath(frontmatter: MemoryFrontmatter, pathRel: string, content?: string): MemoryFrontmatter;
+import { stripAttributesSuffix } from "./structured-attributes.js";
+export { stripAttributesSuffix };
+export { normalizeAttributePairs } from "./structured-attributes.js";
+/**
+ * Parse an entity markdown file into a structured EntityFile.
+ * Backward compatible: old files without new sections get empty arrays.
+ */
+export declare function parseEntityFile(content: string, entitySchemas?: PluginConfig["entitySchemas"]): EntityFile;
+/**
+ * Serialize an EntityFile back to markdown.
+ * Writes the compiled-truth + timeline format while remaining parse-compatible
+ * with the legacy in-memory `summary` and `facts` fields.
+ */
+export declare function serializeEntityFile(entity: EntityFile, entitySchemas?: PluginConfig["entitySchemas"], okfType?: boolean): string;
+export declare function buildEntitySchemaCacheKey(entitySchemas?: PluginConfig["entitySchemas"]): string;
+/**
+ * Full-schema type guard for a `BUFFER_SURPRISE` telemetry row
+ * (issue #563 PR 3).
+ *
+ * The reader applies `limit` over the count of VALID rows, so
+ * applying only a partial check (e.g. "has a finite surpriseScore")
+ * and then deferring the rest of validation to
+ * `reportBufferSurpriseDistribution` would silently count
+ * schema-incomplete rows toward the limit, pushing genuinely-valid
+ * earlier rows out of the report window. Validate everything the
+ * downstream report requires at read time so the limit semantics and
+ * the distribution semantics stay consistent.
+ */
+export declare function isValidBufferSurpriseEvent(value: unknown): value is BufferSurpriseEvent;
+/** Result of {@link StorageManager.writeMemory} (issue #1645). Carries the
+ * persisted id PLUS the non-resurrection tombstone-block outcome (#1579) so
+ * post-write callers can observe it — NEVER a silent no-op (rule 34). */
+export interface MemoryWriteResult {
+    /** The persisted memory id. */
+    id: string;
+    /** True when the #1579 tombstone chokepoint downgraded this write to
+     * `pending_review` + `blockedBy`. Callers gate active post-write work on this. */
+    tombstoneBlocked: boolean;
+    /** The tombstone id that blocked the write, when `tombstoneBlocked`. */
+    blockedBy?: string;
+    /** Existing pending-review memory id when a blocked write coalesced with it. */
+    duplicateOf?: string;
+}
+/**
+ * Options accepted by `StorageManager.writeMemory` (extracted verbatim in
+ * issue #1989 PR2 so `SealedWriteExtras` can be derived from it — the
+ * sealed-envelope path takes envelope-owned fields from the envelope and
+ * everything else from these extras).
+ */
+export interface WriteMemoryOptions {
+    actor?: string;
+    confidence?: number;
+    tags?: string[];
+    entityRef?: string;
+    source?: string;
+    supersedes?: string;
+    lineage?: string[];
+    importance?: ImportanceScore;
+    links?: MemoryLink[];
+    intentGoal?: string;
+    intentActionType?: string;
+    intentEntityTypes?: string[];
+    artifactType?: MemoryFrontmatter["artifactType"];
+    sourceMemoryId?: string;
+    sourceTurnId?: string;
+    memoryKind?: MemoryFrontmatter["memoryKind"];
+    expiresAt?: string;
+    validAt?: string;
+    observedAt?: string;
+    eventTimeSource?: "extracted" | "assumed";
+    invalidAt?: 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;
+    /**
+     * When true, writeMemory marks the fact-hash index dirty via `.add(...)`
+     * but does NOT flush it to disk — the caller is responsible for a
+     * subsequent batch save (issue #1909). The extraction persist path sets
+     * this and relies on the orchestrator's authoritative
+     * `saveContentHashIndexes()` batch save plus a per-storage union flush,
+     * avoiding a whole-index (which grows with corpus size) rewrite per fact.
+     * Default false: every
+     * other (single-write) caller keeps the immediate, crash-safe save.
+     */
+    deferHashIndexSave?: boolean;
+    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;
+    /**
+     * Faithfulness gate verdict (issue #1576). When provided, persisted to
+     * frontmatter so downstream readers (TrustScore #1577, review queue)
+     * can consume it. Absent = gate was off or fact predates #1576.
+     */
+    faithfulness?: import("./types.js").FaithfulnessFrontmatter;
+    /**
+     * Claim-level provenance spans (issue #1575 PR 2). When provided,
+     * persisted to frontmatter so downstream readers (memory_get, x-ray,
+     * faithfulness gate #1576) can consume them. Absent = fact predates
+     * #1575 or provenance was disabled.
+     */
+    sources?: ProvenanceSource[];
+    provenance?: "verified" | "unverified" | "none";
+    origin?: string;
+    sourceConnector?: string;
+    toolScoped?: true;
+    subject?: MemorySubject;
+}
+/**
+ * `WriteMemoryOptions` minus the fields a `SealedMemoryEnvelope` owns.
+ * Passing an envelope-owned field twice is a compile error by construction.
+ */
+export type SealedWriteExtras = Omit<WriteMemoryOptions, "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector" | "origin" | "subject">;
+export declare class StorageManager extends TombstoneBlockedCaptureIndexHost {
+    private readonly baseDir;
+    private readonly entitySchemas?;
+    private knowledgeIndexCache;
+    private readonly deletionRevisionStore;
+    private readonly casRevisions;
+    private artifactIndexCache;
+    private projectionLedgerLagManager;
+    private static readonly loadedMemorySnapshots;
+    static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS = 600000;
+    /** Read by storage/memory-read-store.ts (decomposition). */
+    static readonly ARTIFACT_INDEX_CACHE_TTL_MS = 60000;
+    private static readonly artifactWriteVersionByDir;
+    private static readonly memoryStatusVersionByDir;
+    private static readonly memoryCorpusVersionByDir;
+    private static readonly entityMutationVersionByDir;
+    private static readonly secureStoreEntityCacheKeyIds;
+    private static nextSecureStoreEntityCacheKeyId;
+    private static readonly coldWriteVersionByDir;
+    /**
+     * Process-wide default for the hot-memories result cache gate (issue #1902).
+     * Set once from config by the orchestrator/access layer via
+     * setHotMemoriesCacheDefault() so that EVERY StorageManager — including the
+     * ephemeral instances recall sub-stages (verified-recall, semantic-rule
+     * verification, ...) construct over the same dir — honors the operator's
+     * hotMemoriesCacheEnabled setting. The constructor option overrides this
+     * per-instance (tests). Defaults true (cache on).
+     */
+    private static hotMemoriesCacheDefault;
+    /**
+     * Per-memory-directory override of the hot-cache gate (issue #1902, Codex
+     * P2). setHotMemoriesCacheDefault(memoryDir, enabled) registers the
+     * operator's setting keyed by dir, so a StorageManager constructed over that
+     * dir honors ITS owning orchestrator's config — not merely the last
+     * orchestrator constructed in the process. Unregistered dirs fall back to
+     * the process-wide default above.
+     */
+    private static readonly hotMemoriesCacheDefaultByDir;
+    /**
+     * Process-wide TTL (ms) safety net for the hot cache (issue #1902). Bounds
+     * how long a version-keyed entry is served before a fresh disk scan, so
+     * external filesystem edits (manual/git/editor) that don't bump the sentinel
+     * self-heal. Set from config by the orchestrator via setHotMemoriesCacheDefault.
+     * 0 disables the TTL (version invalidation only). Default 60s.
+     */
+    private static hotMemoriesCacheTtlMs;
+    /**
+     * Per-memory-directory override of the hot-cache TTL (issue #1902, Codex P2),
+     * mirroring hotMemoriesCacheDefaultByDir. Registered by
+     * setHotMemoriesCacheDefault so two orchestrators in one process with
+     * different TTLs don't clobber each other's setting. Unregistered dirs fall
+     * back to the process-wide default above.
+     */
+    private static readonly hotMemoriesCacheTtlByDir;
+    /**
+     * Whether the process-wide hot-cache fallbacks (hotMemoriesCacheDefault /
+     * hotMemoriesCacheTtlMs) have been seeded by the first
+     * setHotMemoriesCacheDefault call (issue #1902, Cursor Low). Only the first
+     * registration seeds them; later registrations touch ONLY their per-dir map
+     * entry. This makes the process-wide fallback deterministic (first-writer,
+     * by init order) instead of last-writer-wins, so a second orchestrator with
+     * a divergent config cannot silently flip the fallback that unregistered
+     * dirs resolve to. All REGISTERED dirs are isolated by the per-dir maps.
+     */
+    private static hotMemoriesCacheProcessDefaultSeeded;
+    /**
+     * Per-memory-directory gate for scope-aware cache invalidation (issue #1904).
+     * Registered from config by the orchestrator via
+     * setScopedCacheInvalidationDefault() so every StorageManager built over a
+     * memory dir — including ephemeral recall sub-stage instances — honors the
+     * operator's setting. Unregistered dirs default to `true` (scoped on). Set
+     * `false` to restore the pre-#1904 full-clear-per-write behavior (rollback
+     * lever). Read once per write via isScopedCacheInvalidationEnabled().
+     */
+    private static readonly scopedCacheInvalidationByDir;
+    /** Read by storage/memory-read-store.ts (decomposition). */
+    static readonly COLD_SCAN_CACHE_TTL_MS = 30000;
+    /** Read by storage/memory-read-store.ts (decomposition). */
+    static readonly coldMemoriesCache: Map<string, {
+        memories: MemoryFile[];
+        loadedAt: number;
+        coldVersion: number;
+        keyId: string;
+    }>;
+    /** Read by storage/memory-read-store.ts (decomposition). */
+    static readonly QUESTIONS_CACHE_TTL_MS = 60000;
+    /** Read by storage/memory-read-store.ts (decomposition). */
+    static readonly questionsCache: Map<string, {
+        questions: Array<{
+            id: string;
+            question: string;
+            context: string;
+            priority: number;
+            resolved: boolean;
+            created: string;
+            filePath: string;
+        }>;
+        loadedAt: number;
+    }>;
+    private factHashIndex;
+    private factHashIndexLoadPromise;
+    private factHashIndexAuthoritative;
+    private factHashIndexAuthoritativePromise;
+    /**
+     * Fact-ONLY hash membership (PR #2016 / issue #2474) lives on the shared
+     * `ContentHashIndex` fact-only partition (`addFact*` / `hasFact*` /
+     * `removeFactByHash`), not a parallel set here. The partition carries only
+     * `category === "fact"` hashes and is the sole source for
+     * `hasFactContentHash`, so an over-included non-fact body can never
+     * suppress a real fact candidate. In-memory only; never persisted — every
+     * authoritative corpus rebuild repopulates it via
+     * `ContentHashIndex.clear()` + `addFactByHash`.
+     */
+    /** Optional lock/retry tuning for the fact-hash index cross-process lock (PR #2016; tests inject tight budgets). */
+    factHashIndexLockOptions: ContentHashIndexLockOptions;
+    private readonly secureAppendChains;
+    /**
+     * Cache of "is this file encrypted?" keyed by absolute path, VALIDATED by file
+     * identity (size + mtimeMs) — issue #1909 review round 10 finding 1. A prior
+     * design cached only a boolean and relied on this instance's own writes to
+     * invalidate it; a PEER process encrypting the file would not invalidate,
+     * leaving a stale `false` that made the append path write RAW bytes into an
+     * encrypted file (corruption). Now each entry records the (size, mtime) the
+     * classification was read at; `isEncryptedFileHeader` re-sniffs (header-only)
+     * whenever the on-disk identity no longer matches, so a foreign rewrite is
+     * detected. The whole-file read is still never performed.
+     */
+    private readonly secureFileEncryptionSniffCache;
+    private offlineSyncDigestCache;
+    private offlineSyncDigestCacheLoadPromise;
+    private offlineSyncDigestCacheWriteChain;
+    private offlineSyncDigestCacheWriteTimer;
+    /** Optional: set by the orchestrator after construction to enable template-aware citation stripping during legacy hash rebuild. */
+    citationTemplate: string;
+    /** Post-write catalog hook (#1522). Installed by the namespace router; fire-and-forget. */
+    onCatalogWrite?: () => void;
+    /** Post-write embedding hook (#2019). Installed by the orchestrator; fire-and-forget. */
+    onMemoryWrite?: (filePath: string) => void;
+    private notifyMemoryWrite;
+    private notifyCatalogWrite;
+    /**
+     * Whether pure state-file writes touch the namespace catalog (issue #1903).
+     * Set by `NamespaceStorageRouter.bindCatalogWriteHook` from
+     * `namespacesCatalogTouchStateWrites` (default false). State files
+     * (`state/buffer.json`, ledgers, indexes) are not namespace memory data, so by
+     * default their writes do NOT record a catalog touch.
+     */
+    touchStateWrites: boolean;
+    /**
+     * Post-write catalog hook, gated by file path (issue #1903). Namespace data
+     * (`facts/`, `cold/`, `entities/`, `artifacts/`, `profile.md`, ...) lives
+     * OUTSIDE `stateDir`, so a data write always touches; a write under `stateDir`
+     * is a pure state write and is skipped unless `touchStateWrites` is enabled.
+     */
+    protected notifyCatalogWriteForPath(filePath: string): void;
+    /** Whether `filePath` resolves to `stateDir` itself or a path contained in it. */
+    private isStateFilePath;
+    private tombstoneStore;
+    private tombstoneStoreLoadPromise;
+    private tombstonesConfig;
+    /** 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;
+    /**
+     * At-rest encryption key (issue #690 PR 3/4).
+     *
+     * When non-null, every memory file read is decrypted and every write
+     * is encrypted using the secure-fs layer.  When null, the storage
+     * layer operates in plain-text mode (legacy/unencrypted store).
+     *
+     * Set by the orchestrator after init/unlock; cleared on lock.
+     * The key buffer is NEVER logged or serialized.
+     */
+    private _secureStoreKey;
+    /**
+     * When true (and `_secureStoreKey` is non-null), new writes are
+     * encrypted.  Set to false to pause encryption of new writes while
+     * still decrypting existing files.
+     */
+    private _secureStoreEncryptOnWrite;
+    /**
+     * When true, the secure-store is configured as required — writes
+     * MUST be encrypted and a locked store MUST reject writes rather
+     * than silently falling back to plaintext.  Set by the orchestrator
+     * from `resolveRecallAuxiliaryCapabilities(config).secureStore`.
+     */
+    private _secureStoreRequired;
+    /**
+     * Set or clear the at-rest encryption key.
+     *
+     * Pass a 32-byte Buffer to enable encryption; pass null to clear
+     * (lock) the store. The caller is responsible for key lifecycle —
+     * this method does not zero the buffer on replacement; the keyring
+     * module (`keyring.ts`) owns zeroization. The setter remains synchronous
+     * for existing consumers; call `setSecureStoreKeyAndWait` when unlock must
+     * await migration.
+     */
+    setSecureStoreKey(key: Buffer | null, encryptOnWrite?: boolean): void;
+    setSecureStoreKeyAndWait(key: Buffer | null, encryptOnWrite?: boolean): Promise<void>;
+    private applySecureStoreKey;
+    private getEntityCacheSecureStoreKey;
+    /**
+     * Secure-store key identity for the version-keyed hot/archive memory caches
+     * (issue #1902, Codex P1). Scopes cached DECRYPTED corpora by the key that
+     * decrypted them, so a locked/unkeyed StorageManager for the same baseDir
+     * never reads content another instance decrypted under a key (which would
+     * bypass the locked-store error). Plaintext and locked stores share the ""
+     * namespace; an unlocked encrypted store uses its per-key id.
+     */
+    hotCacheKeyId(): string;
+    /**
+     * Resolved hot-cache gate for THIS store (issue #1902, Cursor Medium): the
+     * per-instance override if one was passed, else the per-dir/process default.
+     * Recall sub-stages (verified-recall, semantic-rule) read this to honor the
+     * operator's opt-out for their derived caches even when the caller omits the
+     * flag in options.
+     */
+    isHotCacheEnabled(): boolean;
+    /**
+     * Effective hot-cache TTL (ms) for this store's dir (issue #1902): the per-dir
+     * registration if present, else the process-wide default. 0 disables the TTL.
+     */
+    hotCacheTtlMs(): number;
+    /**
+     * True if `p` lives in this store's cold/ or archive/ tier (issue #1902,
+     * Codex P2). Determined RELATIVE to baseDir — a substring scan of the
+     * absolute path would misclassify every active path when memoryDir itself is
+     * nested under a dir literally named "cold" or "archive" (e.g.
+     * /srv/cold/remnic), skipping the patch and stranding a stale hot entry.
+     */
+    private isColdOrArchiveTierPath;
+    /**
+     * Mark the secure-store as required for this storage instance.
+     * When required and locked, writes throw SecureStoreLockedError
+     * rather than silently writing plaintext.
+     */
+    setSecureStoreRequired(required: boolean): void;
+    /** Return true iff the secure-store key is currently set (store is unlocked). */
+    isSecureStoreUnlocked(): boolean;
+    /** Whether a state-file write encrypts at rest (encrypt-on-write on AND key
+     *  set) — the write mode lifecycle compaction reserves the envelope for (#2033). */
+    willEncryptStateWrites(): boolean;
+    /**
+     * Resolve the effective write key: null when encrypt-on-write is off or the
+     * store is unlocked-optional; the key when set; else throws
+     * SecureStoreLockedError under a required-but-locked store (PR #767) instead
+     * of silently writing plaintext.
+     *
+     * `forceEncrypt` overrides the encrypt-on-write policy flag ONLY (issue
+     * #2033): a lifecycle-ledger compaction of an already-encrypted ledger/backup
+     * must preserve encryption at rest even when `secureStoreEncryptOnWrite` is
+     * paused, or it would silently downgrade encrypted state to plaintext. It
+     * never bypasses the LOCK: when the store has no key it still returns null
+     * (optional) or throws (required), so a keyless caller can never fabricate an
+     * encrypted write.
+     */
+    private resolveWriteKey;
+    /**
+     * Snapshot the current content of a page before overwriting.
+     * 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>;
+    private readonly hotMemoriesCacheEnabled;
+    constructor(baseDir: string, entitySchemas?: PluginConfig["entitySchemas"], 
+    /**
+     * Hot-memories result cache gate (issue #1902). When omitted, resolves to
+     * the per-directory default registered by setHotMemoriesCacheDefault()
+     * (falling back to the process-wide default); pass an explicit boolean to
+     * override per-instance (tests, memory-constrained readers).
+     */
+    hotMemoriesCacheEnabledOverride?: boolean);
+    /** Set the process-wide hot-memories cache default (issue #1902). The
+     *  orchestrator/access layer calls this with the operator's
+     *  hotMemoriesCacheEnabled config so the escape hatch reaches every
+     *  StorageManager, including ephemeral recall-sub-stage instances. Only an
+     *  explicit `false` disables; `undefined` (e.g. a cast test config missing
+     *  the field) leaves the cache on. */
+    static setHotMemoriesCacheDefault(memoryDir: string, enabled: boolean | undefined, ttlMs?: number): void;
+    /** Register the operator's scope-aware cache invalidation gate for a memory
+     *  dir (issue #1904). The orchestrator/access layer calls this with
+     *  the operator's scopedCacheInvalidationEnabled flag so the setting reaches every
+     *  StorageManager built over the dir, including ephemeral recall-sub-stage
+     *  instances. Only an explicit `false` disables; `undefined` leaves it on. */
+    static setScopedCacheInvalidationDefault(memoryDir: string, enabled: boolean | undefined): void;
+    /** OKF `type` emission gate registrations per memory dir (issue #1946). */
+    private static readonly okfConformanceByDir;
+    /** Register the OKF conformance gate for a memory dir. Unregistered dirs default to
+     *  conformance-on; namespace child dirs (<memoryDir>/namespaces/<tok>) inherit the
+     *  nearest registered ancestor. Only an explicit `false` disables. */
+    static setOkfConformanceDefault(memoryDir: string, enabled: boolean | undefined): void;
+    okfConformanceEnabled(): boolean;
+    /**
+     * The LIVE class object of this instance (issue #1809 review of the
+     * storage decomposition): extracted store modules must read/write the
+     * shared static caches (questionsCache, coldMemoriesCache, ...) through
+     * the SAME class binding the host methods use. Referencing the imported
+     * `StorageManager` symbol from a split bundle chunk can yield a second
+     * class copy with its own statics, split-braining the caches
+     * (resolveQuestion clears copy A while readQuestions reads copy B).
+     */
+    get storageManagerClass(): typeof StorageManager;
+    /** The root directory of this storage instance. */
+    /** MemoryReadStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+    private _memoryReadStore;
+    private get memoryReadStore();
+    /** EntityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+    private _entityStore;
+    private get entityStore();
+    /** IdentityContinuityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+    private _identityContinuityStore;
+    private get identityContinuityStore();
+    get dir(): string;
+    private identityFilePath;
+    private versionFilePath;
+    private bumpSharedVersion;
+    private readSharedVersion;
+    protected bumpMemoryStatusVersion(): void;
+    getMemoryStatusVersion(): number;
+    /**
+     * Entity content revision used by migration discovery and entity-page cache coherence.
+     */
+    getEntityMutationVersion(): number;
+    protected bumpEntityMutationVersion(): void;
+    /**
+     * Corpus version sentinel for the hot-memories result cache (#1902).
+     * Distinct from memory-status: bumps on EVERY memory-file mutation so the
+     * version-keyed hot cache stays coherent across processes, WITHOUT
+     * invalidating the version-keyed entity cache on every plain fact create.
+     */
+    getMemoryCorpusVersion(): number;
+    /**
+     * Bump only — NOT invalidateAllForDir (that would drop the very hot
+     * entry the write path just patched).
+     */
+    protected bumpMemoryCorpusVersion(): void;
+    getArchiveMutationVersion(): number;
+    /**
+     * Corpus bump reporting whether THIS process's append was the only one
+     * since the pre-bump size (#1902, Codex P1): the `exclusive` flag lets
+     * patchHotMemoriesCache refuse to re-key its locally patched corpus at a
+     * version already reflecting a peer's still-unread concurrent append.
+     */
+    private bumpMemoryCorpusVersionExclusive;
+    protected bumpArtifactWriteVersion(): number;
+    private getArtifactWriteVersion;
+    private get wearablesDir();
+    /**
+     * Resolve the on-disk path for a source/day transcript. Throws on
+     * malformed inputs — source ids and dates reach this from CLI/MCP/HTTP
+     * surfaces and must never become path traversal.
+     */
+    wearableTranscriptPath(sourceId: string, date: string): string;
+    writeWearableDayTranscript(sourceId: string, date: string, serialized: string): Promise<void>;
+    /** Read a stored day transcript; null when the day has no file. */
+    readWearableDayTranscript(sourceId: string, date: string): Promise<string | null>;
+    listWearableTranscriptDays(sourceId?: string): Promise<Array<{
+        source: string;
+        date: string;
+    }>>;
+    private _fusionStore?;
+    /** Derived fusion-day IO; file IO lives in wearables/fusion (#1810). */
+    fusionArtifactStore(): FusionArtifactStore;
+    private _meetingRecordStore?;
+    /**
+     * Meeting record IO (issue #1900). Records live under `<baseDir>/meetings/`
+     * — inside the QMD collection root (full-text searchable) but outside the
+     * memory scan roots — and inherit the same encrypted-at-rest + atomic-write +
+     * symlink-containment semantics as memories via the shared secure IO port.
+     */
+    meetingRecordStore(): MeetingRecordStore;
+    /**
+     * Locate a wearable-sourced memory by exact (trimmed) content,
+     * ignoring the "[Attributes: ...]" suffix writeMemory appends for
+     * structuredAttributes — callers pass the raw fact text. Used by the
+     * smart trust pipeline to find an earlier borderline write when the
+     * same fact re-extracts with stronger evidence.
+     */
+    findWearableMemoryByContent(content: string): Promise<{
+        id: string;
+        status: MemoryStatus | undefined;
+    } | null>;
+    /**
+     * Promote a pending_review wearable memory to active in place,
+     * merging updated trust evidence into structuredAttributes. Returns
+     * false when the memory is missing or no longer pending_review (a
+     * concurrent review decision wins), or when the row is tombstone-blocked
+     * (`blockedBy` — issue #1579 threads OcuDx/Ocu1l): writeMemoryFrontmatter
+     * bypasses the writeMemory chokepoint, so a blocked row must first be
+     * cleared via revokeTombstone before promotion can proceed.
+     */
+    promoteWearableMemory(id: string, attributeUpdates: Record<string, string>, confidence?: number): Promise<boolean>;
+    /**
+     * Demote a pending_review wearable memory to rejected when a re-pass
+     * produced an explicit judge-reject verdict, merging the evidence.
+     * Returns false when the memory is missing or no longer
+     * pending_review — active rows are NEVER auto-demoted (operator
+     * approvals and accrued recall signals win; contradiction scans and
+     * supersession own active-row retirement).
+     */
+    demoteWearableMemory(id: string, attributeUpdates: Record<string, string>): Promise<boolean>;
+    private get factsDir();
+    private get correctionsDir();
+    private get proceduresDir();
+    private get reasoningTracesDir();
+    private get entitiesDir();
+    private resolveEntityFilePath;
+    private readStorageSecureFile;
+    readDependencyPropagationQueueFile(filePath: string): Promise<string>;
+    writeDependencyPropagationQueueFile(filePath: string, content: string): Promise<void>;
+    protected writeStorageSecureFile(filePath: string, content: string | Buffer, forceEncrypt?: boolean): Promise<void>;
+    protected assertManagedStoragePath(filePath: string, method: string): string;
+    readDeletionRevisions(): Promise<ReadonlyMap<string, number>>;
+    hasCommittedInvalidation(memory: Pick<MemoryFile, "content" | "frontmatter">): Promise<boolean>;
+    readCasRevision: (filePath: string) => Promise<string | undefined>;
+    readCasRevisionStatus: (filePath: string) => Promise<import("./storage/cas-revision-store.js").CasRevisionReadStatus>;
+    readDurableFileDigest: (filePath: string) => Promise<string | null>;
+    protected beginDurableMemoryRevision: (pathname: string, expectedContent?: string | Buffer | null) => Promise<import("./storage/cas-revision-store.js").CasRevisionTransaction>;
+    private recordCommittedInvalidation;
+    private clearCommittedInvalidation;
+    recordReplicatedDeletionRevision(filePath: string, mtimeMs: number): Promise<void>;
+    protected writeManagedStorageFile(filePath: string, write: () => Promise<void>): Promise<void>;
+    protected deleteManagedStorageFileDurable(filePath: string, deletionMtimeMs?: number | null): Promise<boolean>;
+    readOfflineSyncFile(filePath: string): Promise<Buffer>;
+    digestOfflineSyncFile(filePath: string): Promise<{
+        sha256: string;
+        bytes: number;
+    }>;
+    private loadOfflineSyncDigestCache;
+    private readOfflineSyncDigestCache;
+    private rememberOfflineSyncDigest;
+    private scheduleOfflineSyncDigestCacheWrite;
+    private queueOfflineSyncDigestCacheWrite;
+    private offlineSyncFileIsEncrypted;
+    writeOfflineSyncStagingFile(filePath: string, content: Buffer): Promise<void>;
+    createContentHashIndex(): ContentHashIndex;
+    private appendStorageSecureFile;
+    /**
+     * Classify a file as encrypted by reading ONLY the fixed-size magic header
+     * (issue #1909), never the whole file. The result is cached per-path but
+     * VALIDATED against the file's (size, mtime) identity (review round 10 finding
+     * 1): a `stat` on each call is O(1), and the 12-byte header read happens only
+     * on a cache miss or when the on-disk identity changed — so a PEER process
+     * rewriting/encrypting the file is detected and we never append raw bytes into
+     * an encrypted body. ENOENT and short/empty files classify as not-encrypted
+     * (fall through to a plain `appendFile`).
+     */
+    private isEncryptedFileHeader;
+    private appendStorageSecureFileUnlocked;
+    private get stateDir();
+    private get offlineSyncDigestCachePath();
+    private get entitySynthesisQueuePath();
+    /**
+     * The on-disk tombstone log path. Lives under `<stateDir>/tombstones.jsonl`
+     * so it is co-located with the fact-hash index and encrypted at rest when
+     * the secure-store is enabled (the StorageManager's secure read/write
+     * helpers are injected into the store).
+     */
+    private get tombstonesPath();
+    /**
+     * Configure the tombstone invariant for this storage instance. Installed
+     * by the orchestrator after construction (same pattern as
+     * `setVersioningConfig` / `citationTemplate`). When `enabled` is false
+     * (default until the orchestrator wires config), the chokepoint check is a
+     * no-op — pre-feature behavior for rollback safety (rule 30).
+     */
+    setTombstonesConfig(config: {
+        enabled: boolean;
+        semanticMatch: boolean;
+        semanticThreshold: number;
+        namespace: string;
+    }): void;
+    private buildTombstoneStore;
+    /**
+     * Lazily load the tombstone store. Mirrors the fact-hash-index lazy-load
+     * pattern: a single in-flight load promise dedups concurrent first-access.
+     * The cross-process staleness probe lives inside the store now (#1579): on
+     * each cached access it stats its own file and invalidates if a peer process
+     * appended, so the next lookup reloads from disk. If the probe just
+     * invalidated the store, fall through to the reload branch — returning null
+     * here was the original regression (the chokepoint threw and failed OPEN).
+     */
+    getTombstoneStore(): Promise<TombstoneStore>;
+    /**
+     * Whether tombstones are enabled on this storage. Callers that need to
+     * distinguish "tombstones disabled" (null return is expected) from
+     * "persistence failed" (appendTombstone swallows store errors and also
+     * returns null) use this to fail closed when enabled (#1580 review OgIqp).
+     */
+    isTombstonesEnabled(): boolean;
+    /**
+     * Append a tombstone for a retired memory (issue #1579 emitters).
+     * Best-effort: a tombstone append failure MUST NOT fail the supersession /
+     * correction that triggered it (gotcha #13 / rule 34). The memory is
+     * already retired on disk; the tombstone is the non-resurrection guard.
+     */
+    appendTombstone(input: {
+        reason: TombstoneReason;
+        createdBy: TombstoneCreatedBy;
+        sourceMemoryId: string;
+        rawContent: string;
+        entityRef?: string;
+        supersessionKey?: string;
+        operationKey?: string;
+        createdAt?: string;
+        contentHash?: string;
+    }): Promise<string | null>;
+    hasExactTombstone(input: {
+        sourceMemoryId: string;
+        contentHash?: string;
+        entityRef?: string;
+        supersessionKey?: string;
+        createdAt?: string;
+        operationKey?: string;
+    }): Promise<boolean>;
+    /**
+     * Revoke a tombstone (re-allow the content). Used by the review-queue
+     * approval path when an operator approves a blocked memory.
+     */
+    revokeTombstone(tombstoneId: string, createdBy: TombstoneCreatedBy): Promise<string | null>;
+    /** Aggregate tombstone stats for `remnic doctor`. */
+    getTombstoneStats(): Promise<TombstoneStats | null>;
+    /**
+     * Rebuild the tombstone log from retired memories on disk. Exposed for
+     * `remnic doctor --rebuild-tombstones` and tests.
+     */
+    rebuildTombstonesFromFiles(): Promise<number>;
+    protected markFactHashIndexNotAuthoritative(): void;
+    protected tombstoneBlockedCaptureIndexOptions(): TombstoneBlockedCaptureIndexOptions;
+    private getFactHashIndex;
+    /**
+     * Return the fact-hash index after ensuring it is authoritative — i.e. rebuilt
+     * from the durable fact corpus (issue #1909 review round 12). This is the ONE
+     * coherent dedup source: the orchestrator's dedup layer
+     * (contentHashIndexForStorage) shares THIS instance instead of loading a raw,
+     * possibly-stale fact-hashes.txt, so after a crash+restart the orchestrator's
+     * hasContentHashDedup sees the same corpus-rebuilt hashes StorageManager does
+     * and never re-creates a fact whose per-write flush was deferred and lost.
+     */
+    getAuthoritativeFactHashIndex(): Promise<ContentHashIndex>;
+    /**
+     * Return the shared fact-hash index instance, corpus-rebuilt under the lock
+     * when the lock is free. Unlike {@link getAuthoritativeFactHashIndex} this
+     * NEVER throws on lock contention — it returns the shared instance (the loaded
+     * snapshot when a locked rebuild could not run) so registration writes still
+     * land in the one shared index and reconcile to disk. Callers that trust a
+     * dedup MISS MUST also consult {@link isFactContentHashAuthoritative} and
+     * confirm against the corpus when it is false (PR #2016).
+     */
+    getSharedFactHashIndex(): Promise<ContentHashIndex>;
+    private ensureFactHashIndexAuthoritative;
+    /**
+     * Repopulate `factHashIndex` in memory from the durable HOT+COLD corpus. Runs
+     * WHILE the per-index cross-process lock is held (see
+     * ContentHashIndex.rebuildUnderLock, which publishes the rebuilt set); this
+     * method itself never writes to disk.
+     */
+    private rebuildFactHashIndexFromCorpus;
+    private storedContentIdentityCandidates;
+    /** Returns the current body identity while preserving explicit external identities. */
+    private corpusRegisteredHashes;
+    private get questionsDir();
+    private get artifactsDir();
+    private get identityDir();
+    private get identityAnchorPath();
+    private get identityIncidentsDir();
+    private get identityAuditsWeeklyDir();
+    private get identityAuditsMonthlyDir();
+    private get identityImprovementLoopsPath();
+    private get identityReflectionsPath();
+    private get profilePath();
+    private get memoryActionsPath();
+    private get memoryLifecycleLedgerPath();
+    private get compressionGuidelinesPath();
+    private get compressionGuidelineDraftPath();
+    private get compressionGuidelineStatePath();
+    private get compressionGuidelineDraftStatePath();
+    private get behaviorSignalsPath();
+    /**
+     * In-memory dedup key set for behavior-signals appends (issue #1909),
+     * validated by (size, mtime) file identity like the catalog `compactedCache`.
+     * Avoids re-reading + JSON.parsing the whole `behavior-signals.jsonl` on
+     * every append. A foreign write changes size/mtime, forcing a reload; this
+     * process's own appends refresh the identity in place. null => reload.
+     */
+    private behaviorSignalsKeyCache;
+    /**
+     * Per-instance serializer for `appendBehaviorSignals` (issue #1909 review
+     * round 3). The read→dedup→append→cache-commit transaction must run to
+     * completion before the next append starts; otherwise two concurrent callers
+     * each snapshot their own `existingKeys`, and the later one commits an
+     * INCOMPLETE set under the final file identity, so a subsequent call
+     * cache-hits a set missing the earlier batch and writes duplicate signals.
+     * The `.catch` links keep the chain alive after a rejected append
+     * (AGENTS.md #28).
+     */
+    private behaviorSignalsAppendChain;
+    /**
+     * 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();
+    /**
+     * Entity alias table loaded from THIS store's config/aliases.json.
+     * Instance-scoped on purpose (issue #1534): multiple StorageManager
+     * instances in one process (namespaces, hosted profiles, tenants) must
+     * never share alias state — the previous module-level table let whichever
+     * store loaded last rewrite every other store's canonical entity ids.
+     */
+    private userAliases;
+    private readonly historicalEntityCanonicalIds;
+    private currentHistoricalIds;
+    /** Post-persist repair subsystem (issue #2213) — storage/entity-ref-repair.ts. */
+    private _entityRefRepair;
+    private get entityRefRepair();
+    private readonly entityCanonicalIdMigration;
+    normalizeEntityName(raw: string, type: string): string;
+    /**
+     * Read-only view of this store's user alias table, for call sites that
+     * normalize outside the manager (pass it to the free `normalizeEntityName`).
+     */
+    get entityAliases(): Readonly<Record<string, string>>;
+    /**
+     * Reload user-defined entity aliases from config/aliases.json in the memory
+     * store. File format: { "variant": "canonical", ... }. The constructor
+     * already loads aliases, so this is only needed to pick up file changes
+     * (e.g. orchestrator.initialize() re-running on a live instance).
+     * Non-object payloads and non-string or empty alias values are ignored.
+     */
+    loadAliases(): Promise<void>;
+    private loadAliasesSync;
+    private runLegacyEntityCanonicalIdMigration;
+    ensureDirectories(): Promise<void>;
+    /**
+     * Resolve the on-disk write path for a memory of the given category, creating
+     * the target directory. Category routing goes through the shared
+     * `getCategoryDir()` chokepoint (utils/category-dir.ts → CATEGORY_DIR_MAP) so
+     * decision/preference/moment/etc. outputs land in their dedicated dirs
+     * (`decisions/`, `preferences/`, ...) instead of collapsing into `facts/`
+     * (issue #1546; CLAUDE.md rule 39). `correction` keeps its historical flat
+     * layout (no `<date>` subdir) as the corrections pipeline expects; every other
+     * category — including `fact`/`entity`, which fall back to `facts/` — is dated
+     * as `<dir>/<date>/`. Read/scan/reindex already iterate every category dir
+     * (RECALL_FALLBACK_DIRS; QMD scans baseDir recursively), so writes stay found.
+     */
+    private resolveCategoryWritePath;
+    private findExistingTombstoneBlockedMemory;
+    /** Derive the inert OKF `type` at the serialization choke point when conformance is on
+     *  and the parsed frontmatter carried none (issue #1946). Never touches `category`. */
+    private withOkfType;
+    writeMemory(category: MemoryCategory, content: string, options?: WriteMemoryOptions): Promise<{
+        id: string;
+        tombstoneBlocked: boolean;
+        blockedBy: string | undefined;
+        duplicateOf: string;
+        memory: MemoryFile;
+    } | {
+        memory: {
+            path: string;
+            frontmatter: MemoryFrontmatter;
+            content: string;
+        };
+        blockedBy?: string | undefined;
+        id: string;
+        tombstoneBlocked: boolean;
+        duplicateOf?: undefined;
+    }>;
+    /**
+     * Sealed-envelope write entry point (issue #1989 PR2).
+     *
+     * Byte-identity with `writeMemory` is BY DELEGATION: the envelope-owned
+     * fields are unpacked into the exact `writeMemory` arguments a legacy
+     * caller would have passed, so the persisted output is produced by the
+     * same code path. The composer's `persistedBody` was assembled with the
+     * same `assemblePersistedBody` helper `writeMemory` uses, so fingerprints
+     * derived from the envelope match the stored body (§13).
+     *
+     * Differences from a raw `writeMemory` call are REJECTIONS, not silent
+     * changes: the composer enforces tag/attribute caps, strict validAt, and
+     * plain-object attributes that the legacy path never validated.
+     *
+     * `envelope.ttl` maps to `expiresAt` verbatim; converting duration
+     * expressions (`"90d"`) to instants remains the access layer's job (PR3).
+     * `envelope.sourceReason` is access-layer metadata with no frontmatter
+     * field and is deliberately not persisted here.
+     */
+    writeSealedMemory(envelope: SealedMemoryEnvelope, extras?: SealedWriteExtras): Promise<{
+        id: string;
+        tombstoneBlocked: boolean;
+        blockedBy: string | undefined;
+        duplicateOf: string;
+        memory: MemoryFile;
+    } | {
+        memory: {
+            path: string;
+            frontmatter: MemoryFrontmatter;
+            content: string;
+        };
+        blockedBy?: string | undefined;
+        id: string;
+        tombstoneBlocked: boolean;
+        duplicateOf?: undefined;
+    }>;
+    hasFactContentHash(content: string): Promise<boolean>;
+    private factContentHashPresentInCorpus;
+    private factContentHashesForRemoval;
+    /** Publish `hashes` for an ACTIVE fact through the SAME locked reconcile the write path uses. */
+    private publishActiveFactHashes;
+    /**
+     * Register an EXPLICITLY computed content hash for an active fact (issue
+     * #2330 round N+16 C): the degraded merge repair indexes the COMMITTED
+     * body while the persisted `frontmatter.contentHash` is the stale
+     * PRE-merge identity. Round N+20 (B): body-coupled (`expectedContent`) —
+     * repair), so no obsolete hash lands on a newer record. No-op otherwise.
+     */
+    registerFactContentHash(memoryId: string, contentHash: string, expectedContent: string): Promise<void>;
+    private addActiveFactContentHash;
+    /**
+     * Re-register a fact's contentHash in the dedup index after a tombstone
+     * block is lifted on approval (issue #1579 thread ObnTy): `writeMemory`
+     * skips registration for tombstone-blocked facts (rule 44), so a promoted
+     * fact must re-enter the index or the next extraction of the same content
+     * creates a second active fact. No-op for non-facts or inactive facts.
+     */
+    restoreFactHashAfterApproval(memoryId: string): Promise<void>;
+    private syncFactHashIndexAfterRewrite;
+    removeFactContentHashesForMemories(memories: MemoryFile[]): Promise<void>;
+    /**
+     * Remove a memory's fact-ONLY partition membership in lockstep with the
+     * shared, category-agnostic index removal the orchestrator's
+     * `removeContentHashForMemory` performs on archival / semantic
+     * consolidation (PR #2016 threads SDzOP / SDzOR). Without this, the
+     * partition kept a removed/superseded fact's hash and `hasFactContentHash`
+     * returned a stale `true` until the next corpus rebuild, so wearable /
+     * explicit-capture / promotion callers skipped a valid write. No-op when
+     * the fact-hash index has not been loaded in this process yet (the
+     * partition is empty then and the corpus rebuild excludes the removed
+     * memory). No-op for non-facts.
+     */
+    removeFactOnlyHashForMemory(memory: MemoryFile): void;
+    isFactContentHashAuthoritative(): Promise<boolean>;
+    writeArtifact(quote: string, options?: {
+        actor?: string;
+        tags?: string[];
+        confidence?: number;
+        artifactType?: MemoryFrontmatter["artifactType"];
+        sourceMemoryId?: string;
+        sourceTurnId?: string;
+        intentGoal?: string;
+        intentActionType?: string;
+        intentEntityTypes?: string[];
+        sourceConnector?: string;
+        origin?: string;
+        toolScoped?: true;
+    }): Promise<string>;
+    private readAllArtifactsCached;
+    searchArtifacts(query: string, maxResults: number, options?: ArtifactSearchOptions): Promise<MemoryFile[]>;
+    writeEntity(name: string, type: string, facts: string[], options?: {
+        timestamp?: string;
+        source?: string;
+        sessionKey?: string;
+        principal?: string;
+        origin?: string;
+        structuredSections?: EntityStructuredSection[];
+    }): Promise<string>;
+    readProfile(): Promise<string>;
+    writeProfile(content: string): Promise<void>;
+    private static normalizeForDedup;
+    /**
+     * Check if a new bullet is a fuzzy duplicate of any existing bullet.
+     * Returns true if the new bullet should be skipped.
+     */
+    private static isFuzzyDuplicate;
+    appendToProfile(updates: string[]): Promise<void>;
+    /** Check if profile.md exceeds the max line cap and needs LLM consolidation */
+    profileNeedsConsolidation(triggerLines?: number): Promise<boolean>;
+    private rememberMemorySnapshot;
+    private rememberMemorySnapshots;
+    readAllMemories(options?: CorpusReadOptions): Promise<MemoryFile[]>;
+    /** Invalidate the readAllMemories() cache after writes that add/remove memories. */
+    /** Public cache invalidation for callers that need authoritative disk reads
+     *  (e.g. projection verify/rebuild). */
+    invalidateAllMemoriesCacheForDir(): void;
+    /** Invalidate only the cache layers affected by direct tier file deletes. */
+    invalidateMemoryCachesForTiers(tiers: Iterable<"hot" | "cold" | "archive">): void;
+    /** Clear ALL static caches. Use in tests that write files directly
+     *  (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.
+     *
+     *  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.). */
+    protected invalidateAllMemoriesCache(): void;
+    /**
+     * Single-file write/delete fast path for the hot-memories cache (issue
+     * #1902). Keeps THIS process's version-keyed corpus entry warm by patching
+     * the changed memory in place, bumps the dedicated `.memory-corpus-version.log`
+     * sentinel so PEER processes rescan (memory-status is deliberately NOT bumped
+     * here so plain creates/content edits don't invalidate the entity cache), and
+     * evicts only the derived/global layers (which
+     * are cheap to rebuild and are never patched). Mirrors the in-flight-dedup
+     * and tombstone-store invalidation that invalidateAllMemoriesCache() does.
+     *
+     * `added` is the written MemoryFile (writes/overwrites); `removedPath` is a
+     * deleted path. A path outside the active scan roots (under cold/ or
+     * archive/) is NOT applied to the hot map — that cache holds active memories
+     * only — but the version bump and derived/global eviction still run so
+     * coherence is preserved. Bulk/ambiguous mutations keep the wholesale
+     * invalidateAllMemoriesCache() drop instead (issue #1902 Step 5).
+     */
+    private patchHotMemoriesCache;
+    /**
+     * 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.
+     */
+    protected invalidateColdMemoriesCache(): void;
+    /** 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;
+    /**
+     * Public cheap active-memory path scan (issue #2149 corpus watermark). Lists
+     * active memory file paths without parsing frontmatter — safe on a 100k+
+     * corpus, unlike readAllMemories().
+     */
+    collectActiveMemoryPaths(options?: {
+        propagateReadErrors?: boolean;
+    } & CorpusReadOptions): Promise<string[]>;
+    /**
+     * Public cheap cold-tier path scan (issue #2156 finding D corpus census).
+     * Lists demoted-but-reachable memory paths under `cold/` without parsing
+     * frontmatter, so the divergence watermark counts the cold tier too.
+     */
+    collectColdMemoryPaths(options?: {
+        propagateReadErrors?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Combined hot+cold corpus-mutation sentinel (issue #2156). Changes whenever
+     * EITHER tier is written, so a divergence census can bracket its hot/cold scan
+     * and detect a tier migration (write-cold-then-unlink-hot) racing the walkers,
+     * then retry for a consistent snapshot instead of caching a transient
+     * double-count or miss.
+     */
+    getCorpusScanVersion(): string;
+    private readParsedMemoriesFromPaths;
+    private readWindowUpdatedMs;
+    private filterWindowPathsByUpdatedAfter;
+    private orderWindowPaths;
+    private readWindowBoundedBatch;
+    readMemoriesWindow(options?: WindowedMemoryReadOptions): Promise<WindowedMemoryReadResult>;
+    private _readAllMemoriesFromDisk;
+    readAllColdMemories(): Promise<MemoryFile[]>;
+    /**
+     * Read archived memory markdown files under archive/.
+     * Used by long-term recall fallback when hot recall has no hits.
+     */
+    readArchivedMemories(): Promise<MemoryFile[]>;
+    readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
+    private resolveTierRootDir;
+    private resolveMemoryDateDir;
+    private isArtifactMemory;
+    buildTierMemoryPath(memory: MemoryFile, tier: "hot" | "cold"): string;
+    private writeMemoryFileAtomic;
+    moveMemoryToPath(memory: MemoryFile, targetPath: string): Promise<boolean>;
+    migrateMemoryToTier(memory: MemoryFile, targetTier: "hot" | "cold"): Promise<{
+        changed: boolean;
+        targetPath: string;
+    }>;
+    private get archiveDir();
+    /**
+     * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
+     * Updates frontmatter with archived status before moving.
+     * Returns the new file path on success, null on failure.
+     */
+    archiveMemory(memory: MemoryFile, lifecycle?: MemoryLifecycleEventWriteOptions): Promise<string | null>;
+    /** Alias of listEntityNames (kept for legacy callers; sorted). */
+    readEntities(): Promise<string[]>;
+    readEntity(name: string): Promise<string>;
+    listEntityNames(): Promise<string[]>;
+    /**
+     * Find an existing entity that fuzzy-matches the proposed name.
+     * Returns the existing entity filename (without .md) or null if no match.
+     *
+     * Matching priority:
+     * 1. Exact normalized match (handled by normalizeEntityName already)
+     * 2. Dehyphenated match: "jane-doe" vs "janedoe"
+     * 3. Substring containment: "handle-janedoe" contains "janedoe"
+     * 4. Levenshtein ≤ 2 on dehyphenated names
+     */
+    findMatchingEntity(proposedName: string, type: string): Promise<string | null>;
+    invalidateMemory(id: string, expectedSnapshot?: Pick<MemoryFile, "content" | "frontmatter"> & Partial<Pick<MemoryFile, "path">>, options?: {
+        recordCommitProof?: boolean;
+    }): Promise<boolean>;
+    /** Commit the new body and return the CAS commit receipt — the sidecar
+     * revision token, never `frontmatter.updated` (#2813 P1, #2807). */
+    private updateMemoryFromCurrent;
+    updateMemory(id: string, newContent: string, options?: {
+        supersedes?: string;
+        lineage?: string[];
+        actor?: string;
+        sourceConnector?: string;
+    }): Promise<boolean>;
+    /** CAS content update: false when the record moved past `expected`; on
+     * success the commit receipt — the only identity that can attribute a standing body later (#2813 P1, #2807). */
+    updateMemoryIfUnchanged(expected: MemoryFile, newContent: string, options?: {
+        supersedes?: string;
+        lineage?: string[];
+        actor?: string;
+        sourceConnector?: string;
+    }): Promise<string | false>;
+    /**
+     * Update frontmatter fields without changing memory content. Returns false when the memory is not found.
+     */
+    writeMemoryFrontmatter(memory: MemoryFile, patch: Partial<MemoryFrontmatter>, lifecycle?: MemoryLifecycleEventWriteOptions): Promise<boolean>;
+    /**
+     * Update frontmatter only when the persisted memory still matches the
+     * expected semantic snapshot.
+     */
+    writeMemoryFrontmatterIfUnchanged(expected: MemoryFile, patch: Partial<MemoryFrontmatter>, lifecycle?: MemoryLifecycleEventWriteOptions): Promise<boolean>;
+    /**
+     * Update frontmatter by memory ID.
+     * Prefer writeMemoryFrontmatter(memory, patch) in batch loops to avoid full-corpus rescans.
+     */
+    updateMemoryFrontmatter(id: string, patch: Partial<MemoryFrontmatter>): Promise<boolean>;
+    /** Remove memories past their TTL expiresAt date */
+    cleanExpiredTTL(): Promise<MemoryFile[]>;
+    loadBuffer(): Promise<BufferState>;
+    saveBuffer(state: BufferState): Promise<void>;
+    loadMeta(): Promise<MetaState>;
+    saveMeta(state: MetaState): Promise<void>;
+    appendMemoryActionEvents(events: MemoryActionEvent[]): Promise<number>;
+    appendContextTransformRecords(records: ContextTransformTelemetryRecord[]): Promise<number>;
+    readContextTransformRecords(limit?: number): Promise<ContextTransformTelemetryRecord[]>;
+    appendMemoryLifecycleEvents(events: MemoryLifecycleEvent[]): Promise<number>;
+    /** Drain the durable pending lifecycle-append spill into the ledger (#2033);
+     *  fast no-op when nothing is pending. Returns true when rows were drained. */
+    drainPendingMemoryLifecycleEvents(): Promise<boolean>;
+    /** Offline-sync pre-snapshot drain (#2033): fold pending lifecycle spills into
+     *  the active ledger and report whether durable rows STILL remain in the
+     *  offline-sync-EXCLUDED pending queue. The caller aborts the snapshot when
+     *  `pendingDeferred` is true so append-only rows are never silently omitted. */
+    drainPendingMemoryLifecycleEventsForSync(): Promise<DrainPendingLifecycleForSyncResult>;
+    /** Drain pending lifecycle spills for any ledger inside this storage root.
+     * The offline CLI uses this path-aware variant for per-namespace ledgers so
+     * secure-store encryption and path-bound authentication remain consistent. */
+    drainPendingMemoryLifecycleEventsForSyncAt(ledgerPath: string): Promise<DrainPendingLifecycleForSyncResult>;
+    /** Rewrite the ledger through the secure writer (#1910); re-encrypts when unlocked, throws when locked.
+     *  `targetPath` re-encrypts under a decryptable backup path's own AAD;
+     *  Buffer content passes through verbatim (#2033). `forceEncrypt` preserves
+     *  encryption at rest for an already-encrypted ledger/backup even when the
+     *  `secureStoreEncryptOnWrite` policy is paused, so a compaction never
+     *  downgrades encrypted state to plaintext (#2033); it never bypasses the lock. */
+    writeMemoryLifecycleLedgerContent(content: string | Buffer, targetPath?: string, forceEncrypt?: boolean): Promise<void>;
+    appendBufferSurpriseEvents(events: BufferSurpriseEvent[]): Promise<number>;
+    readBufferSurpriseEvents(options?: {
+        limit?: number;
+    }): Promise<BufferSurpriseEvent[]>;
+    appendBehaviorSignals(events: BehaviorSignalEvent[]): Promise<number>;
+    private appendBehaviorSignalsUnlocked;
+    appendReextractJobs(events: ReextractJobRequest[]): Promise<number>;
+    readReextractJobs(limit?: number): Promise<ReextractJobRequest[]>;
+    readBehaviorSignals(limit?: number): Promise<BehaviorSignalEvent[]>;
+    readMemoryActionEvents(limit?: number): Promise<MemoryActionEvent[]>;
+    readMemoryActionEventRows(limit?: number): Promise<Array<{
+        line: number;
+        event: MemoryActionEvent;
+    }>>;
+    readAllMemoryLifecycleEvents(): Promise<MemoryLifecycleEvent[]>;
+    /** Raw decrypted ledger bytes as a Buffer, never a string, so an oversized
+     *  ledger cannot throw on decode before recovery (#2033). */
+    readMemoryLifecycleLedgerRawBufferForCompaction(): Promise<Buffer>;
+    readAllMemoryLifecycleEventsForCompaction(): Promise<MemoryLifecycleEvent[]>;
+    readMemoryLifecycleEvents(limit?: number): Promise<MemoryLifecycleEvent[]>;
+    writeCompressionGuidelines(content: string): Promise<void>;
+    readCompressionGuidelines(): Promise<string | null>;
+    writeCompressionGuidelineDraft(content: string): Promise<void>;
+    readCompressionGuidelineDraft(): Promise<string | null>;
+    writeCompressionGuidelineOptimizerState(state: CompressionGuidelineOptimizerState): Promise<void>;
+    writeCompressionGuidelineDraftState(state: CompressionGuidelineOptimizerState): Promise<void>;
+    readCompressionGuidelineOptimizerState(): Promise<CompressionGuidelineOptimizerState | null>;
+    readCompressionGuidelineDraftState(): Promise<CompressionGuidelineOptimizerState | null>;
+    activateCompressionGuidelineDraft(options?: {
+        expectedContentHash?: string;
+        expectedGuidelineVersion?: number;
+    }): Promise<boolean>;
+    private readCompressionGuidelineStateFile;
+    writeIdentityAnchor(content: string): Promise<void>;
+    readIdentityAnchor(): Promise<string | null>;
+    appendContinuityIncident(input: ContinuityIncidentOpenInput): Promise<ContinuityIncidentRecord>;
+    readContinuityIncidents(limit?: number, state?: "open" | "closed" | "all"): Promise<ContinuityIncidentRecord[]>;
+    closeContinuityIncident(id: string, closure: ContinuityIncidentCloseInput): Promise<ContinuityIncidentRecord | null>;
+    writeIdentityAudit(period: "weekly" | "monthly", key: string, content: string): Promise<string>;
+    readIdentityAudit(period: "weekly" | "monthly", key: string): Promise<string | null>;
+    writeIdentityImprovementLoops(content: string): Promise<void>;
+    readIdentityImprovementLoops(): Promise<string | null>;
+    readIdentityImprovementLoopRegister(): Promise<ContinuityImprovementLoop[]>;
+    upsertIdentityImprovementLoop(input: ContinuityLoopUpsertInput): Promise<ContinuityImprovementLoop>;
+    reviewIdentityImprovementLoop(id: string, input: ContinuityLoopReviewInput): Promise<ContinuityImprovementLoop | null>;
+    private generateId;
+    writeQuestion(question: string, context: string, priority: number): Promise<string>;
+    readQuestions(opts?: {
+        unresolvedOnly?: boolean;
+    }): Promise<Array<{
+        id: string;
+        question: string;
+        context: string;
+        priority: number;
+        resolved: boolean;
+        created: string;
+        filePath: string;
+    }>>;
+    /** Invalidate the questions cache (call after writing a question). */
+    invalidateQuestionsCache(): void;
+    private parseQuestionFile;
+    resolveQuestion(id: string): Promise<boolean>;
+    readIdentity(workspaceDir: string, namespace?: string): Promise<string>;
+    writeIdentity(workspaceDir: string, content: string, namespace?: string): Promise<void>;
+    /** Max size for IDENTITY.md before we stop appending reflections (15KB leaves room under 20KB gateway limit) */
+    private static readonly IDENTITY_MAX_BYTES;
+    /** Minimum interval between reflections (1 hour) */
+    private static readonly REFLECTION_COOLDOWN_MS;
+    appendToIdentity(workspaceDir: string, reflection: string, opts?: {
+        hygiene?: FileHygieneConfig;
+        namespace?: string;
+    }): Promise<void>;
+    readIdentityReflections(): Promise<string | null>;
+    writeIdentityReflections(content: string): Promise<void>;
+    appendIdentityReflection(reflection: string): Promise<void>;
+    addEntityRelationship(name: string, rel: EntityRelationship): Promise<void>;
+    addEntityActivity(name: string, entry: EntityActivityEntry, maxEntries: number): Promise<void>;
+    addEntityAlias(name: string, alias: string): Promise<void>;
+    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;
+    }>;
+    readAllEntityFiles(options?: CorpusReadOptions): Promise<EntityFile[]>;
+    /**
+     * Score an entity based on recency, frequency, activity, type priority,
+     * and relationship density.
+     *
+     * score = recency*0.40 + frequency*0.25 + activity*0.15 + typePriority*0.10 + relationshipDensity*0.10
+     */
+    static scoreEntity(entity: EntityFile, now: Date): number;
+    buildKnowledgeIndex(config: PluginConfig, overrides?: {
+        maxEntities?: number;
+        maxChars?: number;
+    }): Promise<{
+        result: string;
+        cached: boolean;
+    }>;
+    /** Invalidate the Knowledge Index cache (call after entity mutations). */
+    invalidateKnowledgeIndexCache(): void;
+    /** Max lines for profile.md before LLM consolidation triggers */
+    private static readonly PROFILE_MAX_LINES;
+    mergeFragmentedEntities(): Promise<number>;
+    cleanExpiredCommitments(decayDays: number): Promise<MemoryFile[]>;
+    /**
+     * Flush batched access tracking updates to disk.
+     * Called during consolidation or when buffer exceeds max size.
+     */
+    flushAccessTracking(entries: AccessTrackingEntry[]): Promise<number>;
+    getMemoryById(id: string): Promise<MemoryFile | null>;
+    getMemoryByIdIncludingArchived(id: string): Promise<MemoryFile | null>;
+    /** Resolve existing active memory IDs through a lightweight directory scan. */
+    findExistingMemoryPaths(ids: string[], preferredPaths?: Map<string, string[]>): Promise<Map<string, string[]>>;
+    /**
+     * Check which of the given memory IDs actually exist on disk.
+     */
+    filterExistingMemoryIds(ids: string[]): Promise<Set<string>>;
+    getProjectedMemoryState(id: string): Promise<MemoryProjectionCurrentState | null>;
+    browseProjectedMemories(options: ProjectedMemoryBrowseOptions): Promise<ProjectedMemoryBrowsePage | null>;
+    getProjectedGovernanceRecord(): Promise<ReturnType<typeof readProjectedGovernanceRecord>>;
+    private toProjectedCurrentState;
+    getMemoryTimeline(memoryId: string, limit?: number): Promise<MemoryLifecycleEvent[]>;
+    /**
+     * Write a memory chunk with parent reference.
+     * Chunk IDs follow format: {parentId}-chunk-{index}
+     */
+    writeChunk(parentId: string, chunkIndex: number, chunkTotal: number, category: MemoryCategory, content: string, options?: {
+        confidence?: number;
+        tags?: string[];
+        entityRef?: string;
+        source?: string;
+        importance?: ImportanceScore;
+        intentGoal?: string;
+        intentActionType?: string;
+        intentEntityTypes?: string[];
+        memoryKind?: MemoryFrontmatter["memoryKind"];
+        validAt?: string;
+        /** Lifecycle status (issue #1576): pending_review chunks stay out of active recall. */
+        status?: import("./types.js").MemoryStatus;
+        /**
+         * Tombstone block provenance (issue #1645): when the parent fact was
+         * tombstone-blocked, propagate the tombstone id onto each chunk so an
+         * independently-surfaced chunk (memory_get/x-ray/doctor) reveals the block
+         * and the chunk stays pending_review, never an active resurrection.
+         */
+        blockedBy?: string;
+        /** Faithfulness gate verdict (issue #1576), propagated from the parent fact. */
+        faithfulness?: import("./types.js").FaithfulnessFrontmatter;
+        /** Claim-level provenance spans (issue #1575 PR 2), propagated from the parent fact so a chunk surfaced independently (memory_get/x-ray) preserves them (chatgpt-codex-connector thread Ocvmo). */
+        sources?: ProvenanceSource[];
+        /** Coarse provenance tag (issue #1575 PR 2), propagated from the parent. */
+        provenance?: "verified" | "unverified" | "none";
+        invalidAt?: string;
+        observedAt?: string;
+        eventTimeSource?: "extracted" | "assumed";
+        sourceConnector?: string;
+        origin?: string;
+        toolScoped?: true;
+    }): Promise<string>;
+    /**
+     * Get all chunks for a given parent memory ID.
+     * Returns chunks sorted by chunkIndex.
+     */
+    getChunksForParent(parentId: string): Promise<MemoryFile[]>;
+    supersedeMemory(oldMemoryId: string, newMemoryId: string, reason: string, supersessionMetadata?: Pick<MemoryFrontmatter, "supersessionCause" | "invalidatedBy">, options?: {
+        actor?: string;
+        requireActive?: boolean;
+        acceptExactReplay?: boolean;
+        expectedSnapshot?: Pick<MemoryFile, "content" | "frontmatter"> & Partial<Pick<MemoryFile, "path">>;
+        audit?: SupersessionAuditOptions;
+    }): Promise<boolean>;
+    private get summariesDir();
+    writeSummary(summary: MemorySummary): Promise<void>;
+    readSummaries(): Promise<MemorySummary[]>;
+    archiveMemories(memoryIds: string[], summaryId: string): Promise<number>;
+    saveTopics(topics: TopicScore[]): Promise<void>;
+    loadTopics(): Promise<{
+        topics: TopicScore[];
+        updatedAt: string | null;
+    }>;
+    addLinksToMemory(memoryId: string, links: MemoryLink[], lifecycle?: MemoryLifecycleEventWriteOptions): Promise<boolean>;
+    private summarizeLifecycleState;
+    private frontmatterPatchEventType;
+    private appendGeneratedMemoryLifecycleEvent;
+    private appendGeneratedMemoryLifecycleEventFailOpen;
+}
+//# sourceMappingURL=storage.d.ts.map