@remnic/core 9.69.56 → 9.69.58

package/dist/orchestration/extraction-run.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Extraction-run coordinator — extracted from the orchestrator
+ * (issue #1526, seam 15).
+ *
+ * Owns the buffer→extract→persist pipeline orchestration:
+ *   - `runExtraction` — the main extraction pipeline coordinator
+ *     (normalize → threshold gate → namespace resolve → dedupe
+ *     fingerprint → extract → validate → persist → post-write hooks)
+ *   - dedupe support: `shouldQueueExtraction`,
+ *     `buildExtractionFingerprint`, `normalizeExtractionFingerprintTurns`
+ *   - `recordProcessedExtractionFingerprint` — meta recording
+ *
+ * The orchestrator constructs one instance and delegates the extraction
+ * run to it. `persistExtraction`, `maybeCapturePassiveCorrections`, and
+ * all post-write side-effect helpers arrive as injectable delegates so
+ * the orchestrator keeps ownership of cross-subsystem routing and the
+ * behavior-critical chokepoints it hosts.
+ *
+ * Behavior-preserving move from orchestrator.ts. No logic changes — the
+ * orchestrator keeps thin delegating methods so existing call sites
+ * and tests that exercise the public API continue to work.
+ */
+import type { StorageManager } from "../index.js";
+import { NamespaceStorageRouter } from "../namespaces/storage.js";
+import type { ExtractionEngine } from "../extraction.js";
+import type { SmartBuffer } from "../buffer.js";
+import type { ThreadingManager } from "../threading.js";
+import type { BoxBuilder } from "../boxes.js";
+import { type ResolvedScopeProfilePlan } from "../namespaces/scope-profiles.js";
+import type { CodingContext } from "../types.js";
+import { type ExtractionSourceContext } from "./extraction-origin-context.js";
+import { type GraphConstructionCapabilitySet, type MemoryLifecycleCapabilitySet } from "../capabilities.js";
+import type { PluginConfig, BufferTurn, ExtractionResult } from "../types.js";
+import type { TierMigrationCycleSummary } from "../recall-state.js";
+export interface ExtractionRunResult {
+    status: "completed" | "skipped";
+    reason?: string;
+    persistedCount: number;
+    durableOutputCount: number;
+    postPersistMetadataFailed?: boolean;
+}
+export declare class ExtractionDeadlineError extends Error {
+    readonly stage: string;
+    constructor(stage: string);
+}
+/** Dependencies injected by the orchestrator. All stable references or
+ *  live accessors — lazy getters for anything tests reassign
+ *  post-construction (buffer, extraction, storageRouter, threading). */
+export interface ExtractionRunCoordinatorDeps {
+    config: PluginConfig;
+    getBuffer: () => SmartBuffer;
+    getExtraction: () => Pick<ExtractionEngine, "extract">;
+    getStorageRouter: () => Pick<NamespaceStorageRouter, "storageFor">;
+    getThreading: () => Pick<ThreadingManager, "processTurn" | "updateThreadTitle">;
+    persistExtraction: (result: ExtractionResult, storage: StorageManager, threadIdForExtraction?: string | null, sourceContext?: ExtractionSourceContext, baseNamespace?: string, scopeProfileWritePlan?: ResolvedScopeProfilePlan | null, sourceText?: string, graphCaps?: GraphConstructionCapabilitySet, lifecycleCaps?: MemoryLifecycleCapabilitySet) => Promise<{
+        persistedIds: string[];
+        memoryPathById: Map<string, string>;
+    }>;
+    maybeCapturePassiveCorrections: (turns: readonly BufferTurn[], opts: {
+        sessionKey: string;
+        principal?: string;
+        namespace: string;
+        bufferKey: string;
+        isLiveSession: boolean;
+        abortSignal?: AbortSignal;
+    }) => Promise<void>;
+    resolveSelfNamespace: (sessionKey?: string) => string;
+    getCodingContextForSession: (sessionKey: string) => CodingContext | null;
+    applyCodingNamespaceOverlay: (sessionKey: string, namespace: string) => string;
+    boxBuilderFor: (storage: StorageManager) => Pick<BoxBuilder, "onExtraction">;
+    appendPersistedThreadEpisodes: (threadId: string, ids: string[]) => Promise<void>;
+    maybeScheduleConsolidation: (nonZero: boolean) => void;
+    requestQmdMaintenance: () => void;
+    runTierMigrationCycle: (storage: StorageManager, trigger: "extraction" | "maintenance" | "manual", options?: {
+        dryRun?: boolean;
+        limitOverride?: number;
+        force?: boolean;
+    }) => Promise<TierMigrationCycleSummary>;
+    getLastPersistExtractionDeferredCount: () => number;
+    recordProcessedExtractionFingerprint: (storage: StorageManager, fingerprint: string, preloadedMeta?: Awaited<ReturnType<StorageManager["loadMeta"]>>) => Promise<void>;
+}
+import { capExtractionRetryStateEntries, computeExtractionRetryNextEligibleMs, deriveSourceConnector, deriveTopicsFromExtraction } from "./extraction-run-helpers.js";
+import type { ExtractionResilienceStatus } from "./extraction-run-helpers.js";
+export { capExtractionRetryStateEntries, computeExtractionRetryNextEligibleMs, deriveSourceConnector, deriveTopicsFromExtraction, };
+export type { ExtractionResilienceStatus };
+/**
+ * Coordinates the extraction run pipeline. Holds the dedupe fingerprint
+ * cache (`recentExtractionFingerprints`) and delegates all side effects
+ * to injected orchestrator methods.
+ */
+export declare class ExtractionRunCoordinator {
+    private readonly deps;
+    private readonly recentExtractionFingerprints;
+    private readonly extractionRetryState;
+    private readonly hydratedRetryNamespaces;
+    private providerBreaker;
+    constructor(deps: ExtractionRunCoordinatorDeps);
+    private get config();
+    private latestSourceValidAtFromTurns;
+    normalizeExtractionFingerprintTurns(turns: BufferTurn[]): string[];
+    buildExtractionFingerprint(turns: BufferTurn[], bufferKey: string): string | null;
+    shouldQueueExtraction(turns: BufferTurn[], options?: {
+        commit?: boolean;
+        bufferKey?: string;
+    }): boolean;
+    recordProcessedExtractionFingerprint(storage: StorageManager, fingerprint: string, preloadedMeta?: Awaited<ReturnType<StorageManager["loadMeta"]>>): Promise<void>;
+    /** Lazily hydrate the in-memory retry-state mirror for a namespace from meta.
+     *  One-time per namespace per coordinator; the hot path is then a Map lookup.
+     *  Cross-process coherence: a fresh coordinator hydrates from the shared
+     *  meta.json, so a failure persisted by another process is honored here. */
+    private hydrateRetryStateFromMeta;
+    private logBreakerTransition;
+    /** True while the breaker suppresses non-forced attempts. Flips an expired
+     *  `open` breaker to `half_open`, which allows exactly one probe (the next
+     *  non-forced attempt) because the extraction queue is a serial drain. */
+    private isProviderBreakerOpen;
+    private onProviderFailure;
+    private resetProviderBreakerOnSuccess;
+    /** Rebuild `meta.extractionRetryState` from the in-memory namespace mirror,
+     *  bounded to the newest entries, and prune the mirror to match. */
+    private persistRetryStateToMeta;
+    /** Record an extraction failure into per-fingerprint backoff state + breaker,
+     *  persisting to namespace meta. Fail-open: never throws upward. */
+    private recordExtractionFailure;
+    /** Delete a fingerprint's retry entry from the mirror + meta. Returns whether
+     *  meta changed (so the caller can decide to persist). Does not touch the
+     *  breaker — callers pair this with `resetProviderBreakerOnSuccess`. */
+    private clearExtractionRetryEntry;
+    /** Live in-process resilience snapshot (breaker + backoff population). */
+    getExtractionResilienceStatus(): ExtractionResilienceStatus;
+    runExtraction(turns: BufferTurn[], options?: {
+        clearBufferAfterExtraction?: boolean;
+        clearMatchingTurns?: boolean;
+        skipCharThreshold?: boolean;
+        skipUserTurnThreshold?: boolean;
+        deadlineMs?: number;
+        bufferKey?: string;
+        abortSignal?: AbortSignal;
+        failOnExtractionFailure?: boolean;
+        /**
+         * Called immediately after durable extraction persistence returns, before
+         * any metadata, retention, or helper work. Lifecycle callers use this
+         * as the write-rate-limit commit boundary.
+         */
+        onDurableCommit?: () => void;
+        /**
+         * Explicit namespace override for the write path (#460).  When set, this
+         * is the namespace where extraction writes go instead of the one derived
+         * from `defaultNamespaceForPrincipal(resolvePrincipal(sessionKey))`.
+         * The resolved `principal` is still threaded into memory metadata for
+         * provenance; only the storage target is overridden.
+         */
+        writeNamespaceOverride?: string;
+        /**
+         * Pin the provenance principal instead of deriving it from
+         * `resolvePrincipal(sessionKey)`. When set, this is the identity an
+         * access surface already authenticated; used so observed-turn provenance
+         * is correct even though `turn.sessionKey` is the original key.
+         */
+        principalOverride?: string;
+        /**
+         * Access scope resolution may already have selected a profile while the
+         * session context remains intentionally unbound. Reuse that plan for
+         * persistence instead of deriving it from shared session state.
+         */
+        scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
+        /**
+         * Force the extractor call, bypassing the retry-backoff / circuit-breaker
+         * gate (extraction hot-loop hardening). Set by explicit flush paths.
+         */
+        forceExtractionAttempt?: boolean;
+    }): Promise<ExtractionRunResult>;
+}
+//# sourceMappingURL=extraction-run.d.ts.map

package/dist/orchestration/extraction-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-run.d.ts","sourceRoot":"","sources":["../../src/orchestration/extraction-run.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/extraction-shutdown.d.ts

@@ -0,0 +1,6 @@
+export declare function drainExtractionAndShutdownDependencyPropagation(extractionQueue: {
+    pauseAndDrain(): Promise<boolean>;
+}, dependencyPropagationDelivery: {
+    shutdown(): Promise<void>;
+} | undefined): Promise<unknown | undefined>;
+//# sourceMappingURL=extraction-shutdown.d.ts.map

package/dist/orchestration/extraction-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-shutdown.d.ts","sourceRoot":"","sources":["../../src/orchestration/extraction-shutdown.ts"],"names":[],"mappings":"AAEA,wBAAsB,+CAA+C,CACnE,eAAe,EAAE;IAAE,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,EACtD,6BAA6B,EAAE;IAAE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,SAAS,GACvE,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAe9B"}

package/dist/orchestration/extraction-watermark.d.ts

@@ -0,0 +1,28 @@
+import { type TokenCapabilities } from "../access-token-capabilities.js";
+import { type CorpusNamespaceRoot } from "../corpus-watermark.js";
+import type { ExtractionWatermarkRead } from "../extraction-liveness.js";
+import type { MetaState, PluginConfig } from "../types.js";
+export interface ExtractionWatermarkMeta extends Pick<MetaState, "lastExtractionAt"> {
+    extractionCount?: number;
+    lastConsolidationAt?: string | null;
+}
+export interface ExtractionWatermarkStorage {
+    readonly dir: string;
+    loadMeta(): Promise<ExtractionWatermarkMeta>;
+}
+export interface ExtractionNamespaceRootCache {
+    getResolvedRootsStatus(compute: () => Promise<CorpusNamespaceRoot[]>): {
+        roots: CorpusNamespaceRoot[] | undefined;
+        refreshError: unknown;
+    };
+}
+export interface AggregateExtractionWatermarkOptions {
+    config: PluginConfig;
+    rootStorage: ExtractionWatermarkStorage;
+    rootMeta?: ExtractionWatermarkMeta;
+    storageForNamespace(namespace: string, rootDir: string): ExtractionWatermarkStorage | Promise<ExtractionWatermarkStorage>;
+    rootsCache?: ExtractionNamespaceRootCache;
+    caps?: TokenCapabilities;
+}
+export declare function readAggregateExtractionWatermark(options: AggregateExtractionWatermarkOptions): Promise<ExtractionWatermarkRead>;
+//# sourceMappingURL=extraction-watermark.d.ts.map

package/dist/orchestration/extraction-watermark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-watermark.d.ts","sourceRoot":"","sources":["../../src/orchestration/extraction-watermark.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEpG,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE/F,OAAO,KAAK,EAAuB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,4BAA4B;IAC3C,sBAAsB,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,mBAAmB,EAAE,CAAC,GAAG;QACrE,KAAK,EAAE,mBAAmB,EAAE,GAAG,SAAS,CAAC;QACzC,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,mCAAmC;IAClD,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,0BAA0B,CAAC;IACxC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACpE,UAAU,CAAC,EAAE,4BAA4B,CAAC;IAC1C,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAwKD,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,uBAAuB,CAAC,CAsElC"}

package/dist/orchestration/generic-recall-paths.d.ts

@@ -0,0 +1,36 @@
+import type { QmdSearchResult } from "../types.js";
+export { isExternalWikiCollectionName } from "../external-wiki-guard.js";
+export interface GenericRecallPathPolicy {
+    readonly memoryDir?: string;
+    readonly qmdCollection?: string;
+    readonly qmdColdCollection?: string;
+    /**
+     * The collection THIS request named, when it named one. A caller may select
+     * a custom collection whose name is also a memory category, which the
+     * configured names alone cannot disambiguate.
+     */
+    readonly requestedCollection?: string;
+}
+type GenericRecallPathSource = "filesystem" | "qmd";
+export declare function isTopLevelArchivePath(filePath: string, policy?: GenericRecallPathPolicy, source?: GenericRecallPathSource): boolean;
+/**
+ * Paths an EXPLICIT ranked search must not return.
+ *
+ * Narrower than {@link isGenericRecallExcludedPath} on purpose. Recall
+ * injection also drops archived memories because they are cold by definition,
+ * but archive is explicitly reserved for "explicit read or search surfaces"
+ * (docs/architecture/memory-lifecycle.md) — hiding it from `memory_search`
+ * would remove the only way to find it. Everything else stays excluded: those
+ * paths flow through their own dedicated surfaces, never a generic search.
+ */
+export declare function isSearchExcludedPath(filePath: string, policy?: GenericRecallPathPolicy, source?: GenericRecallPathSource): boolean;
+export declare function isGenericRecallExcludedPath(filePath: string, policy?: GenericRecallPathPolicy, source?: GenericRecallPathSource): boolean;
+export declare function filterRecallCandidates(candidates: QmdSearchResult[], options: {
+    namespacesEnabled: boolean;
+    recallNamespaces: string[];
+    resolveNamespace: (path: string) => string;
+    limit: number;
+    pathPolicy?: GenericRecallPathPolicy;
+    memoryRoot?: string;
+}): QmdSearchResult[];
+//# sourceMappingURL=generic-recall-paths.d.ts.map

package/dist/orchestration/generic-recall-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-recall-paths.d.ts","sourceRoot":"","sources":["../../src/orchestration/generic-recall-paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAazE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,KAAK,uBAAuB,GAAG,YAAY,GAAG,KAAK,CAAC;AAoDpD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,uBAA4B,EACpC,MAAM,GAAE,uBAAsC,GAC7C,OAAO,CAUT;AAaD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,uBAA4B,EACpC,MAAM,GAAE,uBAAsC,GAC7C,OAAO,CA2BT;AA2FD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,uBAA4B,EACpC,MAAM,GAAE,uBAAsC,GAC7C,OAAO,CAST;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,EAAE;IACP,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,eAAe,EAAE,CAYnB"}

package/dist/orchestration/graph-path-state-loader.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryFile } from "../types.js";
+import type { StorageManager } from "../index.js";
+export declare class GraphPathStateLoader {
+    private archivePathIndexes?;
+    private archivePathIndexBuilds;
+    private archiveLstat;
+    private archiveRealpath;
+    private openArchiveDirectory;
+    readNode(storage: StorageManager, nodeId: string, deadlineAtMs: number | null | undefined, allowArchiveLookup: boolean): Promise<MemoryFile | null>;
+    private resolveContainedPath;
+    private getArchivePathIndex;
+    private waitForDeadline;
+    private buildArchivePathIndex;
+}
+//# sourceMappingURL=graph-path-state-loader.d.ts.map

