@remnic/core 9.7.14 → 9.8.0

package/dist/{storage-CrvzaM9C.d.ts → storage-NIyKYD8g.d.ts}

@@ -1,8 +1,21 @@
-import { M as MemoryFile, P as PluginConfig, v as MemoryStatus, u as MemoryCategory, ak as ImportanceScore, ax as MemoryLink, p as MemoryFrontmatter, F as FaithfulnessFrontmatter, N as ProvenanceSource, ad as EntityStructuredSection, ay as BufferState, az as MetaState, a8 as MemoryActionEvent, x as MemoryLifecycleEvent, Z as BufferSurpriseEvent, B as BehaviorSignalEvent, a9 as CompressionGuidelineOptimizerState, ag as ContinuityIncidentOpenInput, ae as ContinuityIncidentRecord, af as ContinuityIncidentCloseInput, ah as ContinuityImprovementLoop, aj as ContinuityLoopUpsertInput, ai as ContinuityLoopReviewInput, aA as FileHygieneConfig, aB as EntityRelationship, aC as EntityActivityEntry, E as EntityFile, aD as AccessTrackingEntry, w as MemoryProjectionCurrentState, aE as MemorySummary, av as TopicScore, aF as EntityTimelineEntry } from './types-Bl4BWDM8.js';
+import { au as EntityTimelineEntry, ag as EntityStructuredSection, E as EntityFile, M as MemoryFile, P as PluginConfig, x as MemoryStatus, w as MemoryCategory, ah as ImportanceScore, av as MemoryLink, o as MemoryFrontmatter, F as FaithfulnessFrontmatter, U as ProvenanceSource, aw as BufferState, ax as MetaState, ab as MemoryActionEvent, z as MemoryLifecycleEvent, a0 as BufferSurpriseEvent, $ as BehaviorSignalEvent, ac as CompressionGuidelineOptimizerState, ay as FileHygieneConfig, az as EntityRelationship, aA as EntityActivityEntry, aB as AccessTrackingEntry, y as MemoryProjectionCurrentState, aC as MemorySummary, as as TopicScore } from './types-D_fG2ix8.js';
 import { VersioningConfig } from './page-versioning.js';
 import { ConsolidationOperator } from './consolidation-operator.js';
 import { ProjectedMemoryBrowseOptions, ProjectedMemoryBrowsePage, readProjectedGovernanceRecord } from './memory-projection-store.js';
+import { SealedMemoryEnvelope } from './write-envelope.js';
 import './structured-attributes.js';
+import { ContinuityIncidentOpenInput, ContinuityIncidentRecord, ContinuityIncidentCloseInput, ContinuityImprovementLoop, ContinuityLoopUpsertInput, ContinuityLoopReviewInput } from './types-continuity.js';
+
+/** Result of a pre-snapshot lifecycle drain (#2033): `folded` is true when spill
+ *  rows were committed to the active ledger; `pendingDeferred` is true when
+ *  durable spill rows STILL remain in the offline-sync-EXCLUDED pending queue
+ *  after the attempt (the ledger lock was held by a peer, or a spill could not
+ *  be claimed). A caller MUST NOT report a clean snapshot while `pendingDeferred`
+ *  is true — those append-only rows would be silently omitted. */
+interface DrainPendingLifecycleForSyncResult {
+    folded: boolean;
+    pendingDeferred: boolean;
+}
 
 /**
  * Wearable cross-source fusion — shared types (issue #1810).
@@ -623,38 +636,32 @@ interface RetiredMemoryRecord {
     contentHash?: string;
 }
 
-interface ReextractJobRequest {
-    memoryId: string;
-    model: string;
-    requestedAt: string;
-    source: "cli-migrate";
-}
-interface MemoryLifecycleEventWriteOptions {
-    at?: Date;
-    actor?: string;
-    reasonCode?: string;
-    ruleVersion?: string;
-    relatedMemoryIds?: string[];
-    correlationId?: string;
+/**
+ * Tuning for {@link ContentHashIndex} cross-process lock waits and the
+ * deferred reconcile-save durable retry (issue #1909 / PR #2016). All optional;
+ * production uses the module defaults. Tests inject small values so the
+ * lock-timeout + retry path is exercised deterministically without real
+ * multi-second waits.
+ */
+interface ContentHashIndexLockOptions {
+    /** Bounded wait to acquire the per-file advisory lock; passed to `withHeldFileLock` (default 5000ms). */
+    readonly maxWaitMs?: number;
+    /** Poll interval while waiting for a busy lock (default 50ms). */
+    readonly pollMs?: number;
+    /** Base backoff before the first deferred-save retry (default 500ms). */
+    readonly retryBaseMs?: number;
+    /** Max deferred-save retries before falling back to the corpus-rebuild safety net (default 5). */
+    readonly retryMaxAttempts?: number;
 }
