@fgv/ts-agent-memory 5.1.0-36

package/dist/packlets/store/fileTreeMemoryStore.js

@@ -0,0 +1,698 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { Hash, Logging, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { DEFAULT_DEDUP_SCOPE, KnowledgeLwwPolicy } from '../types';
+import { parseMemoryFile, serializeMemoryFile } from '../converters';
+import { MemoryIndex } from '../index';
+import { defaultMemoryScopeEncoding } from './scopeEncoding';
+/** The on-disk extension for a memory record file. */
+const MEMORY_FILE_EXTENSION = '.md';
+/**
+ * Flat-layout, FileTree-backed {@link IMemoryStore}. The FileTree is the source
+ * of truth; the {@link IMemoryIndex} is a derived in-memory view patched on
+ * every write. Concurrent writes are serialized through a per-instance async
+ * write-lock so the index and the on-disk files never interleave.
+ *
+ * @remarks
+ * B1 supports flat (non-versioned) layout only and string (markdown) bodies.
+ * A codec reporting `isVersioned: true`, or a non-string body, fails loudly —
+ * the versioned/temporal write path is a fast-follow.
+ * @public
+ */
+export class FileTreeMemoryStore {
+    constructor(params) {
+        this._root = params.root;
+        this._registry = params.registry;
+        this._writePolicies = params.writePolicies;
+        this._codecs = params.codecs;
+        this._defaultCodec = params.defaultCodec;
+        this._defaultPolicy = params.defaultPolicy;
+        this._scopeEncoding = params.scopeEncoding;
+        this._clock = params.clock;
+        this._index = params.index;
+        this._hasher = new Hash.Crc32Normalizer();
+        this._observers = params.observers;
+        this._logger = params.logger;
+        this._vectorIndex = params.vectorIndex;
+        this._embed = params.embed;
+        this._seq = 0;
+        this._observationSeq = 0;
+        this._writeTail = Promise.resolve();
+    }
+    /**
+     * Family-convention factory. Builds the derived index and a default LWW
+     * policy, then performs an initial FileTree walk so an existing vault is
+     * indexed (and the `seq` counter resumes past the highest persisted `seq`).
+     */
+    static create(params) {
+        return KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => MemoryIndex.create().onSuccess((index) => {
+            var _a, _b, _c, _d, _e, _f;
+            const store = new FileTreeMemoryStore({
+                root: params.root,
+                registry: params.registry,
+                writePolicies: (_a = params.writePolicies) !== null && _a !== void 0 ? _a : new Map(),
+                codecs: (_b = params.codecs) !== null && _b !== void 0 ? _b : new Map(),
+                defaultCodec: params.defaultCodec,
+                defaultPolicy,
+                scopeEncoding: (_c = params.scopeEncoding) !== null && _c !== void 0 ? _c : defaultMemoryScopeEncoding,
+                clock: (_d = params.clock) !== null && _d !== void 0 ? _d : Date.now,
+                index,
+                observers: (_e = params.observers) !== null && _e !== void 0 ? _e : [],
+                logger: (_f = params.logger) !== null && _f !== void 0 ? _f : new Logging.NoOpLogger(),
+                vectorIndex: params.vectorIndex,
+                embed: params.embed
+            });
+            return store._initialIndex().onSuccess(() => succeed(store));
+        }));
+    }
+    /** {@inheritDoc IMemoryStore.get} */
+    async get(kind, entityId) {
+        var _a;
+        const result = this._codecFor(kind).onSuccess((codec) => codec.encode(entityId).onSuccess((addr) => {
+            if (addr.isVersioned) {
+                return fail(`memory get '${entityId}': versioned/temporal layout not yet supported`);
+            }
+            return this._readRecord(addr.scope, addr.idStem);
+        }));
+        await this._fireObservation('read', kind, entityId, {
+            outcome: result.isSuccess() ? 'success' : 'failure',
+            id: result.isSuccess() ? (_a = result.value) === null || _a === void 0 ? void 0 : _a.envelope.id : undefined,
+            error: result.isFailure() ? result.message : undefined
+        });
+        return result;
+    }
+    /** {@inheritDoc IMemoryStore.getById} */
+    async getById(scope, id) {
+        return this._readRecord(scope, id);
+    }
+    /** {@inheritDoc IMemoryStore.list} */
+    async list(filter) {
+        const matches = this._index
+            .entries()
+            .filter((entry) => {
+            if ((filter === null || filter === void 0 ? void 0 : filter.scope) !== undefined && entry.scope !== filter.scope) {
+                return false;
+            }
+            if ((filter === null || filter === void 0 ? void 0 : filter.kind) !== undefined && entry.record.envelope.kind !== filter.kind) {
+                return false;
+            }
+            if ((filter === null || filter === void 0 ? void 0 : filter.tag) !== undefined && !entry.record.envelope.tags.includes(filter.tag)) {
+                return false;
+            }
+            return true;
+        })
+            .map((entry) => entry.record);
+        return succeed(matches);
+    }
+    /** {@inheritDoc IMemoryStore.put} */
+    async put(record) {
+        const result = await this._enqueue(() => this._putLocked(record));
+        await this._fireObservation('write', record.envelope.kind, record.envelope.entityId, {
+            outcome: result.isSuccess() ? 'success' : 'failure',
+            id: result.isSuccess() ? result.value.record.envelope.id : record.envelope.id,
+            provenance: record.envelope.provenance,
+            error: result.isFailure() ? result.message : undefined
+        });
+        // Fire one `'delete'` observation per record evicted by cap-cull. The
+        // evicted records are always in the same `(scope, kind)` cohort as the
+        // incoming record, so resolving the scope from the incoming `entityId`
+        // yields the evicted record's scope; the observation records the evicted
+        // record's own `id`. A no-op / first-write / reject path yields no
+        // evictions, so this loop is empty there.
+        if (result.isSuccess()) {
+            for (const evictedId of result.value.evicted) {
+                await this._fireObservation('delete', record.envelope.kind, record.envelope.entityId, {
+                    outcome: 'success',
+                    id: evictedId
+                });
+            }
+        }
+        return result.onSuccess((outcome) => succeed(outcome.record));
+    }
+    /** {@inheritDoc IMemoryStore.delete} */
+    async delete(kind, entityId) {
+        const result = await this._enqueue(() => this._deleteLocked(kind, entityId));
+        await this._fireObservation('delete', kind, entityId, {
+            outcome: result.isSuccess() ? 'success' : 'failure',
+            id: result.isSuccess() ? result.value : undefined,
+            error: result.isFailure() ? result.message : undefined
+        });
+        return result;
+    }
+    /**
+     * Serialize a mutating task behind the write-lock. Tasks run in submission
+     * order; a failed task does not break the chain for subsequent ones.
+     */
+    _enqueue(task) {
+        const result = this._writeTail.then(task);
+        this._writeTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * Build and fan out one observation record for a completed op. A no-op when no
+     * observers are wired (the additive-default path pays nothing). The store is
+     * the seq authority — it mints `seq` / `timestamp` so every observer sees the
+     * same record. The scope is resolved best-effort via the codec.
+     */
+    async _fireObservation(phase, kind, entityId, details) {
+        if (this._observers.length === 0) {
+            return;
+        }
+        const record = {
+            seq: ++this._observationSeq,
+            timestamp: this._clock(),
+            phase,
+            scope: this._scopeBestEffort(kind, entityId),
+            id: details.id,
+            kind,
+            outcome: details.outcome,
+            error: details.error,
+            provenance: details.provenance
+        };
+        const awaited = [];
+        for (const observer of this._observers) {
+            if (observer.fireAndForget === true) {
+                // Intentionally not awaited: a fire-and-forget observer must not extend
+                // the store op's latency. `_safeObserve` swallows internally; the
+                // `.catch` keeps the detached promise from being flagged as floating.
+                this._safeObserve(observer, record).catch(() => undefined);
+            }
+            else {
+                awaited.push(this._safeObserve(observer, record));
+            }
+        }
+        await Promise.all(awaited);
+    }
+    /** Invoke one observer, swallowing any failure or throw (logged at `warn`). */
+    async _safeObserve(observer, record) {
+        try {
+            const observed = await observer.observe(record);
+            if (observed.isFailure()) {
+                this._warnSwallowed(`memory observer failed (swallowed): ${observed.message}`);
+            }
+        }
+        catch (error) {
+            this._warnSwallowed(`memory observer threw (swallowed): ${String(error)}`);
+        }
+    }
+    /**
+     * Log a swallowed-issue warning (observer failure or best-effort vector
+     * maintenance), tolerating a logger that itself throws — diagnostic logging
+     * must never make a store op reject.
+     */
+    _warnSwallowed(message) {
+        try {
+            this._logger.warn(message);
+        }
+        catch (_a) {
+            // Diagnostic logging must not affect the store operation.
+        }
+    }
+    /** Resolve a scope for an observation, best-effort (undefined when unresolvable). */
+    _scopeBestEffort(kind, entityId) {
+        return this._codecFor(kind)
+            .onSuccess((codec) => codec.encode(entityId))
+            .onSuccess((addr) => succeed(addr.scope))
+            .orDefault();
+    }
+    async _putLocked(record) {
+        const envelope = record.envelope;
+        if (typeof record.body !== 'string') {
+            return fail(`memory put '${envelope.id}': only string (markdown) bodies are supported (got ${typeof record.body})`);
+        }
+        const body = record.body;
+        // Resolve the synchronous prefix (body validation → codec address → content
+        // hash) into a small descriptor, then bridge to the async write tail (which
+        // embeds on write). Keeping the sync prefix intact preserves the exact
+        // dedup/policy ordering of the original; only the embed step is new.
+        return this._registry
+            .convert(envelope.kind, body)
+            .withErrorFormat((msg) => `memory put '${envelope.id}': invalid body: ${msg}`)
+            .onSuccess(() => this._codecFor(envelope.kind))
+            .onSuccess((codec) => codec.encode(envelope.entityId).onSuccess((addr) => {
+            if (addr.isVersioned) {
+                return fail(`memory put '${envelope.entityId}': versioned/temporal layout not yet supported`);
+            }
+            if (envelope.id !== addr.idStem) {
+                return fail(`memory put: envelope id '${envelope.id}' does not match codec-derived stem '${addr.idStem}'`);
+            }
+            return this._contentHash(envelope.kind, body, envelope.links).onSuccess((hash) => succeed({ scope: addr.scope, idStem: addr.idStem, hash }));
+        }))
+            .thenOnSuccess((resolved) => this._writeResolved(record, body, resolved.scope, resolved.idStem, resolved.hash));
+    }
+    /**
+     * Run dedup → policy → stamp → embed → write for a resolved address and content
+     * hash. Async because the embed-on-write hook (when wired) does a network call
+     * or in-process inference; the whole chain runs inside the write-lock so the
+     * vector index, the on-disk file, and the derived index never interleave.
+     */
+    async _writeResolved(record, body, scope, idStem, hash) {
+        var _a;
+        const policy = this._policyFor(record.envelope.kind);
+        const dedupScope = (_a = policy.dedupScope) !== null && _a !== void 0 ? _a : DEFAULT_DEDUP_SCOPE;
+        // Content-hash dedup runs BEFORE policy. Its granularity is the kind's
+        // `dedupScope`:
+        //   - 'content': an identical { kind, body, links } triple ANYWHERE in the
+        //     scope (even under a different id) is a no-op (knowledge family).
+        //   - 'entity' (default): only an identical re-put of the SAME id is a no-op;
+        //     two distinct entities with identical content never collapse (experience
+        //     families). The same-id check is folded into the `_readRecord` below.
+        // (Tags / provenance are metadata and are NOT part of the hash; see
+        // design-lock §2.5.)
+        if (dedupScope === 'content') {
+            const duplicate = this._findByContentHash(scope, hash);
+            if (duplicate !== undefined) {
+                return succeed({ record: duplicate, evicted: [] });
+            }
+        }
+        return this._readRecord(scope, idStem).thenOnSuccess((existing) => {
+            if (dedupScope === 'entity' && existing !== undefined && existing.envelope.contentHash === hash) {
+                // Entity-scoped dedup: an identical re-put of the same entity is a no-op.
+                return Promise.resolve(succeed({ record: existing, evicted: [] }));
+            }
+            // The admission cohort is the set of records the policy's cap applies to:
+            // every record in this scope of this kind EXCEPT the target id. On a first
+            // write the post-write count is `cohort.length + 1`; on an update the prior
+            // same-id record is excluded so the count is still `cohort.length + 1`
+            // (a replace, not a grow). The same-id `existing` record is threaded
+            // separately into `_buildRecord` for the merge-patch. Knowledge LWW ignores
+            // this argument, so its behavior is unchanged by the wider cohort.
+            const cohort = this._admissionCohort(scope, record.envelope.kind, idStem);
+            return policy
+                .admit(record, cohort)
+                .thenOnSuccess((decision) => this._admitWrite(record, body, scope, idStem, hash, policy, existing, decision));
+        });
+    }
+    /**
+     * Build → embed → persist → evict for an admitted write.
+     *
+     * The durable record store is authoritative; the vector index is a **derived,
+     * rebuildable** view, so vector maintenance is **best-effort** — a failed embed
+     * or `add` is logged and the durable write still succeeds (the index can be
+     * rebuilt via {@link InMemoryCosineIndex.rebuild}). Only genuine record-store
+     * failures (body/codec/policy, persist, file eviction) fail the `put`.
+     *
+     * Ordering: the embed + `add` run immediately before the single `_persist` so
+     * the index-returned `embeddingRef` lands in one durable write (a post-persist
+     * stamp would need a second write whose failure path is effectively untestable).
+     * Build and persist the replacement BEFORE evicting the cull-oldest cohort, so a
+     * later eviction failure never loses data with nothing written in its place.
+     */
+    async _admitWrite(record, body, scope, idStem, hash, policy, existing, decision) {
+        if (decision.decision === 'reject') {
+            return fail(`memory put: rejected by policy: ${decision.reason}`);
+        }
+        return this._buildRecord(record, body, existing, policy, hash)
+            .thenOnSuccess((built) => this._embedOnWrite(built))
+            .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
+            .thenOnSuccess(async (persisted) => {
+            // Everything after the authoritative `_persist` commit is best-effort and
+            // never turns a committed write into a `Failure`:
+            //   - a cull-oldest eviction that fails is logged (the per-(scope,kind)
+            //     cap may be transiently exceeded; the next write's admission restores
+            //     it), and only the successfully-evicted ids flow onward;
+            //   - vector pruning of the evicted cohort is likewise best-effort.
+            const evicted = this._applyEvictions(decision, scope);
+            await this._removeEvictedVectors(evicted);
+            return succeed({ record: persisted, evicted });
+        });
+    }
+    /**
+     * Best-effort embed-on-write. When a vector index AND an embedder are wired,
+     * embeds the built record, `add`s the vector (replace semantics handle a same-id
+     * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A
+     * failure (returned `fail` OR a thrown/rejected hook) is logged and the
+     * unembedded record is returned unchanged — the put still persists, and the
+     * derived index is reconciled by a later `rebuild`. A pass-through no-op when
+     * unwired (byte-identical record).
+     *
+     * Always succeeds (`Result` is the chain's shape, never a vector-induced
+     * failure).
+     */
+    async _embedOnWrite(built) {
+        if (this._vectorIndex === undefined || this._embed === undefined) {
+            return succeed(built);
+        }
+        const vectorIndex = this._vectorIndex;
+        const embed = this._embed;
+        const embedded = await this._tryVectorOp(() => embed(built), `embedding '${built.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return succeed(built);
+        }
+        const added = await this._tryVectorOp(() => vectorIndex.add(built.envelope.id, embedded.value), `vector add for '${built.envelope.id}'`);
+        if (added.isFailure()) {
+            return succeed(built);
+        }
+        return succeed({ envelope: Object.assign(Object.assign({}, built.envelope), { embeddingRef: added.value }), body: built.body });
+    }
+    /**
+     * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
+     * after the authoritative `_persist`, so a failed eviction is logged (never
+     * fatal) and the cap self-corrects on the next admission. Returns the ids that
+     * were actually evicted (so observations / vector pruning cover only those).
+     * `accept` / `reject` decisions evict nothing.
+     */
+    _applyEvictions(decision, scope) {
+        if (decision.decision !== 'cull-oldest') {
+            return [];
+        }
+        const evicted = [];
+        for (const id of decision.evict) {
+            const result = this._evict(scope, id);
+            if (result.isSuccess()) {
+                evicted.push(result.value);
+            }
+            else {
+                this._warnSwallowed(`memory put: best-effort eviction of '${id}' failed (cap may be transiently exceeded; restored on the next write): ${result.message}`);
+            }
+        }
+        return evicted;
+    }
+    /** Best-effort vector removal for each evicted record (never fails the put). */
+    async _removeEvictedVectors(evicted) {
+        for (const id of evicted) {
+            await this._removeVectorBestEffort(id);
+        }
+    }
+    /**
+     * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
+     * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds
+     * regardless, since the index is rebuildable.
+     */
+    async _tryVectorOp(op, label) {
+        let result;
+        try {
+            result = await op();
+        }
+        catch (err) {
+            result = fail(`${label} threw: ${String(err)}`);
+        }
+        if (result.isFailure()) {
+            this._warnSwallowed(`memory: ${label} failed (best-effort; vector index left for rebuild): ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * Best-effort vector removal. A no-op unless the full vector lifecycle is wired
+     * (both an index AND an embedder), so an unwired store does no vector work and
+     * behaves byte-identically. Failures are logged, never surfaced — a committed
+     * delete/eviction must not fail because a derived index could not be pruned.
+     */
+    async _removeVectorBestEffort(id) {
+        if (this._vectorIndex === undefined || this._embed === undefined) {
+            return;
+        }
+        const vectorIndex = this._vectorIndex;
+        await this._tryVectorOp(() => vectorIndex.remove(id), `vector removal for '${id}'`);
+    }
+    /**
+     * Build the record to persist. On a first write the incoming envelope is the
+     * base (final content equals the incoming content, so the dedup `hash` is
+     * reused). On an update the incoming record's mutable fields are projected into
+     * a merge-patch and the policy's `applyUpdate` merges them over the existing
+     * record (preserving `created`); the persisted body and `contentHash` are then
+     * taken from the policy's actual output, so a body-transforming policy is never
+     * bypassed and the stored hash always matches the stored `{ kind, body, links }`.
+     * The store stamps the transaction-time metadata it owns
+     * (`created` / `updated` / `seq` / `contentHash`).
+     */
+    _buildRecord(incoming, body, existing, policy, hash) {
+        const now = this._clock();
+        const seq = ++this._seq;
+        if (existing === undefined) {
+            return succeed({
+                envelope: Object.assign(Object.assign({}, incoming.envelope), { created: now, updated: now, seq, contentHash: hash }),
+                body
+            });
+        }
+        const patch = this._projectMutablePatch(incoming, policy.mutableFields);
+        return policy
+            .applyUpdate(existing, patch)
+            .withErrorFormat((msg) => `memory put '${incoming.envelope.id}': update failed: ${msg}`)
+            .onSuccess((updated) => {
+            if (typeof updated.body !== 'string') {
+                return fail(`memory put '${incoming.envelope.id}': policy returned a non-string body (${typeof updated.body})`);
+            }
+            const finalBody = updated.body;
+            return this._contentHash(updated.envelope.kind, finalBody, updated.envelope.links).onSuccess((finalHash) => succeed({
+                envelope: Object.assign(Object.assign({}, updated.envelope), { created: existing.envelope.created, updated: now, seq, contentHash: finalHash }),
+                body: finalBody
+            }));
+        });
+    }
+    /** Serialize and write a fully-stamped record, then patch the index. */
+    _persist(record, scope, idStem) {
+        return serializeMemoryFile(record.envelope, record.body)
+            .onSuccess((raw) => this._writeFile(scope, idStem, raw))
+            .onSuccess(() => this._index.patch('put', { scope, record }))
+            .onSuccess(() => succeed(record));
+    }
+    async _deleteLocked(kind, entityId) {
+        return this._codecFor(kind)
+            .onSuccess((codec) => codec.encode(entityId))
+            .thenOnSuccess((addr) => {
+            if (addr.isVersioned) {
+                return Promise.resolve(fail(`memory delete '${entityId}': versioned/temporal layout not yet supported`));
+            }
+            return this._readRecord(addr.scope, addr.idStem).thenOnSuccess((existing) => {
+                if (existing === undefined) {
+                    return Promise.resolve(fail(`memory delete '${entityId}': no record found`));
+                }
+                // Delete the record file + index entry (authoritative), then prune the
+                // vector best-effort: a committed delete must not fail because the
+                // derived index could not be pruned.
+                return this._deleteFile(addr.scope, addr.idStem)
+                    .onSuccess(() => this._index.patch('delete', { scope: addr.scope, record: existing }))
+                    .thenOnSuccess(async () => {
+                    await this._removeVectorBestEffort(existing.envelope.id);
+                    return succeed(existing.envelope.id);
+                });
+            });
+        });
+    }
+    /** Evict (physically delete) a single record file by id, patching the index. */
+    _evict(scope, id) {
+        return this._readRecord(scope, id).onSuccess((existing) => {
+            if (existing === undefined) {
+                return fail(`memory put: cannot evict '${id}' in scope '${scope}': not found`);
+            }
+            return this._deleteFile(scope, id)
+                .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
+                .onSuccess(() => succeed(id));
+        });
+    }
+    /** Project the incoming record's mutable fields into a merge-patch. */
+    _projectMutablePatch(record, mutableFields) {
+        const patch = {};
+        for (const field of mutableFields) {
+            const accessor = FileTreeMemoryStore._mutableFieldAccessors.get(field);
+            if (accessor !== undefined) {
+                const value = accessor(record);
+                if (value !== undefined) {
+                    patch[field] = value;
+                }
+            }
+        }
+        return patch;
+    }
+    /**
+     * The admission cohort for a write: every indexed record in `scope` of `kind`
+     * except the one at `idStem` (the record being written or updated). This is
+     * the set a per-kind cap (e.g. {@link MemoryCapCullPolicy}) counts against, so
+     * a bounded-ring policy can keep a per-scope/per-kind family within
+     * `maxRecords`. Excluding the target id makes the post-write count uniform
+     * across first-writes and updates.
+     */
+    _admissionCohort(scope, kind, idStem) {
+        return this._index
+            .entries()
+            .filter((entry) => entry.scope === scope && entry.record.envelope.kind === kind && entry.record.envelope.id !== idStem)
+            .map((entry) => entry.record);
+    }
+    /** Find a record in `scope` whose `contentHash` equals `hash`, if any. */
+    _findByContentHash(scope, hash) {
+        const match = this._index
+            .entries()
+            .find((entry) => entry.scope === scope && entry.record.envelope.contentHash === hash);
+        return match === null || match === void 0 ? void 0 : match.record;
+    }
+    _contentHash(kind, body, links) {
+        return this._hasher.computeHash({ kind, body, links });
+    }
+    _codecFor(kind) {
+        var _a;
+        const codec = (_a = this._codecs.get(kind)) !== null && _a !== void 0 ? _a : this._defaultCodec;
+        if (codec === undefined) {
+            return fail(`no identity codec registered for kind '${kind}'`);
+        }
+        return succeed(codec);
+    }
+    _policyFor(kind) {
+        var _a;
+        return (_a = this._writePolicies.get(kind)) !== null && _a !== void 0 ? _a : this._defaultPolicy;
+    }
+    /**
+     * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
+     * when the scope directory or file is absent. Verifies the on-disk id ↔
+     * filename round-trip on every load.
+     */
+    _readRecord(scope, idStem) {
+        return this._resolveScopeDir(scope).onSuccess((scopeDir) => {
+            if (scopeDir === undefined) {
+                return succeed(undefined);
+            }
+            return scopeDir.getChildren().onSuccess((children) => {
+                const targetName = `${idStem}${MEMORY_FILE_EXTENSION}`;
+                const file = children.find((c) => c.type === 'file' && c.name === targetName);
+                if (file === undefined) {
+                    return succeed(undefined);
+                }
+                return file
+                    .getRawContents()
+                    .onSuccess((raw) => parseMemoryFile(raw, this._registry))
+                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, file, parsedRecord));
+            });
+        });
+    }
+    /** Enforce `envelope.id === filename stem` and the codec round-trip on load. */
+    _verifyLoaded(scope, file, record) {
+        if (record.envelope.id !== file.baseName) {
+            return fail(`memory file '${file.absolutePath}': envelope id '${record.envelope.id}' does not match filename stem '${file.baseName}'`);
+        }
+        return this._codecFor(record.envelope.kind)
+            .onSuccess((codec) => codec.verifyRoundTrip(scope, file.baseName))
+            .withErrorFormat((msg) => `memory file '${file.absolutePath}': ${msg}`)
+            .onSuccess(() => succeed(record));
+    }
+    /**
+     * Resolve the directory for a scope, returning `undefined` when it does not
+     * exist. Navigation only — does not create. Folds the path segments through
+     * `getChildren` so an absent segment short-circuits to `undefined`.
+     */
+    _resolveScopeDir(scope) {
+        return this._scopeEncoding(scope).onSuccess((encoded) => {
+            const segments = encoded.split('/').filter((s) => s.length > 0);
+            return segments.reduce((acc, segment) => acc.onSuccess((current) => {
+                if (current === undefined) {
+                    return succeed(undefined);
+                }
+                return current
+                    .getChildren()
+                    .onSuccess((children) => succeed(children.find((c) => c.type === 'directory' && c.name === segment)));
+            }), succeed(this._root));
+        });
+    }
+    /** Ensure the scope directory exists, creating segments as needed. */
+    _ensureScopeDir(scope) {
+        return this._scopeEncoding(scope).onSuccess((encoded) => {
+            const segments = encoded.split('/').filter((s) => s.length > 0);
+            return segments.reduce((acc, segment) => acc.onSuccess((current) => current.getChildren().onSuccess((children) => {
+                const existing = children.find((c) => c.type === 'directory' && c.name === segment);
+                if (existing === undefined) {
+                    return current.createChildDirectory(segment);
+                }
+                /* c8 ignore next 3 -- defensive: a child of a mutable in-memory/fs tree is itself mutable; the guard protects against a read-only adapter handed in as root */
+                if (!FileTree.isMutableDirectoryItem(existing)) {
+                    return fail(`${existing.absolutePath}: directory is not mutable`);
+                }
+                return succeed(existing);
+            })), succeed(this._root));
+        });
+    }
+    /** Write (create or overwrite) `<scope>/<idStem>.md` with `raw`. */
+    _writeFile(scope, idStem, raw) {
+        return this._ensureScopeDir(scope).onSuccess((scopeDir) => scopeDir.getChildren().onSuccess((children) => {
+            const fileName = `${idStem}${MEMORY_FILE_EXTENSION}`;
+            const existing = children.find((c) => c.type === 'file' && c.name === fileName);
+            if (existing === undefined) {
+                return scopeDir.createChildFile(fileName, raw).onSuccess(() => succeed(true));
+            }
+            /* c8 ignore next 3 -- defensive: a file in a mutable tree is mutable; guards a read-only adapter */
+            if (!FileTree.isMutableFileItem(existing)) {
+                return fail(`${existing.absolutePath}: file is not mutable`);
+            }
+            return existing.setRawContents(raw).onSuccess(() => succeed(true));
+        }));
+    }
+    /**
+     * Physically delete `<scope>/<idStem>.md`. The scope-missing and file-missing
+     * guards are unreachable through the callers (`delete` / `_evict` both read the
+     * record first, so the directory and file exist) but are kept so a future
+     * direct caller degrades loudly rather than silently.
+     */
+    _deleteFile(scope, idStem) {
+        return this._resolveScopeDir(scope).onSuccess((scopeDir) => {
+            /* c8 ignore next 3 -- unreachable: callers read the record (hence the scope dir) first */
+            if (scopeDir === undefined) {
+                return fail(`memory delete: scope '${scope}' not found`);
+            }
+            const fileName = `${idStem}${MEMORY_FILE_EXTENSION}`;
+            return scopeDir.getChildren().onSuccess((children) => {
+                const file = children.find((c) => c.type === 'file' && c.name === fileName);
+                /* c8 ignore next 3 -- unreachable: callers read the record (hence the file) first */
+                if (file === undefined) {
+                    return fail(`memory delete: file '${fileName}' not found in scope '${scope}'`);
+                }
+                /* c8 ignore next 3 -- defensive: a file in a mutable tree is mutable; guards a read-only adapter */
+                if (!FileTree.isMutableFileItem(file)) {
+                    return fail(`${file.absolutePath}: file is not mutable`);
+                }
+                return file.delete().onSuccess(() => succeed(true));
+            });
+        });
+    }
+    /**
+     * Walk the FileTree once and rebuild the index. Also resumes the `seq`
+     * counter past the highest persisted `seq` so new writes stay monotonic.
+     */
+    _initialIndex() {
+        return this._collectEntries(this._root, []).onSuccess((entries) => this._index.rebuild(entries).onSuccess(() => {
+            for (const entry of entries) {
+                if (entry.record.envelope.seq > this._seq) {
+                    this._seq = entry.record.envelope.seq;
+                }
+            }
+            return succeed(true);
+        }));
+    }
+    /** Recursively collect every `.md` record under `dir` (scope = path segments). */
+    _collectEntries(dir, scopeSegments) {
+        return dir.getChildren().onSuccess((children) => {
+            const results = children.map((child) => {
+                if (child.type === 'directory') {
+                    return this._collectEntries(child, [...scopeSegments, child.name]);
+                }
+                if (!child.name.endsWith(MEMORY_FILE_EXTENSION) || scopeSegments.length === 0) {
+                    // Skip non-record files and any record-shaped file sitting at the root
+                    // (records always live under at least one scope segment).
+                    return succeed([]);
+                }
+                const scope = scopeSegments.join('/');
+                return child
+                    .getRawContents()
+                    .onSuccess((raw) => parseMemoryFile(raw, this._registry))
+                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, child, parsedRecord))
+                    .onSuccess((verified) => succeed([{ scope, record: verified }]));
+            });
+            return mapResults(results).onSuccess((perChild) => succeed(perChild.flat()));
+        });
+    }
+}
+/**
+ * The record-level mutable-field vocabulary: maps a declared mutable field
+ * name to its canonical location on a record. Used to project an incoming
+ * record into a merge-patch on update. B1 ships the knowledge-LWW surface
+ * (body + envelope metadata); body-internal mutable fields (Phase-C cap-cull)
+ * extend this map.
+ */
+FileTreeMemoryStore._mutableFieldAccessors = new Map([
+    ['body', (r) => r.body],
+    ['tags', (r) => r.envelope.tags],
+    ['links', (r) => r.envelope.links],
+    ['provenance', (r) => r.envelope.provenance],
+    ['embeddingRef', (r) => r.envelope.embeddingRef]
+]);
+//# sourceMappingURL=fileTreeMemoryStore.js.map