package/dist/orchestration/graph-path-state-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-path-state-loader.d.ts","sourceRoot":"","sources":["../../src/orchestration/graph-path-state-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA6BlD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAsC;IACjE,OAAO,CAAC,sBAAsB,CAA6D;IAC3F,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,eAAe,CAAmD;IAC1E,OAAO,CAAC,oBAAoB,CAAoD;IAC1E,QAAQ,CACZ,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,kBAAkB,EAAE,OAAO,GAC1B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;YA2Cf,oBAAoB;YA0BpB,mBAAmB;YA+DnB,eAAe;YAgBf,qBAAqB;CA+HpC"}

package/dist/orchestration/graph-recall-coordinator.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Graph-recall coordinator — extracted from the orchestrator (issue #1526).
+ *
+ * Owns the graph-expansion subsystem in recall: spreading-activation
+ * traversal from seed memories, seed-path resolution relative to
+ * per-namespace storage, and the last-graph-recall snapshot persistence.
+ * Behavior-preserving move from orchestrator.ts with bounded graph-state
+ * lookups and optional path scoring. The orchestrator constructs one instance
+ * and keeps thin delegating methods so existing call sites (recallInternal,
+ * cold-fallback pipeline) continue to work.
+ *
+ * Config, storage, graph index, namespace resolution, and QMD result
+ * resolution are accessed through getter callbacks (not captured at
+ * construction) so that post-construction reassignment of the orchestrator's
+ * live fields is honored. This mirrors the RecallRerankCoordinator /
+ * ContradictionLinkingCoordinator accessor pattern.
+ */
+import type { MemoryFile, MemoryIntent, PluginConfig, QmdSearchResult, RecallPlanMode } from "../types.js";
+import type { StorageManager } from "../index.js";
+import type { GraphIndex } from "../graph.js";
+import type { GraphRecallExpandedEntry } from "../recall-state.js";
+export interface GraphRecallRankedResult {
+    path: string;
+    score: number;
+    docid?: string;
+    sourceLabels: string[];
+}
+export interface GraphRecallShadowComparison {
+    baselineCount: number;
+    graphCount: number;
+    overlapCount: number;
+    overlapRatio: number;
+    averageOverlapDelta: number;
+}
+export interface GraphRecallExpansionOptions {
+    memoryResults: QmdSearchResult[];
+    recallNamespaces: string[];
+    recallResultLimit: number;
+    /** Query-time instant used for graph-path invalidity checks. */
+    asOf?: string;
+    asOfMs?: number;
+    deadlineAtMs?: number | null;
+    /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
+    includeLowConfidence?: boolean;
+}
+export interface GraphRecallExpansionResult {
+    merged: QmdSearchResult[];
+    seedPaths: string[];
+    expandedPaths: GraphRecallExpandedEntry[];
+    seedResults: QmdSearchResult[];
+}
+export declare function mergeGraphExpandedResults(primary: QmdSearchResult[], expanded: QmdSearchResult[]): QmdSearchResult[];
+export declare function graphPathRelativeToStorage(storageDir: string, candidatePath: string): string | null;
+export declare function blendGraphExpandedRecallScore(options: {
+    graphActivationScore: number;
+    seedRecallScore: number;
+    activationWeight: number;
+    blendMin: number;
+    blendMax: number;
+}): number;
+export declare class GraphRecallCoordinator {
+    private readonly getConfig;
+    private readonly getStorage;
+    private readonly storageFor;
+    private readonly graphIndexFor;
+    private readonly namespaceFromPath;
+    private readonly resolveColdQmdResultForRecall;
+    private readonly storageForAbsoluteQmdResultPath;
+    private readonly readQmdResultMemory;
+    private readonly graphPathStateLoader;
+    constructor(options: {
+        getConfig: () => PluginConfig;
+        getStorage: () => StorageManager;
+        storageFor: (namespace: string) => Promise<StorageManager>;
+        graphIndexFor: (storage: StorageManager) => GraphIndex;
+        namespaceFromPath: (p: string) => string;
+        resolveColdQmdResultForRecall: (result: QmdSearchResult, fallbackStorage: StorageManager, recallNamespaces: readonly string[]) => Promise<{
+            namespace: string;
+            result: QmdSearchResult;
+        } | null>;
+        storageForAbsoluteQmdResultPath: (resultPath: string, fallbackStorage: StorageManager, recallNamespaces: readonly string[]) => Promise<{
+            storage: StorageManager;
+            dir: string;
+            namespace: string;
+        } | null>;
+        readQmdResultMemory: (resultPath: string, fallbackStorage: StorageManager, recallNamespaces: readonly string[], preferredNamespace?: string) => Promise<MemoryFile | null>;
+    });
+    expandResultsViaGraph(options: GraphRecallExpansionOptions): Promise<GraphRecallExpansionResult>;
+    recordLastGraphRecallSnapshot(options: {
+        storage: StorageManager;
+        prompt: string;
+        recallMode: RecallPlanMode;
+        recallNamespaces: string[];
+        seedPaths: string[];
+        expandedPaths: GraphRecallExpandedEntry[];
+        status: "completed" | "skipped" | "aborted";
+        reason?: string;
+        shadowMode?: boolean;
+        queryIntent: MemoryIntent;
+        seedResults?: GraphRecallRankedResult[];
+        finalResults?: GraphRecallRankedResult[];
+        shadowComparison?: GraphRecallShadowComparison;
+    }): Promise<void>;
+    private graphSeedPathRelativeToStorage;
+    private graphSeedPathsWithinDeadline;
+}
+//# sourceMappingURL=graph-recall-coordinator.d.ts.map

package/dist/orchestration/graph-recall-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-recall-coordinator.d.ts","sourceRoot":"","sources":["../../src/orchestration/graph-recall-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/harmonic-construction-persist.d.ts

@@ -0,0 +1,58 @@
+import { type HarmonicConstructionInput } from "../harmonic-construction.js";
+import type { StorageManager } from "../index.js";
+import type { ExtractionResult } from "../types.js";
+export interface HarmonicPersistenceEntry {
+    storage: {
+        dir: string;
+    };
+    facts: HarmonicConstructionInput["persistedFacts"];
+}
+export declare function filterHarmonicEntityMentions(facts: HarmonicConstructionInput["persistedFacts"], entityMentions: ExtractionResult["entities"]): ExtractionResult["entities"];
+/**
+ * Finding B (round N+3, PR #2771): a successful merge-on-write commits new
+ * claims into an EXISTING target id. `persistedIds` stays new-fragment only
+ * by contract and cue anchors ride only through the per-fact harmonic
+ * entry, so without this enqueue a merge-only extraction emits no episode,
+ * abstraction node, or cue anchors for the committed claims. Enqueue the
+ * surviving target — with the COMMITTED merged body as content — into the
+ * same batch map the create path feeds, so the end-of-batch
+ * {@link persistConstructedHarmonicRecords} pass covers it.
+ *
+ * Round N+9 (C): two facts merging into the SAME target in one batch enqueue
+ * twice under one `memoryId`. `deriveHarmonicRecords` dedupes only
+ * `sourceMemoryIds` — `persistedFacts` keeps both entries, so the episode
+ * summary concatenated both cumulative snapshots and the inserted-at
+ * metadata overwrote its duplicate key. Coalesce instead: the entry for a
+ * repeated target is REPLACED by the latest committed body (each merge's
+ * body is cumulative, so the latest carries every claim) while the cue
+ * anchors UNION across merges — anchors are deduped by id downstream, but
+ * the union keeps the earlier merge's anchors alive when the later incoming
+ * fact carried none.
+ *
+ * #2807 (finding 3): the entry's metadata comes from the REREAD committed
+ * target, never the incoming fact alone. The parity gate lets an incoming
+ * fact with no entityRef merge into a target that HAS one (only a
+ * differing non-undefined incoming entity refuses), and incoming tags are
+ * a subset of the target's — so stamping the incoming fields onto the
+ * cumulative body dropped the target's committed entity association and
+ * extra tags, and `deriveHarmonicRecords` skipped the deterministic
+ * entity cue/topic linkage for the merged claims. Cue anchors stay
+ * incoming-only: they are event-specific. An unreadable or advanced record
+ * falls back to the incoming fact's own fields (fail-open, like every
+ * merge-adjacent effect).
+ */
+export declare function enqueueMergedTargetForHarmonicConstruction(entries: Map<string, {
+    storage: StorageManager;
+    facts: HarmonicConstructionInput["persistedFacts"];
+}>, storage: StorageManager, fact: Omit<HarmonicConstructionInput["persistedFacts"][number], "memoryId" | "insertedAt">, memoryId: string, content: string, insertedAt: string): Promise<void>;
+export declare function persistConstructedHarmonicRecords(options: {
+    entries: Iterable<HarmonicPersistenceEntry>;
+    baseStorageDir: string;
+    abstractionNodeStoreDir?: string;
+    sessionKey?: string;
+    validAt?: string;
+    episodeTitle?: string;
+    anchorsEnabled: boolean;
+    entityMentions: ExtractionResult["entities"];
+}): Promise<void>;
+//# sourceMappingURL=harmonic-construction-persist.d.ts.map

package/dist/orchestration/harmonic-construction-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harmonic-construction-persist.d.ts","sourceRoot":"","sources":["../../src/orchestration/harmonic-construction-persist.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,yBAAyB,EAM/B,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACzB,KAAK,EAAE,yBAAyB,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,yBAAyB,CAAC,gBAAgB,CAAC,EAClD,cAAc,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAC3C,gBAAgB,CAAC,UAAU,CAAC,CAiB9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,0CAA0C,CAC9D,OAAO,EAAE,GAAG,CACV,MAAM,EACN;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,yBAAyB,CAAC,gBAAgB,CAAC,CAAA;CAAE,CAChF,EACD,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,IAAI,CACR,yBAAyB,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,EACnD,UAAU,GAAG,YAAY,CAC1B,EACD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED,wBAAsB,iCAAiC,CAAC,OAAO,EAAE;IAC/D,OAAO,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAAC;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;CAC9C,GAAG,OAAO,CAAC,IAAI,CAAC,CAsChB"}

package/dist/orchestration/lifecycle-policy-coordinator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Lifecycle-policy coordinator — extracted from the orchestrator
+ * (issue #1526, seam 6).
+ *
+ * Owns the deterministic memory-lifecycle pipeline: heat/decay scoring
+ * (`runLifecyclePolicyPass`), fact archival (`runFactArchival`),
+ * summarization (`runSummarization`), and topic extraction
+ * (`runTopicExtraction`). Also owns the action-outcome prior builder
+ * (`buildLifecycleActionPriors` / `actionOutcomePriorDelta`) that feeds
+ * the lifecycle transition decider.
+ *
+ * The orchestrator constructs one instance and delegates the internal
+ * entrypoints to it. The public wrapper (`runLifecyclePolicyNow`)
+ * remains on the orchestrator as a thin pass-through. Storage is the
+ * orchestrator's stable `this.storage` (or a per-namespace override
+ * passed via options); the extraction engine, embedding-fallback, and
+ * content-hash callbacks arrive as deps so the orchestrator keeps
+ * ownership of gateway routing and cross-subsystem persistence.
+ *
+ * Behavior-preserving move from orchestrator.ts. No logic changes — the
+ * orchestrator keeps thin delegating methods so existing call sites
+ * and tests that exercise the public API continue to work.
+ */
+import type { StorageManager } from "../index.js";
+import type { ExtractionEngine } from "../extraction.js";
+import type { EmbeddingFallback } from "../embedding-fallback.js";
+import type { PluginConfig, MemoryFile, MemoryActionEvent } from "../types.js";
+import type { RecallHandleHistoryStore } from "../recall-state.js";
+/** Dependencies injected by the orchestrator. All stable references or
+ *  live accessors. */
+export interface LifecyclePolicyCoordinatorDeps {
+    config: PluginConfig;
+    /** Live accessor: the orchestrator's storage manager (stable post-ctor). */
+    getStorage: () => StorageManager;
+    /** The extraction engine — used for summarization. */
+    extraction: ExtractionEngine;
+    /** The embedding-fallback manager used for index cleanup on archival. */
+    embeddingFallback: EmbeddingFallback;
+    /** Effective lifecycle thresholds (promote/stale/archive). Delegated to
+     *  the orchestrator which owns runtime-policy-values overlay. */
+    getEffectiveLifecycleThresholds: () => {
+        promoteHeatThreshold: number;
+        staleDecayThreshold: number;
+        archiveDecayThreshold: number;
+    };
+    /** Remove a memory's content-hash entry from the storage-scoped index.
+     *  Delegated to the orchestrator which owns the per-storage index map. */
+    removeContentHashForMemory: (targetStorage: StorageManager, memory: MemoryFile, context: string) => Promise<void>;
+    /** Persist all dirty content-hash indexes to disk. */
+    saveContentHashIndexes: () => Promise<void>;
+    /** Recall-handle ring used to suppress quoted-back echo during seed graduation. */
+    getHandleHistory?: () => RecallHandleHistoryStore;
+}
+/**
+ * Coordinates the memory-lifecycle policy pipeline. Holds no mutable
+ * state of its own — all persistence flows through the injected storage
+ * managers and callbacks.
+ */
+export declare class LifecyclePolicyCoordinator {
+    private readonly deps;
+    constructor(deps: LifecyclePolicyCoordinatorDeps);
+    private get config();
+    actionOutcomePriorDelta(event: MemoryActionEvent): number;
+    buildLifecycleActionPriors(storage?: StorageManager): Promise<Map<string, number>>;
+    runLifecyclePolicyPass(allMemories: MemoryFile[], storage?: StorageManager): Promise<number>;
+    /**
+     * Archive old, low-importance, rarely-accessed facts (v6.0).
+     * Moves eligible facts from facts/ to archive/YYYY-MM-DD/.
+     * Returns the number of archived facts.
+     */
+    runFactArchival(allMemories: MemoryFile[]): Promise<number>;
+    /**
+     * Run memory summarization if memory count exceeds threshold (Phase 4A).
+     */
+    runSummarization(allMemories: MemoryFile[]): Promise<void>;
+    /**
+     * Run topic extraction on all memories (Phase 4B).
+     */
+    runTopicExtraction(allMemories: MemoryFile[]): Promise<void>;
+}
+//# sourceMappingURL=lifecycle-policy-coordinator.d.ts.map

package/dist/orchestration/lifecycle-policy-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-policy-coordinator.d.ts","sourceRoot":"","sources":["../../src/orchestration/lifecycle-policy-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAmBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnE;sBACsB;AACtB,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,YAAY,CAAC;IACrB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,cAAc,CAAC;IACjC,sDAAsD;IACtD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,yEAAyE;IACzE,iBAAiB,EAAE,iBAAiB,CAAC;IACrC;qEACiE;IACjE,+BAA+B,EAAE,MAAM;QACrC,oBAAoB,EAAE,MAAM,CAAC;QAC7B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF;8EAC0E;IAC1E,0BAA0B,EAAE,CAC1B,aAAa,EAAE,cAAc,EAC7B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,sDAAsD;IACtD,sBAAsB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,wBAAwB,CAAC;CACnD;AAED;;;;GAIG;AACH,qBAAa,0BAA0B;IAEnC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,8BAA8B;IAGvD,OAAO,KAAK,MAAM,GAEjB;IAMD,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM;IAuBnD,0BAA0B,CAC9B,OAAO,GAAE,cAAuC,GAC/C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAsDzB,sBAAsB,CAC1B,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,GAAE,cAAuC,GAC/C,OAAO,CAAC,MAAM,CAAC;IAwHlB;;;;OAIG;IACG,eAAe,CACnB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,MAAM,CAAC;IAyFlB;;OAEG;IACG,gBAAgB,CACpB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC;IAsGhB;;OAEG;IACG,kBAAkB,CACtB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC;CAmBjB"}