-declare function parseFrontmatterStringValue(rawValue: string | undefined): string | undefined;
-declare function parseFrontmatter(raw: string): {
-    frontmatter: MemoryFrontmatter;
-    content: string;
-} | null;
-declare function normalizeFrontmatterForPath(frontmatter: MemoryFrontmatter, pathRel: string, content?: string): MemoryFrontmatter;
 /**
- * Normalize an entity name to a canonical form.
- * Strips non-alphanumeric chars, collapses hyphens, removes type prefix duplication.
- * e.g. "My Project" → "my-project"
- *
- * Checks caller-provided user aliases first, then built-in aliases. Alias
- * tables are instance state on StorageManager (issue #1534) — use
- * `storageManager.normalizeEntityName(raw, type)` when normalizing within a
- * store, or pass `storageManager.entityAliases` explicitly. Without an
- * aliases argument only the built-in structural aliases apply.
+ * Thrown when the fact-hash index cannot be made authoritative — the
+ * cross-process rebuild lock could not be acquired within the bounded retry
+ * budget (PR #2016). Callers that require an authoritative dedup answer surface
+ * this instead of silently trusting a stale loaded snapshot.
  */
-declare function normalizeEntityName(raw: string, type: string, aliases?: Readonly<Record<string, string>>): string;
+declare class FactHashIndexNotAuthoritativeError extends Error {
+    constructor(stateDir: string);
+}
 /**
  * Content-hash dedup index for facts.
  * Normalizes content (lowercase, strip punctuation, collapse whitespace),
@@ -664,13 +671,66 @@ declare function normalizeEntityName(raw: string, type: string, aliases?: Readon
 declare class ContentHashIndex {
     private hashes;
     private dirty;
+    /**
+     * Hashes explicitly removed since the last successful save (issue #1909 review
+     * round 8 thread 3). Tracked separately so `saveMergingWithDisk` can be
+     * removal-AWARE: under the file lock it reads the latest on-disk set, DROPS
+     * these, then unions our additions — so a removal batch cannot resurrect a
+     * hash (union alone would) and cannot clobber a concurrent extraction's
+     * appended hash (blind overwrite would). Consumed + cleared by every save.
+     */
+    private removed;
+    /**
+     * Hashes added by THIS instance since the last successful save (issue #1909
+     * review round 9 finding 3). Tracked separately from the loaded snapshot so a
+     * reconciling save publishes `(on-disk \ removed) ∪ added` — it re-applies only
+     * OUR additions, never the stale loaded entries. Without this, seeding the
+     * merge from `this.hashes` (loaded ∪ added) would resurrect a hash a peer
+     * removed on disk while this instance held a stale snapshot.
+     */
+    private added;
     private readonly filePath;
     private readonly secureStoreKeyProvider;
     private readonly secureStoreWriteKeyProvider;
     private readonly memoryDir;
