@fgv/ts-agent-memory 5.1.0-36

package/lib/packlets/index/memoryIndex.js

@@ -0,0 +1,174 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryIndex = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */
+const EMPTY_KEY_SET = new Set();
+/**
+ * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /
+ * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an
+ * already-indexed key first removes the prior entry's associations so a changed
+ * kind / tag / link set never leaves a stale reference behind.
+ * @public
+ */
+class MemoryIndex {
+    constructor() {
+        this._byKey = new Map();
+        this._byKind = new Map();
+        this._byTag = new Map();
+        this._backlinks = new Map();
+    }
+    /** Family-convention factory. */
+    static create() {
+        return (0, ts_utils_1.succeed)(new MemoryIndex());
+    }
+    /**
+     * The composite primary key for an entry: scope + id, NUL-separated. NUL
+     * is excluded from both components (scope segments pass
+     * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it
+     * is a collision-proof separator across every scope/id pair the codecs produce.
+     */
+    static _keyOf(scope, id) {
+        return `${scope}\0${id}`;
+    }
+    /** {@inheritDoc IMemoryIndex.rebuild} */
+    rebuild(entries) {
+        this._byKey.clear();
+        this._byKind.clear();
+        this._byTag.clear();
+        this._backlinks.clear();
+        for (const entry of entries) {
+            this._add(entry);
+        }
+        return (0, ts_utils_1.succeed)(this._byKey.size);
+    }
+    /** {@inheritDoc IMemoryIndex.patch} */
+    patch(op, entry) {
+        const key = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
+        // Always drop any prior associations for this key first, so a 'put' that
+        // changes kind/tags/links cannot strand a stale reference.
+        this._remove(key);
+        if (op === 'put') {
+            this._add(entry);
+        }
+        return (0, ts_utils_1.succeed)(entry);
+    }
+    /** {@inheritDoc IMemoryIndex.entries} */
+    entries() {
+        return Array.from(this._byKey.values());
+    }
+    /** {@inheritDoc IMemoryIndex.byKind} */
+    byKind(kind) {
+        var _a;
+        return this._recencyOrdered((_a = this._byKind.get(kind)) !== null && _a !== void 0 ? _a : EMPTY_KEY_SET);
+    }
+    /** {@inheritDoc IMemoryIndex.byTag} */
+    byTag(tag) {
+        var _a;
+        return this._recencyOrdered((_a = this._byTag.get(tag)) !== null && _a !== void 0 ? _a : EMPTY_KEY_SET);
+    }
+    /** {@inheritDoc IMemoryIndex.byRecency} */
+    byRecency() {
+        return this._recencyOrdered(this._byKey.keys());
+    }
+    /** {@inheritDoc IMemoryIndex.backlinks} */
+    backlinks(target) {
+        const sources = this._backlinks.get(target);
+        return sources === undefined ? [] : Array.from(sources.values());
+    }
+    /**
+     * Resolve a set of composite keys to their records, ordered
+     * most-recently-updated first (with a `seq` tiebreak so equal-`updated`
+     * records sort deterministically).
+     */
+    _recencyOrdered(keys) {
+        const records = [];
+        for (const key of keys) {
+            const entry = this._byKey.get(key);
+            if (entry !== undefined) {
+                records.push(entry.record);
+            }
+        }
+        return records.sort((a, b) => {
+            const byUpdated = b.envelope.updated - a.envelope.updated;
+            return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
+        });
+    }
+    /** Insert an entry and register all its derived associations. */
+    _add(entry) {
+        const key = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
+        const envelope = entry.record.envelope;
+        this._byKey.set(key, entry);
+        this._addToSetMap(this._byKind, envelope.kind, key);
+        for (const tag of envelope.tags) {
+            this._addToSetMap(this._byTag, tag, key);
+        }
+        for (const edge of envelope.links) {
+            this._addBacklink(edge.target, key, envelope.id);
+        }
+    }
+    /** Remove the entry at `key` (if present) and all its derived associations. */
+    _remove(key) {
+        const entry = this._byKey.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        const envelope = entry.record.envelope;
+        this._byKey.delete(key);
+        this._removeFromSetMap(this._byKind, envelope.kind, key);
+        for (const tag of envelope.tags) {
+            this._removeFromSetMap(this._byTag, tag, key);
+        }
+        for (const edge of envelope.links) {
+            this._removeBacklink(edge.target, key);
+        }
+    }
+    /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */
+    _addBacklink(target, sourceKey, sourceId) {
+        const existing = this._backlinks.get(target);
+        if (existing === undefined) {
+            this._backlinks.set(target, new Map([[sourceKey, sourceId]]));
+        }
+        else {
+            existing.set(sourceKey, sourceId);
+        }
+    }
+    /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
+    _removeBacklink(target, sourceKey) {
+        const existing = this._backlinks.get(target);
+        if (existing === undefined) {
+            return;
+        }
+        existing.delete(sourceKey);
+        if (existing.size === 0) {
+            this._backlinks.delete(target);
+        }
+    }
+    /** Add `member` to the set at `mapKey`, creating the set on first use. */
+    _addToSetMap(map, mapKey, member) {
+        const existing = map.get(mapKey);
+        if (existing === undefined) {
+            map.set(mapKey, new Set([member]));
+        }
+        else {
+            existing.add(member);
+        }
+    }
+    /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
+    _removeFromSetMap(map, mapKey, member) {
+        const existing = map.get(mapKey);
+        if (existing === undefined) {
+            return;
+        }
+        existing.delete(member);
+        if (existing.size === 0) {
+            map.delete(mapKey);
+        }
+    }
+}
+exports.MemoryIndex = MemoryIndex;
+//# sourceMappingURL=memoryIndex.js.map

