@saihm/shm 0.0.0-stage → 0.38.0

package/dist/session/memory_session.js

@@ -0,0 +1,1183 @@
+import { checkEntitlement } from "../entitlement/entitlement.js";
+import { buildWarmIndex } from "../store/warm_index.js";
+import { SaihmBodySource } from "../answer/saihm_body_source.js";
+import { CachingBodySource, DEFAULT_CACHE_CONFIG } from "../answer/caching_body_source.js";
+import { PersistentBodySource } from "../answer/persistent_body_source.js";
+import { OwnCellBodySource } from "../answer/own_cell_body_source.js";
+import { restoreOrCold, takeSnapshot } from "../store/warm_start.js";
+import { decodeIndexPart, encodeIndexPart, IndexPartError, INDEX_PART_NAME } from "../store/index_snapshot.js";
+import { CorpusWarmer } from "../answer/corpus_warmer.js";
+import { composeLeverStack } from "../tuning/lever_stack.js";
+import { parseLifecycle, } from "../retrieval/thread_lifecycle.js";
+import { ProactiveInjector } from "../inject/proactive_injector.js";
+import { ErasureBus, ErasureDetector } from "../erasure/bus.js";
+import { IndexWatcher } from "../erasure/index_watcher.js";
+import { FeedWatcher, FileFeedCursorStore, resolveFeedPath } from "../erasure/feed_watcher.js";
+import { FileWithheldStore, MemoryWithheldStore } from "../erasure/withheld_store.js";
+import { acquireWriterLock, canonicalLockDir } from "../store/writer_lock.js";
+import { collectListing, decideFromIndex, decideFromListing, decideFromProbe, summarize } from "../erasure/reconcile.js";
+import { resolveChangesPath } from "../erasure/changes_feed.js";
+import { ChangeFeedFollower } from "./change_feed.js";
+import { parseServerFeatures } from "../saihm_client/server_features.js";
+import { FederatedReadPort } from "../saihm_client/federated_port.js";
+import { homedir } from "node:os";
+import { dirname, join as joinPath } from "node:path";
+import { ContentFingerprintIndex } from "../standing/content_fingerprint.js";
+import { surfaceStanding } from "../standing/surface.js";
+import { parseLabel } from "../ingest/parse.js";
+import { scopeFrom, withLineage, composeScopes } from "../retrieval/scope.js";
+import { isDerivedLabel } from "../derived/codec.js";
+import { assembleThread } from "../assemble/thread.js";
+import { assembleHistory, epochsFromHits } from "../history/answerable.js";
+import { assembleFleetReport } from "../fleet/knowledge.js";
+import { assembleComplianceReport } from "../compliance/report.js";
+import { planTiers } from "../tiers/membership.js";
+import { Consolidator } from "../consolidate/consolidator.js";
+import { verifyResume } from "../resume/resume.js";
+export class MemorySession {
+    retriever;
+    bodies;
+    answerRetriever;
+    bus;
+    detector;
+    warm;
+    port;
+    persistent;
+    bodyStore;
+    rerankRetriever;
+    threadRetriever;
+    standingWiring;
+    labelMap;
+    stampLookup;
+    lineageLookup;
+    embedder;
+    audit;
+    feedWatcher;
+    feedUnwired;
+    reconcileCfg;
+    reconcileUnwired;
+    watcher;
+    withheldNow = new Set();
+    lastReconcile;
+    reconcileChain = Promise.resolve();
+    withheldFault;
+    withheldLoadFaultOnce;
+    withheldLoadNote;
+    withheldForeign;
+    withheldLoadFault;
+    changeFollower;
+    changeUnwired;
+    ownReads;
+    ownReadsOff = "not wired";
+    warmStartWiring;
+    warmStartOff = "not requested — pass warmStart (a snapshot client) to restore and take snapshots";
+    lastWarmTake = null;
+    writerLocks;
+    writerLocksReleased;
+    closed = false;
+    withheldSaves = new Set();
+    withheldGuard;
+    constructor(retriever, bodies, answerRetriever, bus, detector, warm, port, persistent, bodyStore, rerankRetriever, threadRetriever, standingWiring, labelMap, stampLookup, lineageLookup, embedder, audit, feedWatcher, feedUnwired, reconcileCfg, reconcileUnwired) {
+        this.retriever = retriever;
+        this.bodies = bodies;
+        this.answerRetriever = answerRetriever;
+        this.bus = bus;
+        this.detector = detector;
+        this.warm = warm;
+        this.port = port;
+        this.persistent = persistent;
+        this.bodyStore = bodyStore;
+        this.rerankRetriever = rerankRetriever;
+        this.threadRetriever = threadRetriever;
+        this.standingWiring = standingWiring;
+        this.labelMap = labelMap;
+        this.stampLookup = stampLookup;
+        this.lineageLookup = lineageLookup;
+        this.embedder = embedder;
+        this.audit = audit;
+        this.feedWatcher = feedWatcher;
+        this.feedUnwired = feedUnwired;
+        this.reconcileCfg = reconcileCfg;
+        this.reconcileUnwired = reconcileUnwired;
+    }
+    static _create(retriever, bodies, answerRetriever, bus, detector, warm, port, persistent, bodyStore, rerankRetriever, threadRetriever, standingWiring, labelMap, stampLookup, lineageLookup, embedder, audit, feedWatcher, feedUnwired, reconcileCfg, reconcileUnwired) {
+        return new MemorySession(retriever, bodies, answerRetriever, bus, detector, warm, port, persistent, bodyStore, rerankRetriever, threadRetriever, standingWiring, labelMap, stampLookup, lineageLookup, embedder, audit, feedWatcher, feedUnwired, reconcileCfg, reconcileUnwired);
+    }
+    scope(spec) {
+        const base = scopeFrom(spec, {
+            stampOf: this.stampLookup,
+            namespaceOf: (id) => {
+                const label = this.labelMap.get(id);
+                return label === undefined ? undefined : parseLabel(label).namespace;
+            },
+        });
+        return withLineage(base, {
+            isDerived: (id) => isDerivedLabel(this.labelMap.get(id) ?? ""),
+            lineageOf: this.lineageLookup,
+        });
+    }
+    census(scope) {
+        return this.retriever.census(scope);
+    }
+    threads(opts = {}) {
+        const out = new Map();
+        for (const row of this.retriever.enumerate(opts.scope ?? composeScopes())) {
+            const t = this.stampLookup(row.cellId).thread;
+            if (t !== undefined)
+                out.set(t, (out.get(t) ?? 0) + 1);
+        }
+        return out;
+    }
+    thread(slug, opts = {}) {
+        const threadScope = this.scope({ threads: [slug] });
+        const scope = opts.scope === undefined ? threadScope : composeScopes(threadScope, opts.scope);
+        const asOf = opts.asOfEpoch !== undefined ? { asOfEpoch: opts.asOfEpoch } : undefined;
+        const rows = this.retriever.enumerate(scope, asOf);
+        const scoped = opts.scope === undefined ? undefined
+            : { name: opts.scope.name, notAdmitted: this.retriever.enumerate(threadScope, asOf).length - rows.length };
+        const anyThread = { name: "any-thread", admits: (id) => this.stampLookup(id).thread !== undefined };
+        const corpusHasThreadStamps = this.retriever.census(anyThread).admitted > 0;
+        const account = assembleThread(slug, rows, {
+            stampOf: this.stampLookup,
+            corpusHasThreadStamps,
+            labelOf: (id) => this.labelMap.get(id),
+            ...(opts.freshnessOf !== undefined ? { freshnessOf: opts.freshnessOf } : {}),
+            ...(opts.nowEpoch !== undefined ? { nowEpoch: opts.nowEpoch } : {}),
+            ...(opts.staleAfterHours !== undefined ? { staleAfterHours: opts.staleAfterHours } : {}),
+        });
+        const described = scoped === undefined ? account : { ...account, scoped };
+        if (opts.resume === undefined)
+            return described;
+        const report = verifyResume(opts.resume.claims, opts.resume.probes, opts.resume.here !== undefined ? { here: opts.resume.here } : {});
+        return { ...described, resume: report };
+    }
+    async history(query, opts = {}) {
+        const queryVector = await this.retriever.embedQuery(query);
+        const base = {
+            ...(opts.maxK !== undefined ? { maxK: opts.maxK } : {}),
+            ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+            queryVector,
+        };
+        const current = await this.retriever.selectDetailed(query, base);
+        const epochs = opts.at !== undefined ? [...new Set(opts.at)] : epochsFromHits(current);
+        const maxViews = Number.isInteger(opts.maxViews) && opts.maxViews >= 0 ? opts.maxViews : 32;
+        if (epochs.length > maxViews) {
+            throw new Error(`history: ${epochs.length} as-of views exceed maxViews=${maxViews} — refusing to truncate a timeline; raise maxViews or pass fewer epochs`);
+        }
+        const views = [];
+        for (const asOfEpoch of epochs)
+            views.push({ asOfEpoch, hits: await this.retriever.selectDetailed(query, { ...base, asOfEpoch }) });
+        const scopeOpt = opts.scope !== undefined ? { scope: opts.scope } : {};
+        return assembleHistory({
+            query,
+            current,
+            views,
+            reason: opts.at !== undefined ? "caller" : "arrival",
+            knowableAt: (cellId, asOfEpoch) => this.retriever.vetCandidates([cellId], { asOfEpoch, ...scopeOpt }).length === 1,
+            labelOf: (id) => this.labelMap.get(id),
+            threadOf: (id) => this.stampLookup(id).thread,
+        });
+    }
+    async fleet(opts = {}) {
+        const rows = this.retriever.enumerate(opts.scope ?? composeScopes());
+        const epochOf = new Map();
+        for (const r of rows)
+            if (r.ingestEpoch > 0)
+                epochOf.set(r.cellId, r.ingestEpoch);
+        const fleetRows = rows.map((r) => {
+            const label = this.labelMap.get(r.cellId);
+            const thread = this.stampLookup(r.cellId).thread;
+            return {
+                cellId: r.cellId,
+                ...(r.ingestEpoch > 0 ? { ingestEpoch: r.ingestEpoch } : {}),
+                namespace: label === undefined ? "unknown" : parseLabel(label).namespace,
+                ...(thread !== undefined ? { thread } : {}),
+                ...(r.supersededBy !== undefined ? { supersededBy: r.supersededBy } : {}),
+                ...(r.retiredBy !== undefined ? { retiredBy: r.retiredBy } : {}),
+                ...(r.derived === true ? { derived: true } : {}),
+            };
+        });
+        let clusters;
+        if (opts.clusters !== false) {
+            const entries = rows.map((r) => ({ cellId: r.cellId, label: this.labelMap.get(r.cellId) ?? "", epoch: r.ingestEpoch, byteSize: 0, tier: "index", forgotten: false }));
+            clusters = (await Consolidator.build(entries, this.embedder)).redundancyClusters();
+        }
+        const policy = {
+            ...(opts.thinBelow !== undefined ? { thinBelow: opts.thinBelow } : {}),
+            ...(opts.staleAfterHours !== undefined ? { staleAfterHours: opts.staleAfterHours } : {}),
+            ...(opts.driftWindowHours !== undefined ? { driftWindowHours: opts.driftWindowHours } : {}),
+        };
+        return assembleFleetReport({
+            rows: fleetRows,
+            ...(clusters !== undefined ? { clusters } : {}),
+            ...(opts.nowEpoch !== undefined ? { nowEpoch: opts.nowEpoch } : {}),
+            policy,
+            epochOf: (id) => epochOf.get(id),
+        });
+    }
+    async standing(question, retrievedCellIds, nowEpochMs, cfg = {}) {
+        if (!this.standingWiring) {
+            throw new Error("standing() requires a `standingStore` at openMemorySession. Without one there is no store " +
+                "to audit against and no erasure subscription for the answers it would write, so an empty " +
+                "result here would be indistinguishable from 'nothing matched'.");
+        }
+        const { store, index } = this.standingWiring;
+        return surfaceStanding(question, retrievedCellIds, { store, index }, nowEpochMs, cfg);
+    }
+    get standingStats() {
+        if (!this.standingWiring) {
+            return { enabled: false, refreshes: 0, bodyFailures: 0, fingerprintScope: "label" };
+        }
+        const { refreshes, bodyFailures } = this.standingWiring.index.stats;
+        return { enabled: true, refreshes, bodyFailures, fingerprintScope: this.standingWiring.scope };
+    }
+    async warmBodies(opts = {}) {
+        if (!this.persistent || !this.bodyStore) {
+            return {
+                scanned: 0, alreadyWarm: 0, ineligible: 0, targeted: 0, consumed: 0,
+                filled: 0, skippedPartial: 0, errors: 0,
+                remaining: 0, stoppedReason: "complete", elapsedMs: 0,
+            };
+        }
+        return new CorpusWarmer(this.port, this.bodyStore, this.persistent).warm(opts);
+    }
+    proactiveInjector(cfg = {}) {
+        const audit = this.audit;
+        const onResult = audit === undefined
+            ? cfg.onResult
+            : (result) => {
+                audit.recordInjection(result);
+                cfg.onResult?.(result);
+            };
+        return new ProactiveInjector(this.answerRetriever, this.bodies, { ...cfg, ...(onResult !== undefined ? { onResult } : {}) });
+    }
+    get auditTrail() {
+        return this.audit;
+    }
+    compliance(opts = {}) {
+        if (this.audit === undefined)
+            throw new Error("compliance: no audit trail configured — pass `audit: new AuditTrail(...)` at open");
+        const feed = this.erasureFeed;
+        const feedNotes = feed.mode === "watching" ? [] : [`erasure feed ${feed.mode}${feed.mode === "not-wired" ? `: ${feed.reason}` : ""} — protocol forgets reach this session only through checkErasures()/watch() or session.bus.publish()`];
+        const recon = this.reconciliation;
+        if (recon.mode !== "configured")
+            feedNotes.push(`reconciliation ${recon.mode}${recon.mode === "not-wired" ? `: ${recon.reason}` : ""} — a copied row outlives the cell it copies when the substrate's client fails to write a line`);
+        return assembleComplianceReport(this.audit.events(), { ...opts, dropped: this.audit.dropped, wired: { erasure: true, injection: true, paging: true, feed: this.feedWatcher !== undefined, reconciliation: this.reconcileCfg !== undefined }, feedWiring: feed.mode, notes: feedNotes });
+    }
+    async tiers(policy, opts) {
+        if (opts.apply === true && this.audit === undefined)
+            throw new Error("tiers: apply requires an audit trail — no audit trail configured, and paging nobody can observe is silent state");
+        const rows = this.retriever.enumerate(opts.scope ?? composeScopes());
+        const accesses = new Map();
+        if (this.audit !== undefined) {
+            for (const e of this.audit.events()) {
+                if (e.kind !== "injection")
+                    continue;
+                for (const id of e.injected) {
+                    const cur = accesses.get(id) ?? { count: 0 };
+                    const last = e.atEpoch !== undefined && (cur.lastEpoch === undefined || e.atEpoch > cur.lastEpoch) ? e.atEpoch : cur.lastEpoch;
+                    accesses.set(id, { count: cur.count + 1, ...(last !== undefined ? { lastEpoch: last } : {}) });
+                }
+            }
+        }
+        const signals = rows.map((r) => {
+            const label = this.labelMap.get(r.cellId);
+            const parsed = label === undefined ? undefined : parseLabel(label);
+            return {
+                cellId: r.cellId,
+                ...(r.ingestEpoch > 0 ? { ingestEpoch: r.ingestEpoch } : {}),
+                salient: parsed !== undefined && (parsed.salienceFloor || parsed.decayExempt),
+                ...(this.audit !== undefined ? { accesses: accesses.get(r.cellId) ?? { count: 0 } } : {}),
+            };
+        });
+        let warm = new Set();
+        const extraNotes = [];
+        if (this.bodyStore !== undefined) {
+            try {
+                warm = new Set(await this.bodyStore.list());
+            }
+            catch (e) {
+                extraNotes.push(`at-rest store could not be listed (${e.message}): warm membership read as empty`);
+            }
+        }
+        else {
+            extraNotes.push("no body store: the warm tier is not configured; promotions to warm cannot be applied");
+        }
+        const hot = new Set(rows.filter((r) => this.bodies.has(r.cellId)).map((r) => r.cellId));
+        const base = planTiers(signals, { hot, warm }, policy, opts.nowEpoch, this.audit !== undefined);
+        const plan = extraNotes.length > 0 ? { ...base, notes: [...base.notes, ...extraNotes] } : base;
+        if (opts.apply !== true)
+            return plan;
+        const audit = this.audit;
+        let promoted = 0;
+        let evicted = 0;
+        let failed = 0;
+        const presence = async (id) => (this.bodyStore === undefined ? "absent" : await this.bodyStore.presence(id));
+        for (const a of plan.promotions) {
+            let ok = false;
+            try {
+                if (a.to === "hot")
+                    ok = (await this.bodies.fetchByIds([a.cellId])).length === 1 && this.bodies.has(a.cellId);
+                else if (this.persistent !== undefined)
+                    ok = (await this.persistent.fetchByIds([a.cellId])).length === 1 && (await presence(a.cellId)) === "present";
+            }
+            catch {
+                ok = false;
+            }
+            audit.recordPaging(a, ok ? "applied" : "failed", opts.nowEpoch);
+            if (ok)
+                promoted++;
+            else
+                failed++;
+        }
+        for (const a of plan.evictions) {
+            let ok = false;
+            try {
+                let before = await presence(a.cellId);
+                if (a.to === "warm" && a.from === "hot" && before === "absent" && this.persistent !== undefined) {
+                    const since = this.persistent.stamp();
+                    const resident = this.bodies.peek(a.cellId);
+                    if (resident !== undefined && (await this.persistent.persist(resident, since)) === "filled")
+                        before = await presence(a.cellId);
+                }
+                if (!(a.to === "warm" && before !== "present") && !(a.to === "cold" && before === "unknown")) {
+                    if (a.from === "hot")
+                        this.bodies.evict(a.cellId);
+                    if (a.to === "cold" && before === "present")
+                        await this.bodyStore?.delete(a.cellId);
+                    const after = await presence(a.cellId);
+                    ok = !this.bodies.has(a.cellId) && after === (a.to === "cold" ? "absent" : "present");
+                }
+            }
+            catch {
+                ok = false;
+            }
+            audit.recordPaging(a, ok ? "applied" : "failed", opts.nowEpoch);
+            if (ok)
+                evicted++;
+            else
+                failed++;
+        }
+        return { ...plan, applied: { promoted, evicted, failed } };
+    }
+    get bodyStats() {
+        const ram = this.bodies.stats;
+        if (this.persistent === undefined || this.bodyStore === undefined)
+            return { ram };
+        const store = this.bodyStore;
+        let ineligible = 0;
+        for (const id of this.labelMap.keys())
+            if (!store.accepts(id))
+                ineligible++;
+        return { ram, atRest: { ...this.persistent.stats, ineligible, live: this.labelMap.size } };
+    }
+    get buildStats() {
+        return this.warm.stats;
+    }
+    get rerankStats() {
+        return this.rerankRetriever
+            ? { enabled: true, ...this.rerankRetriever.stats }
+            : { enabled: false, attempts: 0, fallbacks: 0 };
+    }
+    get threadStats() {
+        return this.threadRetriever
+            ? { enabled: true, ...this.threadRetriever.stats }
+            : { enabled: false, attempts: 0, threadsJoined: 0, demoted: 0, stampsResolved: 0, config: null };
+    }
+    async checkErasures() {
+        const all = [];
+        const MAX_PASSES = 32;
+        for (let pass = 0; pass < MAX_PASSES; pass++) {
+            const erased = await this.detector.checkOnce();
+            if (erased.length === 0)
+                return all;
+            all.push(...erased);
+        }
+        throw new Error(`checkErasures: still detecting erasures after ${MAX_PASSES} passes (${all.length} so far) — a listener keeps erasing; refusing to report a non-quiescent index as checked`);
+    }
+    watch(opts) {
+        this.watcher?.close();
+        const cfg = { dir: opts.dir };
+        if (opts.filename !== undefined)
+            cfg.filename = opts.filename;
+        if (opts.debounceMs !== undefined)
+            cfg.debounceMs = opts.debounceMs;
+        if (opts.pollMs !== undefined)
+            cfg.pollMs = opts.pollMs;
+        if (opts.onError !== undefined)
+            cfg.onError = opts.onError;
+        this.watcher = new IndexWatcher(cfg, () => this.checkErasures());
+        this.watcher.start();
+    }
+    _attachChangeFeed(follower, unwired) {
+        this.changeFollower = follower;
+        this.changeUnwired = unwired;
+    }
+    _attachOwnReads(own, off) {
+        this.ownReads = own;
+        this.ownReadsOff = off;
+    }
+    _attachWarmStart(wiring, off) {
+        this.warmStartWiring = wiring;
+        this.warmStartOff = off;
+    }
+    get warmStart() {
+        const w = this.warmStartWiring;
+        return w === undefined ? { mode: "not-wired", reason: this.warmStartOff } : { mode: "wired", restore: w.restore, lastTake: this.lastWarmTake };
+    }
+    async takeWarmStart() {
+        const w = this.warmStartWiring;
+        if (w === undefined)
+            return { ok: false, reason: `warm start is not wired: ${this.warmStartOff}` };
+        if (this.closed)
+            return { ok: false, reason: "the session is closed" };
+        const coversThrough = this.changeFollower?.appliedCursor() ?? null;
+        let bytes;
+        try {
+            bytes = encodeIndexPart(this.warm.currentRows(), this.warm.embeddingSpace);
+        }
+        catch (e) {
+            return { ok: false, reason: e instanceof IndexPartError ? `the index part could not be built: ${e.message}` : "the index part could not be built" };
+        }
+        const out = await takeSnapshot(w.client, { agentIdHash: w.identity, coversThrough, createdAt: new Date().toISOString(), parts: [{ name: INDEX_PART_NAME, bytes }] });
+        this.lastWarmTake = out;
+        return out;
+    }
+    get changeFeed() {
+        if (this.changeFollower === undefined)
+            return this.changeUnwired ?? { mode: "not-wired", reason: "no change feed follower" };
+        const by = this.ownReads?.stats;
+        const ownReads = by === undefined ? { mode: "by-label", reason: this.ownReadsOff } : by.stopped !== null ? { mode: "by-label", reason: by.stopped } : { mode: "by-id", ...by };
+        return { mode: "following", ownReads, ...this.changeFollower.status };
+    }
+    async syncChanges() {
+        if (this.changeFollower === undefined) {
+            const st = this.changeFeed;
+            throw new Error(`syncChanges: the change feed is ${st.mode}${st.mode === "not-wired" ? `: ${st.reason}` : ""}`);
+        }
+        await this.changeFollower.pull();
+    }
+    noteOwnWrite(receipt) {
+        this.changeFollower?.noteOwnWrite(receipt);
+    }
+    async _dropCachedBody(cellId, seq) {
+        this.ownReads?.supersede(cellId);
+        this.bodies.supersede(cellId, seq);
+        await this.persistent?.supersede(cellId, seq);
+    }
+    _attachWriterLocks(locks) {
+        this.writerLocks = locks;
+        if (locks !== undefined && this.reconcileCfg?.persisted === true) {
+            this.withheldGuard = locks.stateDirs.find((s) => s.holds.includes("withheld set"))?.lock ?? locks.index;
+        }
+    }
+    get writerLock() {
+        const l = this.writerLocks;
+        if (l !== undefined) {
+            const i = l.index;
+            return {
+                mode: "held", path: i.path, pid: i.holder.pid, host: i.holder.host, startedAt: i.holder.startedAt, sharedInProcess: i.sharedInProcess,
+                ...(l.stateDirs.length > 0 ? { stateDirs: l.stateDirs.map((s) => ({ path: s.lock.path, holds: s.holds, sharedInProcess: s.lock.sharedInProcess })) } : {}),
+            };
+        }
+        return this.writerLocksReleased ?? { mode: "opted-out" };
+    }
+    get erasureFeed() {
+        if (this.feedWatcher === undefined)
+            return this.feedUnwired ?? { mode: "not-wired", reason: "no feed watcher" };
+        return { mode: "watching", ...this.feedWatcher.status };
+    }
+    async checkFeed() {
+        if (this.feedWatcher === undefined) {
+            const st = this.erasureFeed;
+            throw new Error(`checkFeed: the erasure feed is ${st.mode}${st.mode === "not-wired" ? `: ${st.reason}` : ""}`);
+        }
+        return this.feedWatcher.runOnce();
+    }
+    get ingestStats() {
+        return this.warm.ingest;
+    }
+    get reconciliation() {
+        if (this.reconcileCfg === undefined)
+            return this.reconcileUnwired ?? { mode: "not-wired", reason: "no reconciliation configured" };
+        return {
+            mode: "configured", last: this.lastReconcile, withheld: [...this.withheldNow].sort(), persisted: this.reconcileCfg.persisted,
+            ...(this.withheldFault !== undefined ? { storeFault: this.withheldFault } : {}),
+            ...(this.withheldLoadFault !== undefined ? { loadFault: this.withheldLoadFault } : {}),
+            ...(this.withheldForeign !== undefined ? { foreignState: this.withheldForeign } : {}),
+        };
+    }
+    async release(cellId, reason) {
+        if (typeof cellId !== "string" || cellId.length === 0)
+            throw new TypeError("release: a cell id is required");
+        if (typeof reason !== "string" || reason.trim().length === 0)
+            throw new TypeError("release: a reason is required — the trail records who lifted a doubt and why");
+        if (this.reconcileCfg === undefined) {
+            const st = this.reconciliation;
+            throw new Error(`release: reconciliation is ${st.mode}${st.mode === "not-wired" ? `: ${st.reason}` : ""}`);
+        }
+        const run = this.reconcileChain.then(() => this.runRelease(cellId, reason.trim()));
+        this.reconcileChain = run.catch(() => { });
+        return run;
+    }
+    async runRelease(cellId, reason) {
+        if (!this.withheldNow.has(cellId)) {
+            this.audit?.recordRelease({ cellId, reason, outcome: "not-withheld" });
+            return { cellId, reason, outcome: "not-withheld" };
+        }
+        this.withheldNow.delete(cellId);
+        this.retriever.setWithheld(this.withheldNow);
+        const persisted = await this.persistWithheld();
+        const fault = this.withheldFault;
+        this.audit?.recordRelease({ cellId, reason, outcome: "released", persisted, ...(fault !== undefined ? { storeFault: fault } : {}) });
+        return { cellId, reason, outcome: "released", persisted, ...(fault !== undefined ? { fault } : {}) };
+    }
+    async persistWithheld() {
+        const cfg = this.reconcileCfg;
+        if (cfg === undefined)
+            return false;
+        if (this.closed) {
+            this.withheldFault = "the session is closed: no write lands after its writer locks go — this change is in memory only";
+            return false;
+        }
+        if (this.withheldGuard !== undefined && !this.withheldGuard.newestInProcess) {
+            this.withheldFault = "a newer session on this index holds the withheld set (the hot swap): this change is in memory only — make it on the newer session";
+            return false;
+        }
+        try {
+            const save = cfg.withheld.save([...this.withheldNow].sort());
+            this.withheldSaves.add(save);
+            try {
+                await save;
+            }
+            finally {
+                this.withheldSaves.delete(save);
+            }
+            this.withheldFault = undefined;
+            return cfg.persisted;
+        }
+        catch (e) {
+            this.withheldFault = `withheld store write failed: ${e instanceof Error ? e.message : String(e)} — doubts are per process until a write succeeds`;
+            return false;
+        }
+    }
+    async _loadWithheld() {
+        const cfg = this.reconcileCfg;
+        if (cfg === undefined)
+            return;
+        const file = cfg.withheld instanceof FileWithheldStore ? cfg.withheld : undefined;
+        if (file !== undefined && this.writerLocks === undefined) {
+            try {
+                await file.probeWritable();
+            }
+            catch (pe) {
+                this.withheldFault = `withheld store directory not writable at open: ${pe instanceof Error ? pe.message : String(pe)} — doubts are per process until a write succeeds`;
+            }
+        }
+        try {
+            const ids = await cfg.withheld.load();
+            const writtenBy = file?.lastLoadedOwner;
+            const self = file?.opts.owner;
+            const foreign = typeof writtenBy === "string" && self !== undefined && writtenBy !== self ? writtenBy : undefined;
+            const held = (ids ?? []).filter((id) => this.retriever.holds(id));
+            const dropped = (ids ?? []).length - held.length;
+            if (foreign !== undefined)
+                this.withheldForeign = { writtenBy: foreign, adopted: held.length, dropped };
+            if (ids !== undefined && ids.length > 0) {
+                this.withheldNow = new Set(held);
+                this.retriever.setWithheld(this.withheldNow);
+                if (dropped > 0) {
+                    this.withheldLoadNote =
+                        foreign !== undefined
+                            ? `${dropped} persisted doubt(s) were written by another index (${foreign}) and name rows this index does not hold: dropped — they were that index's doubts, not rows this index held; a state directory belongs to one deployment`
+                            : file !== undefined && writtenBy === null
+                                ? `${dropped} persisted doubt(s) name rows this index does not hold: dropped — the file names no owner (written by a previous release), so they may have been another index's doubts rather than this index's stale rows`
+                                : file === undefined
+                                    ? `${dropped} persisted doubt(s) name rows this index does not hold: dropped — the store records no writer, so whose doubts they were is unknown`
+                                    : `${dropped} persisted doubt(s) named rows this index no longer holds: dropped`;
+                }
+            }
+        }
+        catch (e) {
+            const why = e instanceof Error ? e.message : String(e);
+            let quarantined;
+            try {
+                quarantined = await cfg.withheld.quarantine?.();
+            }
+            catch (qe) {
+                quarantined = undefined;
+                this.withheldFault = `withheld store: the unreadable file could not be quarantined: ${qe instanceof Error ? qe.message : String(qe)}`;
+            }
+            this.withheldLoadFault = `withheld store unreadable at open: ${why} — every doubt held before this open is LOST${quarantined !== undefined ? ` (file moved to ${quarantined})` : ""}; every candidate is re-checked, and evidence re-raises a doubt only for a row still named as a candidate`;
+            this.withheldLoadFaultOnce = this.withheldLoadFault;
+            this.audit?.recordWithheldLost({ reason: this.withheldLoadFault, ...(quarantined !== undefined ? { quarantined } : {}) });
+        }
+    }
+    _onWithheldErased = async (cellId) => {
+        if (!this.withheldNow.delete(cellId))
+            return;
+        this.retriever.setWithheld(this.withheldNow);
+        const persisted = await this.persistWithheld();
+        this.audit?.recordWithheldErased({ cellId, persisted, ...(this.withheldFault !== undefined ? { storeFault: this.withheldFault } : {}) });
+    };
+    async reconcile() {
+        if (this.reconcileCfg === undefined) {
+            const st = this.reconciliation;
+            throw new Error(`reconcile: reconciliation is ${st.mode}${st.mode === "not-wired" ? `: ${st.reason}` : ""}`);
+        }
+        const cfg = this.reconcileCfg;
+        const run = this.reconcileChain.then(() => this.runReconcile(cfg));
+        this.reconcileChain = run.catch(() => { });
+        return run;
+    }
+    async runReconcile(cfg) {
+        const listedCandidates = await cfg.candidates();
+        const seenIds = new Set();
+        const all = listedCandidates.filter((c) => (seenIds.has(c.cellId) ? false : (seenIds.add(c.cellId), true)));
+        const held = all.filter((c) => this.retriever.holds(c.cellId));
+        const notes = [];
+        if (all.length < listedCandidates.length)
+            notes.push(`${listedCandidates.length - all.length} duplicate candidate(s) ignored (first occurrence kept)`);
+        if (held.length < all.length)
+            notes.push(`${all.length - held.length} candidate(s) name rows this index does not hold: skipped`);
+        let method = "none";
+        const decisions = [];
+        let deferred = 0;
+        let entries;
+        try {
+            const listed = await cfg.substrate.readIndex();
+            entries = new Map(listed.map((e) => [e.cellId.toLowerCase(), e]));
+        }
+        catch {
+            entries = undefined;
+        }
+        let listingComplete = false;
+        if (entries === undefined && cfg.listing && cfg.substrate.listVersionsPage !== undefined) {
+            const substrate = cfg.substrate;
+            const listing = await collectListing((after) => substrate.listVersionsPage(after));
+            if (listing.complete) {
+                listingComplete = true;
+                method = "listing";
+                for (const c of held)
+                    decisions.push(decideFromListing(c, listing));
+            }
+            else {
+                notes.push(`the version listing was incomplete (${listing.incompleteReason ?? "no reason given"}): probed instead; it ends nothing`);
+            }
+        }
+        if (entries !== undefined) {
+            method = "index";
+            for (const c of held)
+                decisions.push(decideFromIndex(c, entries));
+        }
+        else if (!listingComplete) {
+            method = "recall";
+            const probed = held.slice(0, Math.max(0, cfg.maxProbes));
+            deferred = held.length - probed.length;
+            for (const c of probed) {
+                if (c.probe === undefined || c.probe.trim().length === 0) {
+                    decisions.push(decideFromProbe(c, undefined));
+                    continue;
+                }
+                let r;
+                try {
+                    if (cfg.substrate.recallByQueryWithMeta !== undefined) {
+                        const a = await cfg.substrate.recallByQueryWithMeta(c.probe);
+                        r = { ok: true, bodies: a.bodies, cap: cfg.recallCap, ...(a.servedBy !== undefined ? { servedBy: a.servedBy } : {}) };
+                    }
+                    else {
+                        r = { ok: true, bodies: await cfg.substrate.recallByQuery(c.probe), cap: cfg.recallCap };
+                    }
+                }
+                catch (e) {
+                    r = { ok: false, reason: e instanceof Error ? e.message : String(e) };
+                }
+                decisions.push(decideFromProbe(c, r));
+            }
+        }
+        const erased = decisions.filter((d) => d.verdict === "erased").map((d) => d.cellId);
+        const suspect = decisions.filter((d) => d.verdict === "suspect").map((d) => d.cellId);
+        const live = decisions.filter((d) => d.verdict === "live").map((d) => d.cellId);
+        const restored = live.filter((id) => this.withheldNow.has(id));
+        const next = new Set(this.withheldNow);
+        for (const id of live)
+            next.delete(id);
+        for (const id of erased)
+            next.delete(id);
+        for (const id of suspect)
+            next.add(id);
+        this.withheldNow = next;
+        this.retriever.setWithheld(next);
+        const persisted = await this.persistWithheld();
+        if (erased.length > 0)
+            await this.bus.publish(erased);
+        if (restored.length > 0)
+            notes.push(`${restored.length} withheld row(s) RESTORED: found again on the substrate`);
+        let loadFault;
+        let loadNote;
+        if (this.withheldLoadFaultOnce !== undefined) {
+            loadFault = this.withheldLoadFaultOnce;
+            notes.push(loadFault);
+            this.withheldLoadFaultOnce = undefined;
+        }
+        if (this.withheldLoadNote !== undefined) {
+            loadNote = this.withheldLoadNote;
+            notes.push(loadNote);
+            this.withheldLoadNote = undefined;
+        }
+        const storeFault = this.withheldFault;
+        if (!persisted && cfg.persisted && storeFault !== undefined)
+            notes.push(storeFault);
+        const summary = summarize(method, decisions, deferred, notes);
+        this.audit?.recordReconcile({ method, checked: summary.checked, live: summary.live, erased, suspect, restored, unverifiable: summary.unverifiable, deferred, withheld: [...this.withheldNow].sort(), persisted, ...(storeFault !== undefined ? { storeFault } : {}), ...(loadFault !== undefined ? { loadFault } : {}), ...(loadNote !== undefined ? { loadNote } : {}) });
+        this.lastReconcile = summary;
+        return summary;
+    }
+    async flush() {
+        await this.warm.flush();
+    }
+    async close() {
+        this.retriever.fence();
+        this.bodies.fence();
+        const indexWatcher = this.watcher;
+        indexWatcher?.close();
+        this.watcher = undefined;
+        this.feedWatcher?.close();
+        this.changeFollower?.close();
+        await this.changeFollower?.settled();
+        await this.feedWatcher?.settled();
+        await indexWatcher?.settled();
+        for (let chain = this.reconcileChain;; chain = this.reconcileChain) {
+            await chain;
+            if (chain === this.reconcileChain)
+                break;
+        }
+        this.closed = true;
+        await Promise.allSettled([...this.withheldSaves]);
+        await this.warm.flush();
+        const l = this.writerLocks;
+        if (l !== undefined) {
+            this.writerLocks = undefined;
+            this.writerLocksReleased = { mode: "released", path: l.index.path, ...(l.stateDirs.length > 0 ? { stateDirs: l.stateDirs.map((s) => ({ path: s.lock.path, holds: s.holds })) } : {}) };
+            await releaseLocks(l);
+        }
+    }
+}
+export async function openMemorySession(opts) {
+    const entitlement = await checkEntitlement(entitlementSource(opts), opts.entitlementTimeoutMs !== undefined ? { timeoutMs: opts.entitlementTimeoutMs } : {});
+    const plan = planStateFiles(opts);
+    if (opts.writerLock === false)
+        return openMemorySessionLocked(opts, plan, undefined, entitlement);
+    const indexDir = await canonicalLockDir(opts.store.dir);
+    const locks = { index: await acquireWriterLock(opts.store.dir, { owner: indexDir }), stateDirs: [] };
+    try {
+        for (const g of await stateDirsOutside(plan, indexDir))
+            locks.stateDirs.push({ lock: await acquireWriterLock(g.dir, { owner: indexDir }), holds: g.holds });
+        return await openMemorySessionLocked(opts, plan, locks, entitlement);
+    }
+    catch (e) {
+        await releaseLocks(locks);
+        throw e;
+    }
+}
+function entitlementSource(opts) {
+    if (opts.entitlement !== undefined)
+        return opts.entitlement;
+    const port = opts.port;
+    return typeof port.status === "function" ? opts.port : undefined;
+}
+async function releaseLocks(l) {
+    for (const s of [...l.stateDirs].reverse())
+        await s.lock.release();
+    await l.index.release();
+}
+function ownCellEventsAdvertised(entitlement) {
+    const events = parseServerFeatures(entitlement.status ?? {}).events;
+    return events.kind === "available" && events.value.ownCellEvents;
+}
+function ownReadsPlan(opts, entitlement) {
+    const cf = opts.changeFeed;
+    if (cf === undefined || cf === false)
+        return { reason: "no change feed: only a cell the feed announces is read by id" };
+    if (cf.ownReads === false)
+        return { reason: "opted out (changeFeed.ownReads: false)" };
+    const port = opts.port;
+    if (port.recallOwn === undefined)
+        return { reason: "the port offers no read by id (recallOwn)" };
+    if (cf.ownReads !== true && !ownCellEventsAdvertised(entitlement)) {
+        return { reason: "own-cell events are not advertised: reads by id run only where the server advertises them" };
+    }
+    return { reader: { recallOwn: (cellId) => port.recallOwn(cellId) } };
+}
+async function restoreIndexRows(ws, store, space, identity) {
+    let local;
+    try {
+        local = await store.load(space);
+    }
+    catch {
+        return { outcome: "cold", reason: "the local index could not be read (its key): the build decides" };
+    }
+    if (local.state === "loaded")
+        return { outcome: "skipped", reason: "a local index for this embedding space is present" };
+    const r = await restoreOrCold(ws, { agentIdHash: identity });
+    if (r.mode === "cold")
+        return { outcome: "cold", reason: r.reason };
+    const part = r.parts.get(INDEX_PART_NAME);
+    if (part === undefined)
+        return { outcome: "cold", reason: `the snapshot carries no ${INDEX_PART_NAME} part` };
+    const d = decodeIndexPart(part, space);
+    if (!d.ok)
+        return { outcome: "cold", reason: `the snapshot's index part did not verify: ${d.reason}` };
+    try {
+        await store.save(d.rows, space);
+    }
+    catch {
+        return { outcome: "cold", reason: "the restored rows could not be written to the local index" };
+    }
+    return { outcome: "restored", snapshotId: r.snapshotId, coversThrough: r.coversThrough, rows: d.rows.length };
+}
+function reconcileSubstrate(r, port) {
+    const substrate = r.substrate ?? (port instanceof FederatedReadPort ? undefined : port);
+    if (substrate === undefined)
+        return { reason: "the session's port is a federation (tagged ids, a union index) — pass reconcile.substrate: the raw substrate port" };
+    if (substrate instanceof FederatedReadPort)
+        return { reason: "reconcile.substrate is a FederatedReadPort — its ids are tagged and its index is a union, so neither speaks for the substrate; pass the raw substrate port" };
+    return { substrate };
+}
+function planStateFiles(opts) {
+    const tenantId = opts.tenantId ?? opts.store.tenantId;
+    let feedCursor;
+    if (opts.erasureFeed !== false) {
+        const fo = opts.erasureFeed ?? {};
+        if (fo.path !== undefined || (opts.agentIdHash ?? opts.port.agentIdHash) !== undefined) {
+            feedCursor = joinPath(fo.stateDir ?? opts.store.dir, `erasure-feed.cursor.${tenantId}.json`);
+        }
+    }
+    let withheld;
+    if (opts.reconcile !== undefined && opts.reconcile !== false && opts.reconcile.withheld === undefined && "substrate" in reconcileSubstrate(opts.reconcile, opts.port)) {
+        withheld = joinPath(opts.reconcile.stateDir ?? opts.store.dir, `reconcile.withheld.${tenantId}.json`);
+    }
+    return { ...(feedCursor !== undefined ? { feedCursor } : {}), ...(withheld !== undefined ? { withheld } : {}) };
+}
+async function stateDirsOutside(plan, indexDir) {
+    const out = [];
+    const roles = [["erasure-feed cursor", plan.feedCursor], ["withheld set", plan.withheld]];
+    for (const [role, file] of roles) {
+        if (file === undefined)
+            continue;
+        const dir = await canonicalLockDir(dirname(file));
+        if (dir === indexDir)
+            continue;
+        const same = out.find((g) => g.dir === dir);
+        if (same !== undefined)
+            same.holds.push(role);
+        else
+            out.push({ dir, holds: [role] });
+    }
+    return out;
+}
+function planned(path, what) {
+    if (path === undefined)
+        throw new Error(`openMemorySession: internal — the lock plan does not cover the ${what} this wiring is about to write`);
+    return path;
+}
+async function openMemorySessionLocked(opts, plan, locks, entitlement) {
+    const tenantId = opts.tenantId ?? opts.store.tenantId;
+    const raw = await opts.port.readIndex();
+    const exclude = new Set(opts.excludeNamespaces ?? []);
+    const entries = exclude.size === 0 ? raw : raw.filter((e) => !exclude.has(parseLabel(e.label).namespace));
+    const warmOpts = { tenantId };
+    if (opts.rrf !== undefined)
+        warmOpts.rrf = opts.rrf;
+    if (opts.port instanceof FederatedReadPort)
+        warmOpts.namespaceSeparator = opts.port.separator;
+    const warmStartIdentity = opts.agentIdHash ?? opts.port.agentIdHash;
+    const warmStartPlan = opts.warmStart === undefined
+        ? { reason: "not requested — pass warmStart (a snapshot client) to restore and take snapshots" }
+        : warmStartIdentity === undefined || !/^[0-9a-f]{64}$/.test(warmStartIdentity)
+            ? { reason: "identity unknown — pass agentIdHash (or a port that carries it): a snapshot belongs to one identity" }
+            : { identity: warmStartIdentity, restore: await restoreIndexRows(opts.warmStart, opts.store, { modelId: opts.embedder.modelId, dim: opts.embedder.dim }, warmStartIdentity) };
+    const warm = await buildWarmIndex(entries, opts.embedder, opts.store, warmOpts);
+    const source = new SaihmBodySource(opts.port, opts.bodyConfig ?? {});
+    const ownPlan = ownReadsPlan(opts, entitlement);
+    const byId = "reader" in ownPlan ? new OwnCellBodySource(source, ownPlan.reader) : undefined;
+    const live = byId ?? source;
+    const tierLatency = opts.tierLatency;
+    const record = (tier, ms) => tierLatency?.record(tier, ms);
+    const persistent = opts.bodyStore
+        ? new PersistentBodySource(live, opts.bodyStore, tierLatency !== undefined ? { onServed: (step, ms) => record(step === "own" ? "warm" : "cold", ms) } : {})
+        : undefined;
+    const auditTrail = opts.audit;
+    const bodies = new CachingBodySource(persistent ?? live, {
+        ...DEFAULT_CACHE_CONFIG,
+        ...(tierLatency !== undefined
+            ? {
+                onServed: (step, ms) => {
+                    if (step === "own")
+                        record("hot", ms);
+                    else if (persistent === undefined)
+                        record("cold", ms);
+                },
+            }
+            : {}),
+        ...(auditTrail !== undefined
+            ? {
+                onEvict: (cellId) => {
+                    const at = opts.bodyStore?.presenceSync(cellId) ?? "absent";
+                    auditTrail.recordPaging({
+                        cellId,
+                        from: "hot",
+                        to: at === "present" ? "warm" : "cold",
+                        reason: at === "unknown" ? "RAM cache capacity (LRU); the at-rest copy could not be checked" : "RAM cache capacity (LRU)",
+                    }, "applied");
+                },
+            }
+            : {}),
+    });
+    if (opts.bodyStore && persistent) {
+        const live = new Set(entries.filter((e) => !e.forgotten).map((e) => e.cellId));
+        let stored = [];
+        try {
+            stored = await opts.bodyStore.list();
+        }
+        catch {
+            stored = [];
+        }
+        for (const id of stored) {
+            if (live.has(id))
+                continue;
+            try {
+                await persistent.forget(id);
+            }
+            catch {
+            }
+        }
+    }
+    const bus = new ErasureBus();
+    bus.subscribe((cellId) => warm.onErased(cellId));
+    bus.subscribe(async (cellId) => {
+        await bodies.forget(cellId);
+        if (persistent)
+            await persistent.forget(cellId);
+        await source.forget(cellId);
+        byId?.forget(cellId);
+    });
+    const detector = new ErasureDetector(opts.port, bus);
+    detector.prime(entries);
+    let answerRetriever = warm.retriever;
+    const labelOf = new Map(entries.filter((e) => !e.forgotten).map((e) => [e.cellId, e.label]));
+    {
+        bus.subscribe((cellId) => {
+            labelOf.delete(cellId);
+        });
+    }
+    let stampOf;
+    if (opts.stampOf) {
+        stampOf = opts.stampOf;
+    }
+    else {
+        const stampMemo = new Map();
+        bus.subscribe((cellId) => {
+            stampMemo.delete(cellId);
+        });
+        stampOf = (id) => {
+            const hit = stampMemo.get(id);
+            if (hit !== undefined)
+                return hit;
+            const label = labelOf.get(id);
+            const stamp = label === undefined ? {} : parseLifecycle(label);
+            if (label !== undefined)
+                stampMemo.set(id, stamp);
+            return stamp;
+        };
+    }
+    const stackDeps = {
+        base: answerRetriever,
+        labelOf: (id) => labelOf.get(id),
+        bodies,
+        ...(opts.reranker !== undefined ? { reranker: opts.reranker } : {}),
+        stampOf,
+        ...(opts.onRerankFallback !== undefined ? { onRerankFallback: opts.onRerankFallback } : {}),
+    };
+    const stack = composeLeverStack(stackDeps, opts);
+    answerRetriever = stack.retriever;
+    const rerankRetriever = stack.rerankRetriever;
+    const threadRetriever = stack.threadRetriever;
+    let standingWiring;
+    if (opts.standingStore) {
+        const standingLabelOf = opts.standingLabelOf ?? ((id) => labelOf.get(id));
+        const index = new ContentFingerprintIndex(standingLabelOf, opts.standingBodies ? { bodies: opts.standingBodies } : {});
+        const store = opts.standingStore;
+        bus.subscribe(store.purge);
+        bus.subscribe((cellId) => index.forget(cellId));
+        standingWiring = { store, index, scope: opts.standingBodies ? "label+body" : "label" };
+    }
+    if (opts.derivedStore) {
+        const ds = opts.derivedStore;
+        const cascade = ds.cascade;
+        if (cascade !== undefined) {
+            bus.subscribe(async (cellId) => {
+                const report = await cascade(cellId);
+                if (report.forgotten.length > 0)
+                    await bus.publish(report.forgotten);
+            });
+        }
+        else
+            bus.subscribe(ds.onSourceErased);
+    }
+    if (opts.audit)
+        bus.subscribe(opts.audit.erasureListener());
+    const shared = opts.derivedLineage;
+    if (shared?.forget)
+        bus.subscribe((cellId) => shared.forget(cellId));
+    const own = opts.derivedStore;
+    const lineageLookup = (cellId) => own?.lineageOf?.(cellId) ?? shared?.lineageOf(cellId);
+    if (own?.retirements) {
+        const apply = () => warm.retriever.setRetirements(own.retirements());
+        apply();
+        bus.subscribe(() => apply());
+    }
+    if (opts.onErased !== undefined)
+        bus.subscribe(opts.onErased);
+    let feed;
+    let feedUnwired;
+    let feedPathWired;
+    let follower;
+    let lastFeedPoint;
+    if (opts.erasureFeed === false) {
+        feedUnwired = { mode: "opted-out" };
+    }
+    else {
+        const fo = opts.erasureFeed ?? {};
+        const identity = opts.agentIdHash ?? opts.port.agentIdHash;
+        if (identity !== undefined && !/^[0-9a-f]{64}$/.test(identity))
+            throw new Error("openMemorySession: agentIdHash must be a 64-hex agentIdHash");
+        let feedPath = fo.path;
+        if (feedPath === undefined) {
+            if (identity === undefined) {
+                feedUnwired = { mode: "not-wired", reason: "identity unknown — pass agentIdHash (or a port that carries it; a FederatedReadPort forwards the one identity its sources agree on) so the per-identity feed can be located, or erasureFeed: false to opt out explicitly" };
+            }
+            else {
+                feedPath = resolveFeedPath({ identity, env: fo.env ?? process.env, homeDir: fo.homeDir ?? homedir() });
+            }
+        }
+        if (feedPath !== undefined) {
+            const trail = auditTrail;
+            const map = fo.mapCellId ?? ((id) => [id]);
+            feedPathWired = feedPath;
+            const sink = {
+                consume: async (batch) => {
+                    const ids = [...new Set(batch.flatMap((b) => map(b.line.cellId)))];
+                    if (ids.length > 0)
+                        await bus.publish(ids);
+                    if (trail !== undefined)
+                        for (const b of batch)
+                            trail.recordFeed(b);
+                    if (follower !== undefined)
+                        for (const b of batch)
+                            follower.erased(b.line.cellId);
+                },
+                progressed: (point) => {
+                    lastFeedPoint = point;
+                    follower?.erasureProgress(point);
+                },
+                ...(trail !== undefined ? { fault: (f) => trail.recordFeedFault(f) } : {}),
+            };
+            feed = new FeedWatcher({
+                path: feedPath,
+                ...(identity !== undefined ? { agentIdHash: identity } : {}),
+                cursor: new FileFeedCursorStore(planned(plan.feedCursor, "erasure-feed cursor")),
+                ...(fo.pollMs !== undefined ? { pollMs: fo.pollMs } : {}),
+                ...(fo.onError !== undefined ? { onError: fo.onError } : {}),
+                ...(fo.now !== undefined ? { now: fo.now } : {}),
+                ...(fo.watch !== undefined ? { watch: fo.watch } : {}),
+            }, sink);
+            await feed.load();
+            const consumedBefore = trail !== undefined ? await feed.consumedLines() : [];
+            await feed.start();
+            if (trail !== undefined) {
+                const live = new Set(entries.filter((e) => !e.forgotten).map((e) => e.cellId));
+                for (const l of consumedBefore)
+                    if (map(l.cellId).some((id) => live.has(id)))
+                        trail.recordFeedLive(l.cellId);
+            }
+        }
+    }
+    let reconcileCfg;
+    let reconcileUnwired;
+    if (opts.reconcile === false) {
+        reconcileUnwired = { mode: "opted-out" };
+    }
+    else if (opts.reconcile === undefined) {
+        reconcileUnwired = { mode: "not-wired", reason: "no candidates named — pass reconcile: { candidates, substrate } to reconcile copied rows against the substrate, or reconcile: false to opt out explicitly" };
+    }
+    else {
+        const wiring = reconcileSubstrate(opts.reconcile, opts.port);
+        if (!("substrate" in wiring)) {
+            reconcileUnwired = { mode: "not-wired", reason: wiring.reason };
+        }
+        else {
+            const substrate = wiring.substrate;
+            const withheld = opts.reconcile.withheld ?? new FileWithheldStore(planned(plan.withheld, "withheld set"), { owner: locks?.index.dir ?? (await canonicalLockDir(opts.store.dir)) });
+            reconcileCfg = {
+                candidates: opts.reconcile.candidates, substrate, atOpen: opts.reconcile.atOpen ?? true, maxProbes: opts.reconcile.maxProbes ?? 25, recallCap: opts.reconcile.recallCap ?? 200,
+                listing: opts.reconcile.listing ?? (substrate.listVersionsPage !== undefined && ownCellEventsAdvertised(entitlement)),
+                withheld, persisted: !(withheld instanceof MemoryWithheldStore),
+            };
+        }
+    }
+    const session = MemorySession._create(warm.retriever, bodies, answerRetriever, bus, detector, warm, opts.port, persistent, opts.bodyStore, rerankRetriever, threadRetriever, standingWiring, labelOf, stampOf, lineageLookup, opts.embedder, opts.audit, feed, feedUnwired, reconcileCfg, reconcileUnwired);
+    session._attachWriterLocks(locks);
+    session._attachOwnReads(byId, "reason" in ownPlan ? ownPlan.reason : "");
+    session._attachWarmStart(opts.warmStart !== undefined && "identity" in warmStartPlan ? { client: opts.warmStart, ...warmStartPlan } : undefined, "reason" in warmStartPlan ? warmStartPlan.reason : "");
+    const changeIdentity = opts.agentIdHash ?? opts.port.agentIdHash;
+    if (opts.changeFeed === undefined || opts.changeFeed === false) {
+        session._attachChangeFeed(undefined, { mode: "not-wired", reason: opts.changeFeed === false ? "opted out" : "not requested — pass changeFeed: {} to follow the identity's change feed" });
+    }
+    else if (changeIdentity === undefined || !/^[0-9a-f]{64}$/.test(changeIdentity)) {
+        session._attachChangeFeed(undefined, { mode: "not-wired", reason: "identity unknown — pass agentIdHash (or a port that carries it) so the per-identity change feed can be located" });
+    }
+    else {
+        const co = opts.changeFeed;
+        const changesPath = co.path ?? resolveChangesPath({ identity: changeIdentity, env: co.env ?? process.env, homeDir: co.homeDir ?? homedir() });
+        const map = (opts.erasureFeed !== false ? opts.erasureFeed?.mapCellId : undefined) ?? ((id) => [id]);
+        follower = new ChangeFeedFollower({
+            path: changesPath,
+            erasurePath: feedPathWired ?? joinPath(dirname(changesPath), "erasures.ndjson"),
+            agentIdHash: changeIdentity,
+            ...(co.pollMs !== undefined ? { pollMs: co.pollMs } : {}),
+            ...(co.livenessMs !== undefined ? { livenessMs: co.livenessMs } : {}),
+            ...(co.reconcileRetryMs !== undefined ? { reconcileRetryMs: co.reconcileRetryMs } : {}),
+            ...(co.now !== undefined ? { now: co.now } : {}),
+            ...(co.onError !== undefined ? { onError: co.onError } : {}),
+            ...(co.timer !== undefined ? { timer: co.timer } : {}),
+        }, {
+            invalidate: async (cellId, version) => {
+                for (const id of map(cellId))
+                    await session._dropCachedBody(id, version.seq);
+            },
+            ...(co.onChanged !== undefined ? { onChanged: co.onChanged } : {}),
+            ...(reconcileCfg !== undefined ? { reconcileByListing: async () => (await session.reconcile()).method === "listing" } : {}),
+        });
+        session._attachChangeFeed(follower, undefined);
+        if (lastFeedPoint !== undefined)
+            follower.erasureProgress(lastFeedPoint);
+    }
+    if (reconcileCfg !== undefined) {
+        bus.subscribe(session._onWithheldErased);
+        await session._loadWithheld();
+        if (reconcileCfg.atOpen && follower === undefined)
+            await session.reconcile();
+    }
+    if (follower !== undefined) {
+        try {
+            await follower.start();
+        }
+        catch (e) {
+            await session.close();
+            throw e;
+        }
+    }
+    return session;
+}
+//# sourceMappingURL=memory_session.js.map