@fgv/ts-agent-memory 5.1.0-51 → 5.1.0-53

package/dist/packlets/store/fileTreeMemoryStore.js

@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: MIT
  */
 import { Hash, Logging, fail, mapResults, mapSuccess, succeed } from '@fgv/ts-utils';
-import { FileTree } from '@fgv/ts-json-base';
 import { DEFAULT_DEDUP_SCOPE, KnowledgeLwwPolicy, isTemporalIdentityCodec, isTemporalRecord, isVersionCurrent, selectCurrentVersion, selectVersionAsOf } from '../types';
 import { parseMemoryFile, serializeMemoryFile, splitFrontmatter } from '../converters';
 import { VectorMaintenance } from './vectorMaintenance';
 import { computeCoverage } from './storeCoverage';
-import { codecFor, resolveIdentity, verifyLoadedIdentity } from './storeIdentity';
+import { codecFor, resolveIdentity, verifyLoadedIdentity, verifyOccupantKind } from './storeIdentity';
+import { deleteRecordFile, resolveScopeDir, writeRecordFile } from './storeFileAccess';
 import { reconcileVectors } from './storeReconcile';
 import { MemoryIndex } from '../index';
 import { defaultMemoryScopeEncoding } from './scopeEncoding';
@@ -129,9 +129,9 @@ export class FileTreeMemoryStore {
                 // version whose `invalid_at` is null/absent) from the entity subtree,
                 // read off the derived index. `asOf` resolution is via `list({ asOf })`
                 // and the temporal retrievers.
-                return this._readVersionedCurrent(addr.scope);
+                return this._readVersionedCurrent(addr.scope, kind);
             }