package/lib/packlets/index/memoryIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryIndex.js","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAgD;AAUhD,uFAAuF;AACvF,MAAM,aAAa,GAAwB,IAAI,GAAG,EAAU,CAAC;AAgE7D;;;;;;GAMG;AACH,MAAa,WAAW;IAetB;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;QACtD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC/D,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,IAAA,kBAAO,EAAC,IAAI,WAAW,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,MAAM,CAAC,KAAqB,EAAE,EAAY;QACvD,OAAO,GAAG,KAAK,KAAK,EAAE,EAAE,CAAC;IAC3B,CAAC;IAED,yCAAyC;IAClC,OAAO,CAAC,OAA4C;QACzD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,uCAAuC;IAChC,KAAK,CAAC,EAAsB,EAAE,KAA2B;QAC9D,MAAM,GAAG,GAAW,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9E,yEAAyE;QACzE,2DAA2D;QAC3D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAED,yCAAyC;IAClC,OAAO;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,wCAAwC;IACjC,MAAM,CAAC,IAAU;;QACtB,OAAO,IAAI,CAAC,eAAe,CAAC,MAAA,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAI,aAAa,CAAC,CAAC;IACvE,CAAC;IAED,uCAAuC;IAChC,KAAK,CAAC,GAAQ;;QACnB,OAAO,IAAI,CAAC,eAAe,CAAC,MAAA,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,aAAa,CAAC,CAAC;IACrE,CAAC;IAED,2CAA2C;IACpC,SAAS;QACd,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,2CAA2C;IACpC,SAAS,CAAC,MAAgB;QAC/B,MAAM,OAAO,GAAsC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/E,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;;;OAIG;IACK,eAAe,CAAC,IAAsB;QAC5C,MAAM,OAAO,GAA6B,EAAE,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAqC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACrE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC3B,MAAM,SAAS,GAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YAClE,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACzD,IAAI,CAAC,KAA2B;QACtC,MAAM,GAAG,GAAW,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9E,MAAM,QAAQ,GAAuC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,+EAA+E;IACvE,OAAO,CAAC,GAAW;QACzB,MAAM,KAAK,GAAqC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAuC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,uFAAuF;IAC/E,YAAY,CAAC,MAAgB,EAAE,SAAiB,EAAE,QAAkB;QAC1E,MAAM,QAAQ,GAAsC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,CAAmB,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAClF,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,0FAA0F;IAClF,eAAe,CAAC,MAAgB,EAAE,SAAiB;QACzD,MAAM,QAAQ,GAAsC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3B,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,0EAA0E;IAClE,YAAY,CAAO,GAAmB,EAAE,MAAS,EAAE,MAAS;QAClE,MAAM,QAAQ,GAAuB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,CAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,6EAA6E;IACrE,iBAAiB,CAAO,GAAmB,EAAE,MAAS,EAAE,MAAS;QACvE,MAAM,QAAQ,GAAuB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AApLD,kCAoLC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';\n\n/**\n * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was\n * written (`'put'`) or removed (`'delete'`).\n * @public\n */\nexport type MemoryIndexPatchOp = 'put' | 'delete';\n\n/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */\nconst EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();\n\n/**\n * A memory record paired with the {@link MemoryScopeKey | scope} it lives\n * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived\n * from the entity id by the codec), so the store threads it alongside the\n * record when patching or rebuilding the index. The `(scope, id)` pair is the\n * index's primary key, keeping records distinct across scopes that reuse a\n * filename stem (e.g. `turn-0` under different conversations in Phase C).\n * @public\n */\nexport interface IIndexedMemoryRecord {\n  /** The scope the record is stored under. */\n  readonly scope: MemoryScopeKey;\n  /** The memory record itself. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * The derived, in-memory secondary indexes the store maintains over its\n * records. Never the source of truth — the FileTree is. The index is fully\n * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is\n * patched incrementally on every write ({@link IMemoryIndex.patch}).\n *\n * @remarks\n * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}\n * is B2. The accessors return records (not bare ids) so the B2 retrievers can\n * consume them directly.\n * @public\n */\nexport interface IMemoryIndex {\n  /**\n   * Replace the entire index from a full set of records (a store walk).\n   * @returns The number of records indexed.\n   */\n  rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;\n\n  /**\n   * Apply a single incremental change. `'put'` inserts or replaces the entry\n   * at its `(scope, id)` key (removing any prior associations first); `'delete'`\n   * removes it.\n   * @returns The entry that was applied.\n   */\n  patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;\n\n  /** Every indexed entry (scope + record). Primary read surface for the store. */\n  entries(): ReadonlyArray<IIndexedMemoryRecord>;\n\n  /** Records of the given kind, in recency order (most-recently-updated first). */\n  byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** Records carrying the given tag, in recency order. */\n  byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** All records in recency order (most-recently-updated first). */\n  byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /**\n   * The ids of records whose `links` point AT `target` (inbound edges).\n   * The seed map for B2 link-traversal.\n   */\n  backlinks(target: MemoryId): ReadonlyArray<MemoryId>;\n}\n\n/**\n * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /\n * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an\n * already-indexed key first removes the prior entry's associations so a changed\n * kind / tag / link set never leaves a stale reference behind.\n * @public\n */\nexport class MemoryIndex implements IMemoryIndex {\n  /** Primary store: `(scope, id)` composite key → indexed entry. */\n  private readonly _byKey: Map<string, IIndexedMemoryRecord>;\n  /** kind → set of composite keys. */\n  private readonly _byKind: Map<Kind, Set<string>>;\n  /** tag → set of composite keys. */\n  private readonly _byTag: Map<Tag, Set<string>>;\n  /**\n   * link target id → (source composite key → source id). Keyed by the source's\n   * `(scope, id)` composite — NOT its bare id — so two distinct source records\n   * that share an id across scopes (e.g. `turn-0` in different conversations)\n   * are tracked independently and removing one never drops the other's edge.\n   */\n  private readonly _backlinks: Map<MemoryId, Map<string, MemoryId>>;\n\n  private constructor() {\n    this._byKey = new Map<string, IIndexedMemoryRecord>();\n    this._byKind = new Map<Kind, Set<string>>();\n    this._byTag = new Map<Tag, Set<string>>();\n    this._backlinks = new Map<MemoryId, Map<string, MemoryId>>();\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<MemoryIndex> {\n    return succeed(new MemoryIndex());\n  }\n\n  /**\n   * The composite primary key for an entry: scope + id, NUL-separated. NUL\n   * is excluded from both components (scope segments pass\n   * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it\n   * is a collision-proof separator across every scope/id pair the codecs produce.\n   */\n  private static _keyOf(scope: MemoryScopeKey, id: MemoryId): string {\n    return `${scope}\\0${id}`;\n  }\n\n  /** {@inheritDoc IMemoryIndex.rebuild} */\n  public rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number> {\n    this._byKey.clear();\n    this._byKind.clear();\n    this._byTag.clear();\n    this._backlinks.clear();\n    for (const entry of entries) {\n      this._add(entry);\n    }\n    return succeed(this._byKey.size);\n  }\n\n  /** {@inheritDoc IMemoryIndex.patch} */\n  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    // Always drop any prior associations for this key first, so a 'put' that\n    // changes kind/tags/links cannot strand a stale reference.\n    this._remove(key);\n    if (op === 'put') {\n      this._add(entry);\n    }\n    return succeed(entry);\n  }\n\n  /** {@inheritDoc IMemoryIndex.entries} */\n  public entries(): ReadonlyArray<IIndexedMemoryRecord> {\n    return Array.from(this._byKey.values());\n  }\n\n  /** {@inheritDoc IMemoryIndex.byKind} */\n  public byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byTag} */\n  public byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRecency} */\n  public byRecency(): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.backlinks} */\n  public backlinks(target: MemoryId): ReadonlyArray<MemoryId> {\n    const sources: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    return sources === undefined ? [] : Array.from(sources.values());\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered\n   * most-recently-updated first (with a `seq` tiebreak so equal-`updated`\n   * records sort deterministically).\n   */\n  private _recencyOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const key of keys) {\n      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n      if (entry !== undefined) {\n        records.push(entry.record);\n      }\n    }\n    return records.sort((a, b) => {\n      const byUpdated: number = b.envelope.updated - a.envelope.updated;\n      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n    });\n  }\n\n  /** Insert an entry and register all its derived associations. */\n  private _add(entry: IIndexedMemoryRecord): void {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.set(key, entry);\n    this._addToSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._addToSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._addBacklink(edge.target, key, envelope.id);\n    }\n  }\n\n  /** Remove the entry at `key` (if present) and all its derived associations. */\n  private _remove(key: string): void {\n    const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n    if (entry === undefined) {\n      return;\n    }\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.delete(key);\n    this._removeFromSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._removeFromSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._removeBacklink(edge.target, key);\n    }\n  }\n\n  /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */\n  private _addBacklink(target: MemoryId, sourceKey: string, sourceId: MemoryId): void {\n    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    if (existing === undefined) {\n      this._backlinks.set(target, new Map<string, MemoryId>([[sourceKey, sourceId]]));\n    } else {\n      existing.set(sourceKey, sourceId);\n    }\n  }\n\n  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */\n  private _removeBacklink(target: MemoryId, sourceKey: string): void {\n    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(sourceKey);\n    if (existing.size === 0) {\n      this._backlinks.delete(target);\n    }\n  }\n\n  /** Add `member` to the set at `mapKey`, creating the set on first use. */\n  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      map.set(mapKey, new Set<M>([member]));\n    } else {\n      existing.add(member);\n    }\n  }\n\n  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */\n  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(member);\n    if (existing.size === 0) {\n      map.delete(mapKey);\n    }\n  }\n}\n"]}

package/lib/packlets/observe/index.d.ts

@@ -0,0 +1,3 @@
+export * from './observer';
+export * from './memoryObservationStore';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/observe/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/observe/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC"}

package/lib/packlets/observe/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./observer"), exports);
+__exportStar(require("./memoryObservationStore"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/observe/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/observe/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,2DAAyC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './observer';\nexport * from './memoryObservationStore';\n"]}

package/lib/packlets/observe/memoryObservationStore.d.ts

@@ -0,0 +1,91 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryObservationQuery, IMemoryObservationRecord, IMemoryObserver } from './observer';
+/**
+ * Construction options for {@link MemoryObservationStore.create}.
+ * @public
+ */
+export interface IMemoryObservationStoreCreateParams {
+    /**
+     * Maximum number of observation records retained before the oldest is
+     * overwritten. Defaults to `1000`. Must be a positive integer if supplied.
+     */
+    readonly maxRecords?: number;
+}
+/**
+ * The default in-memory observation store: an {@link IMemoryObserver} that
+ * retains the records it observes in a bounded ring and answers schema-aware
+ * {@link MemoryObservationStore.query | queries} over them.
+ *
+ * @remarks
+ * **Privacy posture — this store is most-permissive by design.** It retains
+ * every field of every record verbatim, including any `provenance` and
+ * `querySnapshot`. The library bakes in **no** redaction, retention, or
+ * field-stripping policy — that is deployment policy, not library policy. A
+ * deployment that must redact wraps this store with its own
+ * {@link IMemoryObserver} that transforms records before forwarding, or
+ * substitutes a different observer entirely. Size is the only bounded
+ * dimension, via `maxRecords`.
+ *
+ * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not
+ * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`
+ * (the hook) and `query` (the read surface) live on the same class. Wire it via
+ * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are
+ * assigned by the firing authority (the store) before `observe`, so this store
+ * never mints them.
+ * @public
+ */
+export declare class MemoryObservationStore implements IMemoryObserver {
+    /**
+     * The bounded ring of observed records. The firing authority assigns each
+     * record's `seq`, so the ring's monotonic-`seq` cursor contract is satisfied
+     * by that authority's per-instance counter.
+     * @internal
+     */
+    private readonly _buffer;
+    /**
+     * @param buffer - The pre-constructed backing ring buffer.
+     * @internal
+     */
+    private constructor();
+    /**
+     * The highest `seq` observed so far. Hold this value and pass it as
+     * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only
+     * records observed afterward. Stable across ring eviction and
+     * {@link MemoryObservationStore.clear | clear}.
+     */
+    get lastSeq(): number;
+    /**
+     * The number of records currently retained.
+     */
+    get size(): number;
+    /**
+     * Family-convention factory.
+     * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.
+     * @returns On success, a new store. Fails if `maxRecords` is supplied and is
+     * not a positive integer.
+     */
+    static create(params?: IMemoryObservationStoreCreateParams): Result<MemoryObservationStore>;
+    /**
+     * {@inheritDoc IMemoryObserver.observe}
+     */
+    observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;
+    /**
+     * Returns retained records, oldest-first, narrowed by the supplied criteria.
+     * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.
+     * @returns The matching records, oldest-first.
+     */
+    query(criteria?: IMemoryObservationQuery): ReadonlyArray<IMemoryObservationRecord>;
+    /**
+     * Clears all retained records. Does NOT reset
+     * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`
+     * cursor never re-sees a sequence number.
+     */
+    clear(): void;
+    /**
+     * Tests a record against the non-`seq`/`limit` criteria (those are applied by
+     * the ring buffer itself).
+     * @internal
+     */
+    private static _matches;
+}
+//# sourceMappingURL=memoryObservationStore.d.ts.map

package/lib/packlets/observe/memoryObservationStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryObservationStore.d.ts","sourceRoot":"","sources":["../../../src/packlets/observe/memoryObservationStore.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,MAAM,EAAiB,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhG;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4D;IAEpF;;;OAGG;IACH,OAAO;IAIP;;;;;OAKG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;;OAKG;WACW,MAAM,CAAC,MAAM,CAAC,EAAE,mCAAmC,GAAG,MAAM,CAAC,sBAAsB,CAAC;IAYlG;;OAEG;IACI,OAAO,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAK1E;;;;OAIG;IACI,KAAK,CAAC,QAAQ,CAAC,EAAE,uBAAuB,GAAG,aAAa,CAAC,wBAAwB,CAAC;IASzF;;;;OAIG;IACI,KAAK,IAAI,IAAI;IAIpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAqBxB"}

package/lib/packlets/observe/memoryObservationStore.js

@@ -0,0 +1,123 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryObservationStore = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * The default in-memory observation store: an {@link IMemoryObserver} that
+ * retains the records it observes in a bounded ring and answers schema-aware
+ * {@link MemoryObservationStore.query | queries} over them.
+ *
+ * @remarks
+ * **Privacy posture — this store is most-permissive by design.** It retains
+ * every field of every record verbatim, including any `provenance` and
+ * `querySnapshot`. The library bakes in **no** redaction, retention, or
+ * field-stripping policy — that is deployment policy, not library policy. A
+ * deployment that must redact wraps this store with its own
+ * {@link IMemoryObserver} that transforms records before forwarding, or
+ * substitutes a different observer entirely. Size is the only bounded
+ * dimension, via `maxRecords`.
+ *
+ * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not
+ * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`
+ * (the hook) and `query` (the read surface) live on the same class. Wire it via
+ * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are
+ * assigned by the firing authority (the store) before `observe`, so this store
+ * never mints them.
+ * @public
+ */
+class MemoryObservationStore {
+    /**
+     * @param buffer - The pre-constructed backing ring buffer.
+     * @internal
+     */
+    constructor(buffer) {
+        this._buffer = buffer;
+    }
+    /**
+     * The highest `seq` observed so far. Hold this value and pass it as
+     * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only
+     * records observed afterward. Stable across ring eviction and
+     * {@link MemoryObservationStore.clear | clear}.
+     */
+    get lastSeq() {
+        return this._buffer.lastSeq;
+    }
+    /**
+     * The number of records currently retained.
+     */
+    get size() {
+        return this._buffer.size;
+    }
+    /**
+     * Family-convention factory.
+     * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.
+     * @returns On success, a new store. Fails if `maxRecords` is supplied and is
+     * not a positive integer.
+     */
+    static create(params) {
+        const maxRecords = params === null || params === void 0 ? void 0 : params.maxRecords;
+        if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1)) {
+            return (0, ts_utils_1.fail)(`MemoryObservationStore: maxRecords must be a positive integer (got ${maxRecords})`);
+        }
+        return (0, ts_utils_1.succeed)(new MemoryObservationStore(new ts_utils_1.Collections.RetainingRingBuffer({ maxRecords })));
+    }
+    /**
+     * {@inheritDoc IMemoryObserver.observe}
+     */
+    observe(record) {
+        this._buffer.push(record);
+        return Promise.resolve((0, ts_utils_1.succeed)(record));
+    }
+    /**
+     * Returns retained records, oldest-first, narrowed by the supplied criteria.
+     * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.
+     * @returns The matching records, oldest-first.
+     */
+    query(criteria) {
+        return this._buffer.query({
+            sinceSeq: criteria === null || criteria === void 0 ? void 0 : criteria.sinceSeq,
+            limit: criteria === null || criteria === void 0 ? void 0 : criteria.limit,
+            filter: criteria === undefined ? undefined : (record) => MemoryObservationStore._matches(record, criteria)
+        });
+    }
+    /**
+     * Clears all retained records. Does NOT reset
+     * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`
+     * cursor never re-sees a sequence number.
+     */
+    clear() {
+        this._buffer.clear();
+    }
+    /**
+     * Tests a record against the non-`seq`/`limit` criteria (those are applied by
+     * the ring buffer itself).
+     * @internal
+     */
+    static _matches(record, criteria) {
+        if (criteria.since !== undefined && record.timestamp < criteria.since) {
+            return false;
+        }
+        if (criteria.until !== undefined && record.timestamp > criteria.until) {
+            return false;
+        }
+        if (criteria.scope !== undefined && record.scope !== criteria.scope) {
+            return false;
+        }
+        if (criteria.kind !== undefined && record.kind !== criteria.kind) {
+            return false;
+        }
+        if (criteria.phase !== undefined && record.phase !== criteria.phase) {
+            return false;
+        }
+        if (criteria.outcome !== undefined && record.outcome !== criteria.outcome) {
+            return false;
+        }
+        return true;
+    }
+}
+exports.MemoryObservationStore = MemoryObservationStore;
+//# sourceMappingURL=memoryObservationStore.js.map

package/lib/packlets/observe/memoryObservationStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryObservationStore.js","sourceRoot":"","sources":["../../../src/packlets/observe/memoryObservationStore.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Collections, Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryObservationQuery, IMemoryObservationRecord, IMemoryObserver } from './observer';\n\n/**\n * Construction options for {@link MemoryObservationStore.create}.\n * @public\n */\nexport interface IMemoryObservationStoreCreateParams {\n  /**\n   * Maximum number of observation records retained before the oldest is\n   * overwritten. Defaults to `1000`. Must be a positive integer if supplied.\n   */\n  readonly maxRecords?: number;\n}\n\n/**\n * The default in-memory observation store: an {@link IMemoryObserver} that\n * retains the records it observes in a bounded ring and answers schema-aware\n * {@link MemoryObservationStore.query | queries} over them.\n *\n * @remarks\n * **Privacy posture — this store is most-permissive by design.** It retains\n * every field of every record verbatim, including any `provenance` and\n * `querySnapshot`. The library bakes in **no** redaction, retention, or\n * field-stripping policy — that is deployment policy, not library policy. A\n * deployment that must redact wraps this store with its own\n * {@link IMemoryObserver} that transforms records before forwarding, or\n * substitutes a different observer entirely. Size is the only bounded\n * dimension, via `maxRecords`.\n *\n * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not\n * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`\n * (the hook) and `query` (the read surface) live on the same class. Wire it via\n * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are\n * assigned by the firing authority (the store) before `observe`, so this store\n * never mints them.\n * @public\n */\nexport class MemoryObservationStore implements IMemoryObserver {\n  /**\n   * The bounded ring of observed records. The firing authority assigns each\n   * record's `seq`, so the ring's monotonic-`seq` cursor contract is satisfied\n   * by that authority's per-instance counter.\n   * @internal\n   */\n  private readonly _buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>;\n\n  /**\n   * @param buffer - The pre-constructed backing ring buffer.\n   * @internal\n   */\n  private constructor(buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>) {\n    this._buffer = buffer;\n  }\n\n  /**\n   * The highest `seq` observed so far. Hold this value and pass it as\n   * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only\n   * records observed afterward. Stable across ring eviction and\n   * {@link MemoryObservationStore.clear | clear}.\n   */\n  public get lastSeq(): number {\n    return this._buffer.lastSeq;\n  }\n\n  /**\n   * The number of records currently retained.\n   */\n  public get size(): number {\n    return this._buffer.size;\n  }\n\n  /**\n   * Family-convention factory.\n   * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.\n   * @returns On success, a new store. Fails if `maxRecords` is supplied and is\n   * not a positive integer.\n   */\n  public static create(params?: IMemoryObservationStoreCreateParams): Result<MemoryObservationStore> {\n    const maxRecords: number | undefined = params?.maxRecords;\n    if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1)) {\n      return fail(`MemoryObservationStore: maxRecords must be a positive integer (got ${maxRecords})`);\n    }\n    return succeed(\n      new MemoryObservationStore(\n        new Collections.RetainingRingBuffer<IMemoryObservationRecord>({ maxRecords })\n      )\n    );\n  }\n\n  /**\n   * {@inheritDoc IMemoryObserver.observe}\n   */\n  public observe(record: IMemoryObservationRecord): Promise<Result<unknown>> {\n    this._buffer.push(record);\n    return Promise.resolve(succeed(record));\n  }\n\n  /**\n   * Returns retained records, oldest-first, narrowed by the supplied criteria.\n   * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.\n   * @returns The matching records, oldest-first.\n   */\n  public query(criteria?: IMemoryObservationQuery): ReadonlyArray<IMemoryObservationRecord> {\n    return this._buffer.query({\n      sinceSeq: criteria?.sinceSeq,\n      limit: criteria?.limit,\n      filter:\n        criteria === undefined ? undefined : (record) => MemoryObservationStore._matches(record, criteria)\n    });\n  }\n\n  /**\n   * Clears all retained records. Does NOT reset\n   * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`\n   * cursor never re-sees a sequence number.\n   */\n  public clear(): void {\n    this._buffer.clear();\n  }\n\n  /**\n   * Tests a record against the non-`seq`/`limit` criteria (those are applied by\n   * the ring buffer itself).\n   * @internal\n   */\n  private static _matches(record: IMemoryObservationRecord, criteria: IMemoryObservationQuery): boolean {\n    if (criteria.since !== undefined && record.timestamp < criteria.since) {\n      return false;\n    }\n    if (criteria.until !== undefined && record.timestamp > criteria.until) {\n      return false;\n    }\n    if (criteria.scope !== undefined && record.scope !== criteria.scope) {\n      return false;\n    }\n    if (criteria.kind !== undefined && record.kind !== criteria.kind) {\n      return false;\n    }\n    if (criteria.phase !== undefined && record.phase !== criteria.phase) {\n      return false;\n    }\n    if (criteria.outcome !== undefined && record.outcome !== criteria.outcome) {\n      return false;\n    }\n    return true;\n  }\n}\n"]}