-    constructor(stateDir: string, secureStoreKeyProvider?: () => Buffer | null, secureStoreWriteKeyProvider?: () => Buffer | null, memoryDir?: string);
+    private readonly lockOptions;
+    /**
+     * Deferred reconcile-save durable-retry state (issue #1909 / PR #2016). At
+     * most ONE retry is ever armed (`reconcileRetryTimer` is the reentrancy guard)
+     * so successive timed-out saves cannot stack duplicate/parallel retries.
+     * `reconcileRetryBarrier` resolves when the chain settles (published or gave
+     * up) — awaited by tests and any caller wanting the eventual result.
+     */
+    private reconcileRetryTimer;
+    private reconcileRetryAttempts;
+    private reconcileRetryBarrier;
+    private reconcileRetryResolve;
+    /**
+     * On-disk fingerprint (mtime + byte size) of `fact-hashes.txt` captured at the
+     * last point THIS instance's in-memory set matched disk — after `load()`,
+     * `save()`, or a reconcile publish (PR #2016 review). A peer process that
+     * advances the durable index changes this fingerprint;
+     * {@link isDiskFingerprintCurrent} compares a single cheap `stat` against it so
+     * a stale-but-"authoritative" snapshot is detected without an O(file-size)
+     * re-read on the hot path.
+     */
+    private lastSyncedFingerprint;
+    constructor(stateDir: string, secureStoreKeyProvider?: () => Buffer | null, secureStoreWriteKeyProvider?: () => Buffer | null, memoryDir?: string, lockOptions?: ContentHashIndexLockOptions);
     /** Load existing hashes from disk. Safe to call multiple times. */
     load(): Promise<void>;
+    /** Cheap `stat` of the durable index file; null when it does not exist yet. */
+    private statIndexFile;
+    /** Record the current on-disk fingerprint as this instance's synced baseline. */
+    private captureSyncedFingerprint;
+    /**
+     * True when the durable index file is unchanged since this instance last
+     * synced it (load / save / reconcile). False when a peer advanced it, when the
+     * file appeared or vanished, or when freshness cannot be established (stat
+     * error) — the caller then treats the in-memory snapshot as non-authoritative
+     * and confirms a dedup miss against the durable corpus (PR #2016 review). One
+     * `stat`, never an O(file-size) read, so the hot path stays cheap.
+     */
+    isDiskFingerprintCurrent(): Promise<boolean>;
     /** Check if content already exists in the index. */
     has(content: string): boolean;
     /** Add content hash to the index. */