-            return this._readRecord(addr.scope, addr.idStem);
+            return this._readRecord(addr.scope, addr.idStem, kind);
         }));
         await this._fireObservation('read', kind, entityId, {
             outcome: result.isSuccess() ? 'success' : 'failure',
@@ -490,7 +490,7 @@ export class FileTreeMemoryStore {
                 return succeed({ record: duplicate.value, evicted: [] });
             }
         }
-        return this._readRecord(scope, idStem).thenOnSuccess((existing) => {
+        return this._readRecord(scope, idStem, record.envelope.kind).thenOnSuccess((existing) => {
             // Same-id re-put is a no-op ONLY when the content hash matches AND the
             // mutable metadata is also unchanged. The content hash covers
             // { kind, body, links }; a matching hash with revised tags/provenance is a
@@ -616,7 +616,7 @@ export class FileTreeMemoryStore {
     /** 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((raw) => writeRecordFile(this._root, this._scopeEncoding, scope, idStem, raw))
             .onSuccess(() => this._index.patch('put', { scope, record }))
             .onSuccess(() => succeed(record));
     }
@@ -626,9 +626,9 @@ export class FileTreeMemoryStore {
                 if (!isTemporalIdentityCodec(codec)) {
                     return Promise.resolve(fail(`memory delete '${entityId}': codec for versioned kind '${kind}' does not implement the temporal codec interface`));
                 }
-                return this._deleteVersioned(entityId, addr.scope);
+                return this._deleteVersioned(entityId, addr.scope, kind);
             }
-            return this._deleteFlat(entityId, addr.scope, addr.idStem);
+            return this._deleteFlat(entityId, addr.scope, addr.idStem, kind);
         }));
     }
     /**
@@ -636,15 +636,15 @@ export class FileTreeMemoryStore {
      * entry, then prune the vector best-effort. Structurally unchanged from the
      * pre-temporal delete path.
      */
-    async _deleteFlat(entityId, scope, idStem) {
-        return this._readRecord(scope, idStem).thenOnSuccess((existing) => {
+    async _deleteFlat(entityId, scope, idStem, kind) {
+        return this._readRecord(scope, idStem, kind).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(scope, idStem)
+            return deleteRecordFile(this._root, this._scopeEncoding, scope, idStem)
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .thenOnSuccess(async () => {
                 await this._vectors.removeAll({ scope, id: existing.envelope.id });
@@ -658,7 +658,7 @@ export class FileTreeMemoryStore {
      * null/absent. `undefined` when the entity has no current version (never
      * written, or fully invalidated / soft-deleted).
      */
-    _readVersionedCurrent(scope) {
+    _readVersionedCurrent(scope, expectedKind) {
         // Select over ENVELOPES, then materialize the one winner — which is what
         // `IMemoryStore.get`'s docstring promises and what `selectCurrentVersion`
         // being generic over `IEnvelopeCarrier` exists for. Materializing every
@@ -668,21 +668,21 @@ export class FileTreeMemoryStore {
         if (current === undefined) {
             return succeed(undefined);
         }
-        return this._resolveRequired(current);
+        return this._resolveRequired(current).onSuccess((materialized) => verifyOccupantKind(expectedKind, scope, materialized.envelope.id, materialized));
     }
     /**
      * Every persisted version of the entity whose subtree is `scope`. All version
      * files for one entity live under exactly that scope (which encodes the
      * entityId), so a scope filter over the index isolates one entity's versions.
      */
-    _versionsForEntity(scope) {
+    _versionsForEntity(scope, expectedKind) {
         // Selected on the envelope (scope), materialized after — so a versioned write
         // reads only that entity's versions, never the vault. Bounded by the entity's
         // version count.
         return mapResults(this._index
             .entries()
             .filter((entry) => entry.scope === scope)
-            .map((entry) => this._resolveRequired(entry)));
+            .map((entry) => this._resolveRequired(entry).onSuccess((r) => verifyOccupantKind(expectedKind, scope, r.envelope.id, r))));
     }
     /**
      * Versioned write (invalidate-don't-delete). Builds the new version's content
@@ -704,7 +704,7 @@ export class FileTreeMemoryStore {
         // still-current version at snapshot time — normally one, but two-or-more if a
         // prior invalidation partially failed; invalidating all of them lets the write
         // self-heal a stuck state (P2-7).
-        const snapshot = this._versionsForEntity(scope);
+        const snapshot = this._versionsForEntity(scope, kind);
         if (snapshot.isFailure()) {
             return fail(snapshot.message);
         }
@@ -833,8 +833,8 @@ export class FileTreeMemoryStore {
      * kinds exist to preserve the audit trail (and the L3 `contradicts` interlock
      * builds on it), so a hard delete would defeat the purpose.
      */
-    async _deleteVersioned(entityId, scope) {
-        const snapshot = this._versionsForEntity(scope);
+    async _deleteVersioned(entityId, scope, kind) {
+        const snapshot = this._versionsForEntity(scope, kind);
         if (snapshot.isFailure()) {
             return fail(snapshot.message);
         }
@@ -857,7 +857,7 @@ export class FileTreeMemoryStore {
             if (existing === undefined) {
                 return fail(`memory put: cannot evict '${id}' in scope '${scope}': not found`);
             }
-            return this._deleteFile(scope, id)
+            return deleteRecordFile(this._root, this._scopeEncoding, scope, id)
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .onSuccess(() => succeed(id));
         });
@@ -1007,7 +1007,7 @@ export class FileTreeMemoryStore {
      * already-consistent store touches no files.
      */
     _rewriteEnvelope(scope, id, mutate) {
-        return this._resolveScopeDir(scope).onSuccess((scopeDir) => {
+        return resolveScopeDir(this._root, this._scopeEncoding, scope).onSuccess((scopeDir) => {
             /* c8 ignore next 3 - defensive: the scope dir exists for any indexed record */
             if (scopeDir === undefined) {
                 return fail(`'${id}': scope '${scope}' not found`);
@@ -1102,8 +1102,8 @@ export class FileTreeMemoryStore {
      * 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) => {
+    _readRecord(scope, idStem, expectedKind) {
+        return resolveScopeDir(this._root, this._scopeEncoding, scope).onSuccess((scopeDir) => {
             if (scopeDir === undefined) {
                 return succeed(undefined);
             }
@@ -1116,7 +1116,8 @@ export class FileTreeMemoryStore {
                 return file
                     .getRawContents()
                     .onSuccess((raw) => parseMemoryFile(raw, this._registry))
-                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, file, parsedRecord));
+                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, file, parsedRecord))
+                    .onSuccess((loaded) => verifyOccupantKind(expectedKind, scope, idStem, loaded));
             });
         });
     }
@@ -1132,83 +1133,6 @@ export class FileTreeMemoryStore {
     _verifyLoaded(scope, file, record) {
         return verifyLoadedIdentity(this._codec(record.envelope.kind), scope, file, 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.