@fgv/ts-agent-memory 5.1.0-39 → 5.1.0-41

package/lib/packlets/store/fileTreeMemoryStore.js

@@ -33,6 +33,7 @@ class FileTreeMemoryStore {
         this._registry = params.registry;
         this._writePolicies = params.writePolicies;
         this._codecs = params.codecs;
+        this._rankProjectors = params.rankProjectors;
         this._defaultCodec = params.defaultCodec;
         this._defaultPolicy = params.defaultPolicy;
         this._scopeEncoding = params.scopeEncoding;
@@ -54,19 +55,20 @@ class FileTreeMemoryStore {
      */
     static create(params) {
         return types_1.KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => index_1.MemoryIndex.create().onSuccess((index) => {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _e, _f, _g;
             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(),
+                rankProjectors: (_c = params.rankProjectors) !== null && _c !== void 0 ? _c : new Map(),
                 defaultCodec: params.defaultCodec,
                 defaultPolicy,
-                scopeEncoding: (_c = params.scopeEncoding) !== null && _c !== void 0 ? _c : scopeEncoding_1.defaultMemoryScopeEncoding,
-                clock: (_d = params.clock) !== null && _d !== void 0 ? _d : Date.now,
+                scopeEncoding: (_d = params.scopeEncoding) !== null && _d !== void 0 ? _d : scopeEncoding_1.defaultMemoryScopeEncoding,
+                clock: (_e = params.clock) !== null && _e !== void 0 ? _e : Date.now,
                 index,
-                observers: (_e = params.observers) !== null && _e !== void 0 ? _e : [],
-                logger: (_f = params.logger) !== null && _f !== void 0 ? _f : new ts_utils_1.Logging.NoOpLogger(),
+                observers: (_f = params.observers) !== null && _f !== void 0 ? _f : [],
+                logger: (_g = params.logger) !== null && _g !== void 0 ? _g : new ts_utils_1.Logging.NoOpLogger(),
                 vectorIndex: params.vectorIndex,
                 embed: params.embed
             });
@@ -124,6 +126,21 @@ class FileTreeMemoryStore {
         }
         return (0, ts_utils_1.succeed)(FileTreeMemoryStore._projectAsOf(matches, filter.asOf));
     }
+    /** {@inheritDoc IMemoryStore.listScoped} */
+    async listScoped() {
+        // The derived index already carries each record's scope
+        // ({@link IIndexedMemoryRecord.scope}), so the scoped projection is a direct
+        // map — the record's `(scope, id)` is exactly the address the vector index
+        // keys on. No filter/temporal projection: the seam re-embeds the whole vault.
+        return (0, ts_utils_1.succeed)(this._index.entries().map((entry) => ({
+            target: { scope: entry.scope, id: entry.record.envelope.id },
+            record: entry.record
+        })));
+    }
+    /** {@inheritDoc IMemoryStore.asRecordSource} */
+    asRecordSource() {
+        return { list: () => this.listScoped() };
+    }
     /**
      * Collapse temporal records to the single version valid at `asOf` per entity;
      * non-temporal records are timeless and pass through unchanged (valid-time
@@ -370,7 +387,8 @@ class FileTreeMemoryStore {
             return (0, ts_utils_1.fail)(`memory put: rejected by policy: ${decision.reason}`);
         }
         return this._buildRecord(record, body, existing, policy, hash)
-            .thenOnSuccess((built) => this._embedOnWrite(built))
+            .onSuccess((built) => (0, ts_utils_1.succeed)(this._stampRank(built)))
+            .thenOnSuccess((built) => this._embedOnWrite(built, scope))
             .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
             .thenOnSuccess(async (persisted) => {
             // Everything after the authoritative `_persist` commit is best-effort and
@@ -380,7 +398,7 @@ class FileTreeMemoryStore {
             //     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);
+            await this._removeEvictedVectors(evicted, scope);
             return (0, ts_utils_1.succeed)({ record: persisted, evicted });
         });
     }
@@ -396,17 +414,18 @@ class FileTreeMemoryStore {
      * Always succeeds (`Result` is the chain's shape, never a vector-induced
      * failure).
      */
-    async _embedOnWrite(built) {
+    async _embedOnWrite(built, scope) {
         if (this._vectorIndex === undefined || this._embed === undefined) {
             return (0, ts_utils_1.succeed)(built);
         }
         const vectorIndex = this._vectorIndex;
         const embed = this._embed;
+        const target = { scope, id: built.envelope.id };
         const embedded = await this._tryVectorOp(() => embed(built), `embedding '${built.envelope.id}'`);
         if (embedded.isFailure()) {
             return (0, ts_utils_1.succeed)(built);
         }
-        const added = await this._tryVectorOp(() => vectorIndex.add(built.envelope.id, embedded.value), `vector add for '${built.envelope.id}'`);
+        const added = await this._tryVectorOp(() => vectorIndex.add(target, embedded.value), `vector add for '${built.envelope.id}'`);
         if (added.isFailure()) {
             return (0, ts_utils_1.succeed)(built);
         }
@@ -435,10 +454,15 @@ class FileTreeMemoryStore {
         }
         return evicted;
     }
-    /** Best-effort vector removal for each evicted record (never fails the put). */
-    async _removeEvictedVectors(evicted) {
+    /**
+     * Best-effort vector removal for each evicted record (never fails the put).
+     * Every evicted record is in the same `scope` as the incoming write (the
+     * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
+     * scope qualifies each removal target.
+     */
+    async _removeEvictedVectors(evicted, scope) {
         for (const id of evicted) {
-            await this._removeVectorBestEffort(id);
+            await this._removeVectorBestEffort({ scope, id });
         }
     }
     /**
@@ -465,12 +489,12 @@ class FileTreeMemoryStore {
      * 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) {
+    async _removeVectorBestEffort(target) {
         if (this._vectorIndex === undefined || this._embed === undefined) {
             return;
         }
         const vectorIndex = this._vectorIndex;
-        await this._tryVectorOp(() => vectorIndex.remove(id), `vector removal for '${id}'`);
+        await this._tryVectorOp(() => vectorIndex.remove(target), `vector removal for '${target.id}'`);
     }
     /**
      * Build the record to persist. On a first write the incoming envelope is the
@@ -541,7 +565,7 @@ class FileTreeMemoryStore {
             return this._deleteFile(scope, idStem)
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .thenOnSuccess(async () => {
-                await this._removeVectorBestEffort(existing.envelope.id);
+                await this._removeVectorBestEffort({ scope, id: existing.envelope.id });
                 return (0, ts_utils_1.succeed)(existing.envelope.id);
             });
         });
@@ -626,7 +650,8 @@ class FileTreeMemoryStore {
                     .encodeVersion(entityId, seq)
                     .withErrorFormat((msg) => `memory put '${entityId}': ${msg}`)
                     .thenOnSuccess((versionStem) => this._buildVersionedRecord(record, body, current, policy, hash, versionStem, validAt, now, seq)
-                    .thenOnSuccess((built) => this._embedOnWrite(built))
+                    .onSuccess((built) => (0, ts_utils_1.succeed)(this._stampRank(built)))
+                    .thenOnSuccess((built) => this._embedOnWrite(built, scope))
                     .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, versionStem))
                     .onSuccess((persisted) => this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() => (0, ts_utils_1.succeed)(persisted)))
                     .onSuccess((persisted) => (0, ts_utils_1.succeed)({ record: persisted, evicted: [] })));
@@ -794,6 +819,37 @@ class FileTreeMemoryStore {
     _contentHash(kind, body, links) {
         return this._hasher.computeHash({ kind, body, links });
     }
+    /**
+     * Stamp the store-computed {@link IMemoryEnvelope.rank} onto a fully-built,
+     * fully-stamped record by running the kind's registered {@link RankProjector}.
+     * Runs on the SAME resolved (post-merge) record whose `contentHash` was just
+     * computed, so `rank` is always consistent with the current body — no separate
+     * write path and no consumer write-discipline rule. A no-op pass-through
+     * (byte-identical record) when the kind has no projector — the additive,
+     * zero-overhead-when-unwired default. The projector is a host callback: a throw
+     * is logged at `warn` and the record is stamped with NO `rank` (the field is
+     * explicitly cleared, so a throw on an update drops a now-stale prior rank rather
+     * than preserving it), so a ranking bug never loses an authoritative write.
+     */
+    _stampRank(record) {
+        const projector = this._rankProjectors.get(record.envelope.kind);
+        if (projector === undefined) {
+            return record;
+        }
+        try {
+            const rank = projector(record);
+            return { envelope: Object.assign(Object.assign({}, record.envelope), { rank }), body: record.body };
+        }
+        catch (err) {
+            this._warnSwallowed(`memory put '${record.envelope.id}': rank projector threw (swallowed; rank cleared): ${String(err)}`);
+            // Explicitly CLEAR `rank` (not `return record`): on an update the merged
+            // envelope carries the prior version's `rank` (the write-policy merge does
+            // not touch `rank`), so returning it verbatim would keep a stale value
+            // inconsistent with the revised body. Clearing honors the staleness
+            // contract — an uncomputable rank means the record sorts last as "unranked".
+            return { envelope: Object.assign(Object.assign({}, record.envelope), { rank: undefined }), body: record.body };
+        }
+    }
     _codecFor(kind) {
         var _a;
         const codec = (_a = this._codecs.get(kind)) !== null && _a !== void 0 ? _a : this._defaultCodec;