@@ -678,8 +738,99 @@ declare class ContentHashIndex {
     get size(): number;
     /** Clear all loaded hashes so the next save rewrites the index from scratch. */
     clear(): void;
-    /** Persist index to disk if changed. */
+    /** Persist index to disk if changed (plain whole-file overwrite). */
     save(): Promise<void>;
+    /**
+     * Persist the index by RECONCILING with the latest on-disk state under a
+     * cross-process lock (issue #1909). Used by the extraction-persist batch save
+     * for BOTH append and removal batches, so appends and removals to the same
+     * index serialize against each other:
+     *   final = (on-disk \ this.removed) ∪ this.added
+     * Note it re-applies only OUR local additions (`added`), NOT the loaded
+     * snapshot (review round 9 finding 3): seeding from `this.hashes` would
+     * resurrect a hash a peer removed on disk while we held a stale snapshot. This
+     * preserves a concurrent writer's appended hashes (a blind overwrite would
+     * drop them), never resurrects a removed hash, and never loses our additions.
+     *
+     * Hardening:
+     *  - Dirty short-circuit (round 7 finding 3): when this instance neither added
+     *    nor removed anything this run, skip the O(file) read+rewrite entirely.
+     *  - Cross-process lock (round 7 finding 2): serialize the read→reconcile→write
+     *    window on a per-file advisory lock. If the lock is NOT acquired (timeout),
+     *    do NOT publish (round 9 finding 2): keep `dirty` set AND schedule a bounded
+     *    durable background retry (PR #2016) that keeps re-attempting the locked
+     *    publish until the deferred additions land — never an unlocked write that
+     *    could clobber a peer, and never a silent "batch save complete" that leaves
+     *    the addition in this process's memory only.
+     */
+    saveMergingWithDisk(): Promise<void>;
+    /**
+     * Rebuild-and-publish the index from an authoritative source (the durable
+     * corpus) under the SAME per-file cross-process lock the reconciling
+     * append/removal saves (`saveMergingWithDisk`) use (issue #1909 / PR #2016).
+     * The `populate` callback runs WHILE the lock is held and MUST repopulate this
+     * index from the corpus (`clear()` then `addByHash(...)` for every corpus
+     * hash); the rebuilt set is then published with a plain overwrite that is now
+     * serialized against every locked writer.
+     *
+     * This closes the finding where the previous unlocked clear→scan→save() could
+     * overwrite a peer's newer lock-merged or deferred additions: a locked writer
+     * that committed BEFORE the rebuild acquired the lock has its memory `.md` on
+     * disk and is re-scanned; one that commits AFTER the rebuild releases
+     * reconciles its additions on top of the freshly-published set. No union with
+     * the raw on-disk file is performed, so the rebuild keeps its
+     * garbage-collection property (orphaned hashes for deleted memories drop).
+     *
+     * Lock-acquisition failure is explicit and non-destructive: `populate` is NOT
+     * run and nothing is written (never an unlocked overwrite). Returns true when
+     * the rebuild was published under the lock, false when the lock timed out —
+     * the caller keeps the index non-authoritative and retries on next use. Uses
+     * the same non-reentrant file lock as the reconcile path, so it can never
+     * deadlock with the deferred reconcile-retry: a concurrent locked writer (or a
+     * fired retry) simply yields `acquired=false` after the bounded wait.
+     */
+    rebuildUnderLock(populate: () => Promise<void>): Promise<boolean>;
+    /**
+     * True while a background durable reconcile-save retry is armed (PR #2016).
+     * Test/introspection hook.
+     */
+    get hasPendingReconcileRetry(): boolean;
+    /**
+     * Resolve once any armed background reconcile-save retry chain has settled —
+     * either it published the deferred additions, or it exhausted its bounded
+     * attempts and fell back to the corpus-rebuild safety net. Resolves
+     * immediately when nothing is armed. Lets a caller (or a test) await the
+     * eventual durability outcome of a lock-timed-out save.
+     */
+    whenReconcileRetrySettled(): Promise<void>;
+    /**
+     * Drive any deferred lock-timeout reconcile save to completion INLINE at a
+     * lifecycle boundary (PR #2016 finding 3). The background retry timer is
+     * `unref`'d so it never keeps a long-lived daemon alive — but a short-lived
+     * writer (a one-shot CLI) can exit before it fires, leaving a durable fact
+     * `.md` whose hash never reached `fact-hashes.txt` for peers that already
+     * built their in-memory index. `orchestrator.destroy()` calls this so the
+     * addition publishes before the process exits; long-lived hosts only reach it
+     * at their own shutdown, so their in-flight retries keep running in the
+     * background until then. Bounded by the same attempt ceiling as the background
+     * retry; a permanently contended lock falls back to the corpus-rebuild-on-
+     * restart safety net (the fact `.md` is already durable). No deadlock: each
+     * attempt is the same non-reentrant, bounded-wait file lock.
+     */
+    flushReconcileRetry(): Promise<void>;
+    /**
+     * Schedule ONE bounded, exponentially-backed-off background retry of the
+     * deferred reconcile save (PR #2016). Reentrant-safe: an already-armed timer
+     * short-circuits, so successive timed-out saves never stack duplicate retries.
+     * When attempts are exhausted the chain settles without publishing — the
+     * durable fact `.md` is on disk and a process restart rebuilds the index from
+     * the corpus, so this degrades to that safety net, never a fatal failure.
+     */
+    private scheduleReconcileRetry;
+    /** Cancel any armed reconcile-save retry and settle the barrier (a publish landed). */
+    private cancelReconcileRetry;
+    /** Resolve and clear the retry barrier if one is outstanding. */
+    private settleReconcileRetry;
     /** Remove a hash from the index (used when archiving/deleting). */
     remove(content: string): void;
     /**
@@ -706,13 +857,46 @@ declare class ContentHashIndex {
     static computeHash(content: string): string;
 }
 
-declare function normalizeAttributePairs(pairs: Record<string, string>): string;
 declare function normalizeStructuredSectionFacts(facts: string[]): string[];
 declare function compileEntityFacts(timeline: EntityTimelineEntry[], structuredSections: EntityStructuredSection[]): string[];
 declare function compareEntityTimestamps(left?: string, right?: string): number;
 declare function countEntityStructuredFacts(entity: EntityFile): number;
 declare function fingerprintEntityStructuredFacts(entity: Pick<EntityFile, "structuredSections">): string | undefined;
 declare function isEntitySynthesisStale(entity: EntityFile): boolean;
+
+interface ReextractJobRequest {
+    memoryId: string;
+    model: string;
+    requestedAt: string;
+    source: "cli-migrate";
+}
+interface MemoryLifecycleEventWriteOptions {
+    at?: Date;
+    actor?: string;
+    reasonCode?: string;
+    ruleVersion?: string;
+    relatedMemoryIds?: string[];
+    correlationId?: string;
+}
+declare function parseFrontmatterStringValue(rawValue: string | undefined): string | undefined;
+declare function parseFrontmatter(raw: string): {
+    frontmatter: MemoryFrontmatter;
+    content: string;
+} | null;
+declare function normalizeFrontmatterForPath(frontmatter: MemoryFrontmatter, pathRel: string, content?: string): MemoryFrontmatter;
+/**
+ * Normalize an entity name to a canonical form.
+ * Strips non-alphanumeric chars, collapses hyphens, removes type prefix duplication.
+ * e.g. "My Project" → "my-project"
+ *
+ * Checks caller-provided user aliases first, then built-in aliases. Alias
+ * tables are instance state on StorageManager (issue #1534) — use
+ * `storageManager.normalizeEntityName(raw, type)` when normalizing within a
+ * store, or pass `storageManager.entityAliases` explicitly. Without an
+ * aliases argument only the built-in structural aliases apply.
+ */
+declare function normalizeEntityName(raw: string, type: string, aliases?: Readonly<Record<string, string>>): string;
+
 /**
  * Parse an entity markdown file into a structured EntityFile.
  * Backward compatible: old files without new sections get empty arrays.
@@ -751,6 +935,89 @@ interface MemoryWriteResult {
     /** The tombstone id that blocked the write, when `tombstoneBlocked`. */
     blockedBy?: 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).