package/lib/packlets/observe/observer.d.ts

@@ -0,0 +1,110 @@
+import { Result } from '@fgv/ts-utils';
+import { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';
+/**
+ * The store/retriever operation an observation record describes.
+ *
+ * @remarks
+ * `'read'` / `'write'` / `'delete'` are fired post-op by
+ * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when
+ * observers are wired. `'retrieve'` is reserved for retriever-fired
+ * observations; no B2 retriever fires one (a single seq authority per
+ * observation store is the supported topology), so it never appears in B2 but
+ * is part of the vocabulary so a future retriever-firing hook is additive.
+ * @public
+ */
+export type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';
+/**
+ * The outcome of the observed operation.
+ * @public
+ */
+export type MemoryObservationOutcome = 'success' | 'failure';
+/**
+ * A single audit record produced by an observed store (or retriever) operation.
+ *
+ * @remarks
+ * `seq` and `timestamp` are assigned by the firing authority (the store) before
+ * fan-out, so the same record carries the same `seq` across every observer it
+ * lands in. `seq` is strictly increasing per authority, satisfying the
+ * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}
+ * relies on.
+ * @public
+ */
+export interface IMemoryObservationRecord {
+    /**
+     * Monotonic 1-based sequence number assigned by the firing authority, stable
+     * across a store's ring eviction. The ordering / paging key.
+     */
+    readonly seq: number;
+    /** Milliseconds since epoch when the firing authority produced the record. */
+    readonly timestamp: number;
+    /** Which operation this record describes. */
+    readonly phase: MemoryObservationPhase;
+    /** The scope the operation touched, when resolvable. */
+    readonly scope?: MemoryScopeKey;
+    /** The record id the operation touched, when resolvable. */
+    readonly id?: MemoryId;
+    /** The kind the operation targeted, when known. */
+    readonly kind?: Kind;
+    /** Whether the operation succeeded. */
+    readonly outcome: MemoryObservationOutcome;
+    /** Present on failure: the failure `Result`'s message. */
+    readonly error?: string;
+    /** Structured provenance of the write, when the operation carried one. */
+    readonly provenance?: IProvenance;
+    /**
+     * For `'retrieve'` observations: an opaque snapshot of the query that drove
+     * the retrieval. Carried verbatim; never interpreted by the store.
+     */
+    readonly querySnapshot?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Single-method async observer hook. The store fires `observe` once per public
+ * `get` / `put` / `delete` call when observers are wired.
+ *
+ * @remarks
+ * Observer errors never affect the store operation — the store swallows a
+ * failed `Result` or a thrown / rejected `observe`, logging it to the injected
+ * diagnostic logger at `warn`.
+ * @public
+ */
+export interface IMemoryObserver {
+    /**
+     * When `true`, the store dispatches `observe` without awaiting it, so a slow
+     * remote observer (SIEM, network sink) does not extend the store operation's
+     * latency. Defaults to `false` (awaited), which is correct for the cheap
+     * in-memory default {@link MemoryObservationStore}. Errors are swallowed
+     * either way.
+     */
+    readonly fireAndForget?: boolean;
+    /**
+     * Receives a fully-formed observation record.
+     * @param record - The observation record.
+     * @returns A `Result` whose failure is swallowed (logged to the store's
+     * diagnostic logger). A rejected promise is likewise swallowed.
+     */
+    observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;
+}
+/**
+ * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria
+ * are AND-combined.
+ * @public
+ */
+export interface IMemoryObservationQuery {
+    /** Only records with `seq > sinceSeq` (incremental paging cursor). */
+    readonly sinceSeq?: number;
+    /** Return at most this many records — the most-recent N, still oldest-first. */
+    readonly limit?: number;
+    /** Only records with `timestamp >= since`. */
+    readonly since?: number;
+    /** Only records with `timestamp <= until`. */
+    readonly until?: number;
+    /** Only records that touched this scope. */
+    readonly scope?: MemoryScopeKey;
+    /** Only records that targeted this kind. */
+    readonly kind?: Kind;
+    /** Only records of this phase. */
+    readonly phase?: MemoryObservationPhase;
+    /** Only records with this outcome. */
+    readonly outcome?: MemoryObservationOutcome;
+}
+//# sourceMappingURL=observer.d.ts.map

package/lib/packlets/observe/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/packlets/observe/observer.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5D;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;CACrE;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAC;IACxC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;CAC7C"}

package/lib/packlets/observe/observer.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=observer.js.map

package/lib/packlets/observe/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/packlets/observe/observer.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';\n\n/**\n * The store/retriever operation an observation record describes.\n *\n * @remarks\n * `'read'` / `'write'` / `'delete'` are fired post-op by\n * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when\n * observers are wired. `'retrieve'` is reserved for retriever-fired\n * observations; no B2 retriever fires one (a single seq authority per\n * observation store is the supported topology), so it never appears in B2 but\n * is part of the vocabulary so a future retriever-firing hook is additive.\n * @public\n */\nexport type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';\n\n/**\n * The outcome of the observed operation.\n * @public\n */\nexport type MemoryObservationOutcome = 'success' | 'failure';\n\n/**\n * A single audit record produced by an observed store (or retriever) operation.\n *\n * @remarks\n * `seq` and `timestamp` are assigned by the firing authority (the store) before\n * fan-out, so the same record carries the same `seq` across every observer it\n * lands in. `seq` is strictly increasing per authority, satisfying the\n * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}\n * relies on.\n * @public\n */\nexport interface IMemoryObservationRecord {\n  /**\n   * Monotonic 1-based sequence number assigned by the firing authority, stable\n   * across a store's ring eviction. The ordering / paging key.\n   */\n  readonly seq: number;\n  /** Milliseconds since epoch when the firing authority produced the record. */\n  readonly timestamp: number;\n  /** Which operation this record describes. */\n  readonly phase: MemoryObservationPhase;\n  /** The scope the operation touched, when resolvable. */\n  readonly scope?: MemoryScopeKey;\n  /** The record id the operation touched, when resolvable. */\n  readonly id?: MemoryId;\n  /** The kind the operation targeted, when known. */\n  readonly kind?: Kind;\n  /** Whether the operation succeeded. */\n  readonly outcome: MemoryObservationOutcome;\n  /** Present on failure: the failure `Result`'s message. */\n  readonly error?: string;\n  /** Structured provenance of the write, when the operation carried one. */\n  readonly provenance?: IProvenance;\n  /**\n   * For `'retrieve'` observations: an opaque snapshot of the query that drove\n   * the retrieval. Carried verbatim; never interpreted by the store.\n   */\n  readonly querySnapshot?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Single-method async observer hook. The store fires `observe` once per public\n * `get` / `put` / `delete` call when observers are wired.\n *\n * @remarks\n * Observer errors never affect the store operation — the store swallows a\n * failed `Result` or a thrown / rejected `observe`, logging it to the injected\n * diagnostic logger at `warn`.\n * @public\n */\nexport interface IMemoryObserver {\n  /**\n   * When `true`, the store dispatches `observe` without awaiting it, so a slow\n   * remote observer (SIEM, network sink) does not extend the store operation's\n   * latency. Defaults to `false` (awaited), which is correct for the cheap\n   * in-memory default {@link MemoryObservationStore}. Errors are swallowed\n   * either way.\n   */\n  readonly fireAndForget?: boolean;\n  /**\n   * Receives a fully-formed observation record.\n   * @param record - The observation record.\n   * @returns A `Result` whose failure is swallowed (logged to the store's\n   * diagnostic logger). A rejected promise is likewise swallowed.\n   */\n  observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;\n}\n\n/**\n * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria\n * are AND-combined.\n * @public\n */\nexport interface IMemoryObservationQuery {\n  /** Only records with `seq > sinceSeq` (incremental paging cursor). */\n  readonly sinceSeq?: number;\n  /** Return at most this many records — the most-recent N, still oldest-first. */\n  readonly limit?: number;\n  /** Only records with `timestamp >= since`. */\n  readonly since?: number;\n  /** Only records with `timestamp <= until`. */\n  readonly until?: number;\n  /** Only records that touched this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Only records that targeted this kind. */\n  readonly kind?: Kind;\n  /** Only records of this phase. */\n  readonly phase?: MemoryObservationPhase;\n  /** Only records with this outcome. */\n  readonly outcome?: MemoryObservationOutcome;\n}\n"]}