+ */
+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?: 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";
+    sourceConnector?: string;
+}
+/**
+ * `WriteMemoryOptions` minus the fields a `SealedMemoryEnvelope` owns.
+ * Passing an envelope-owned field twice is a compile error by construction.
+ */
+type SealedWriteExtras = Omit<WriteMemoryOptions, "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector">;
 declare class StorageManager {
     private readonly baseDir;
     private readonly entitySchemas?;
@@ -812,6 +1079,16 @@ declare class StorageManager {
      * 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). */
@@ -840,7 +1117,35 @@ declare class StorageManager {
     private factHashIndexLoadPromise;
     private factHashIndexAuthoritative;
     private factHashIndexAuthoritativePromise;
+    /**
+     * Fact-ONLY hash membership (PR #2016). The shared `factHashIndex` above is
+     * category-agnostic (the round-15 corpus rebuild + addContentHashDedup index
+     * every category), so it cannot answer a fact-only question. This set 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. Kept in lockstep with the shared index on EVERY path:
+     * the authoritative corpus rebuild (repopulated in place), the write path
+     * (`writeMemory` / `addActiveFactContentHash`), the storage-owned removal
+     * (`removeFactContentHashesForMemories`), AND the orchestrator's archival /
+     * consolidation removal (`removeContentHashForMemory` ->
+     * `removeFactOnlyHashForMemory`). In-memory only; never persisted.
+     */
+    private factOnlyHashes;
+    /** 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;
@@ -849,6 +1154,9 @@ declare class StorageManager {
     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).
@@ -946,17 +1254,22 @@ declare class StorageManager {
     setSecureStoreRequired(required: boolean): void;
     /** Return true iff the secure-store key is currently set (store is unlocked). */
     isSecureStoreUnlocked(): boolean;
-    /**
-     * Resolve the effective write key.
+    /** 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.
      *
-     * - If `_secureStoreEncryptOnWrite` is false: returns null (plain write).
-     * - If `_secureStoreEncryptOnWrite` is true AND key is set: returns key.
-     * - If `_secureStoreEncryptOnWrite` is true AND key is null AND
-     *   `_secureStoreRequired` is true: throws SecureStoreLockedError so the
-     *   write fails loudly rather than silently writing plaintext (P1 finding
-     *   from Cursor review of PR #767).
-     * - If `_secureStoreEncryptOnWrite` is true AND key is null AND
-     *   `_secureStoreRequired` is false: returns null (unencrypted store).
+     * `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;
     /**
@@ -995,6 +1308,12 @@ declare class StorageManager {
      *  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;
     /**
      * The LIVE class object of this instance (issue #1809 review of the
      * storage decomposition): extracted store modules must read/write the
@@ -1119,11 +1438,21 @@ declare class StorageManager {
     private invalidateAfterOfflineSyncMutation;
     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();
-    private get factHashIndexReadyPath();
     /**
      * 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
@@ -1192,7 +1521,54 @@ declare class StorageManager {
      */
     rebuildTombstonesFromFiles(): Promise<number>;
     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;
+    /**
+     * The content-hash the corpus rebuild registers for `memory`, or null when the
+     * body carries a citation from an unknown/custom template that cannot be
+     * safely stripped. Shared by the authoritative rebuild and the fact-only
+     * corpus confirmation (`hasFactContentHash`) so both derive the identical
+     * hash for a given stored body.
+     *
+     * Preference order:
+     *  1. frontmatter.contentHash — the raw pre-citation hash writeMemory records
+     *     for facts (issue #369 round 8); matches hasFactContentHash(rawFact).
+     *  2. Reconstruct from the stored body: strip the "[Attributes: …]" suffix
+     *     writeMemory appends for structuredAttributes (registration hashed the
+     *     raw canonical content WITHOUT it — a no-op when absent), then strip a
+     *     recognised citation and hash the bare body, or hash a citation-free
+     *     body as-is.
+     *  3. A body with a citation from an unknown/custom template → null: a
+     *     false-negative miss beats a wrong hash that would permanently suppress
+     *     legitimate duplicate writes.
+     */
+    private corpusRegisteredHash;
     private get questionsDir();
     private get artifactsDir();
     private get identityDir();
@@ -1210,6 +1586,25 @@ declare class StorageManager {
     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).
      *
@@ -1258,68 +1653,29 @@ declare class StorageManager {
      * (RECALL_FALLBACK_DIRS; QMD scans baseDir recursively), so writes stay found.
      */
     private resolveCategoryWritePath;
-    writeMemory(category: MemoryCategory, content: string, options?: {
-        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;
-        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?: 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";
-        sourceConnector?: string;
-    }): Promise<MemoryWriteResult>;
+    writeMemory(category: MemoryCategory, content: string, options?: WriteMemoryOptions): Promise<MemoryWriteResult>;
+    /**
+     * 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<MemoryWriteResult>;
     hasFactContentHash(content: string): Promise<boolean>;
+    private factContentHashPresentInCorpus;
     private factContentHashForRemoval;
     private addActiveFactContentHash;
     /**
@@ -1335,6 +1691,19 @@ declare class StorageManager {
     restoreFactHashAfterApproval(memoryId: string): Promise<void>;
     private syncFactHashIndexAfterRewrite;
     removeFactContentHashesForMemories(memories: MemoryFile[]): Promise<void>;
+    /**
+     * Remove a memory's fact-ONLY hash 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, `factOnlyHashes` 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. In-memory only — `factOnlyHashes`
+     * is never persisted; it is rebuilt from the corpus. No-op for non-facts.
+     * Matches the shared index's unconditional per-hash removal so the two stay
+     * coherent.
+     */
+    removeFactOnlyHashForMemory(memory: MemoryFile): void;
     isFactContentHashAuthoritative(): Promise<boolean>;
     writeArtifact(quote: string, options?: {
         actor?: string;
@@ -1511,11 +1880,31 @@ declare class StorageManager {
     saveMeta(state: MetaState): Promise<void>;
     appendMemoryActionEvents(events: MemoryActionEvent[]): Promise<number>;
     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[]>;
@@ -1525,6 +1914,10 @@ declare class StorageManager {
         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>;
@@ -1646,13 +2039,15 @@ declare class StorageManager {
      */
     getMemoryById(id: string): Promise<MemoryFile | null>;
     /**
-     * Check which of the given memory IDs actually exist on disk.
+     * Resolve existing active memory IDs to their on-disk paths.
      *
      * 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.
+     * for citation usage tracking and other existence checks.
+     */
+    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>;
@@ -1739,4 +2134,4 @@ declare class StorageManager {
     private appendGeneratedMemoryLifecycleEventFailOpen;
 }
 
-export { countEntityStructuredFacts as A, fingerprintEntityStructuredFacts as B, ContentHashIndex as C, type DisagreementKind as D, isEntitySynthesisStale as E, FusionArtifactStore as F, isValidBufferSurpriseEvent as G, normalizeEntityName as H, normalizeFrontmatterForPath as I, normalizeStructuredSectionFacts as J, parseFrontmatter as K, parseFrontmatterStringValue as L, type MemoryWriteResult as M, type ReextractJobRequest as R, StorageManager as S, type FusedWearableConversation as a, type FusionConversationInput as b, type FusedSpeaker as c, type FusedSegment as d, type FusedDisagreement as e, type FusionOptions as f, type FusionDayResult as g, FUSION_KIND as h, type FusedContribution as i, type FusedConversationProvenance as j, type FusedDayFile as k, type FusedDayMeta as l, type FusedSegmentProvenance as m, type FusionSegmentInput as n, type SegmentPickReason as o, composeFusionDayMeta as p, hashFusionBody as q, normalizeAttributePairs as r, parseEntityFile as s, parseFusionDay as t, serializeEntityFile as u, serializeFusionDay as v, type MemoryLifecycleEventWriteOptions as w, buildEntitySchemaCacheKey as x, compareEntityTimestamps as y, compileEntityFacts as z };
+export { compareEntityTimestamps as A, compileEntityFacts as B, ContentHashIndex as C, type DisagreementKind as D, countEntityStructuredFacts as E, FusionArtifactStore as F, fingerprintEntityStructuredFacts as G, isEntitySynthesisStale as H, isValidBufferSurpriseEvent as I, normalizeEntityName as J, normalizeFrontmatterForPath as K, normalizeStructuredSectionFacts as L, type MemoryWriteResult as M, parseFrontmatter as N, parseFrontmatterStringValue as O, type ReextractJobRequest as R, StorageManager as S, type WriteMemoryOptions as W, type FusedWearableConversation as a, type FusionConversationInput as b, type FusedSpeaker as c, type FusedSegment as d, type FusedDisagreement as e, type FusionOptions as f, type FusionDayResult as g, FUSION_KIND as h, type FusedContribution as i, type FusedConversationProvenance as j, type FusedDayFile as k, type FusedDayMeta as l, type FusedSegmentProvenance as m, type FusionSegmentInput as n, type SegmentPickReason as o, composeFusionDayMeta as p, hashFusionBody as q, parseEntityFile as r, parseFusionDay as s, serializeEntityFile as t, serializeFusionDay as u, type ContentHashIndexLockOptions as v, FactHashIndexNotAuthoritativeError as w, type MemoryLifecycleEventWriteOptions as x, type SealedWriteExtras as y, buildEntitySchemaCacheKey as z };