@fgv/ts-agent-memory 5.1.0-50 → 5.1.0-52

package/dist/packlets/retrieve/fragmentSemanticRetriever.js

@@ -2,7 +2,8 @@
  * Copyright (c) 2026 Erik Fortune
  * SPDX-License-Identifier: MIT
  */
-import { fail, succeed } from '@fgv/ts-utils';
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { Convert } from '../types';
 /**
  * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
  * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
@@ -10,6 +11,26 @@ import { fail, succeed } from '@fgv/ts-utils';
  * @public
  */
 export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';
+/**
+ * The loud-degradation message returned when a query carries a record narrowing but
+ * no {@link IIdentityResolver} is wired to resolve it.
+ *
+ * @remarks
+ * Deliberately a `Failure` rather than a silently-global search: answering a scoped
+ * question with an unscoped result is the failure this narrowing exists to remove.
+ * @public
+ */
+export const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE = 'fragment recall: a record narrowing was supplied but no identity resolver is wired; pass one to FragmentSemanticRetriever.create';
+/**
+ * The message returned when exactly one of `entityId` / `kind` is supplied.
+ *
+ * @remarks
+ * They travel together because `kind` is what selects the identity codec, and the
+ * codec is what makes the resolution unambiguous. One without the other is not a
+ * partial narrowing that could be honored best-effort — it is not a narrowing at all.
+ * @public
+ */
+export const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE = 'fragment recall: `entityId` and `kind` must be supplied together — `kind` selects the identity codec that resolves the narrowing';
 /**
  * The sub-document semantic-search retriever — the "discovery" half of a
  * search-then-read contract. It embeds a fragment query, queries the
@@ -35,16 +56,26 @@ export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment i
  * @public
  */
 export class FragmentSemanticRetriever {
-    constructor(backend) {
+    constructor(backend, identityResolver) {
         this._backend = backend;
+        this._identityResolver = identityResolver;
     }
     /** What this retriever can do given its wiring. */
     get capabilities() {
         return { supportsFragmentRecall: this._backend !== undefined };
     }
-    /** Family-convention factory. */
+    /**
+     * Family-convention factory.
+     *
+     * @param params - `backend` wires fragment recall itself. `identityResolver`
+     * resolves a query's `(kind, entityId)` narrowing to a storage address;
+     * `IMemoryStore` implements it, so the usual wiring is
+     * `{ backend, identityResolver: store }`. It is optional because an unscoped
+     * fragment search needs nothing to resolve — but a query that *does* carry a
+     * narrowing fails loudly without it rather than quietly searching everything.
+     */
     static create(params) {
-        return succeed(new FragmentSemanticRetriever(params.backend));
+        return succeed(new FragmentSemanticRetriever(params.backend, params.identityResolver));
     }
     /**
      * Embed `query.semantic`, query the fragment index, and return the per-fragment
@@ -55,6 +86,13 @@ export class FragmentSemanticRetriever {
             return fail(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);
         }
         const backend = this._backend;
+        // Resolve the narrowing FIRST. It is synchronous, local, and cheap, while
+        // `embedQuery` is typically a paid network round trip — so a typo'd `kind`, a
+        // missing resolver, or a half-supplied narrowing should cost nothing.
+        const options = this._resolveOptions(query);
+        if (options.isFailure()) {
+            return fail(options.message);
+        }
         // Consumer-supplied hooks may throw; normalize both a returned `fail` and a
         // rejection into a single `fragment recall: <label> failed` Failure so
         // `retrieve` always honors its `Promise<Result<...>>` contract.
@@ -62,7 +100,58 @@ export class FragmentSemanticRetriever {
         if (embedded.isFailure()) {
             return fail(embedded.message);
         }
-        return FragmentSemanticRetriever._callBackend('fragment query', () => { var _a; return backend.fragmentIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10, query.maxPerRecord); });
+        return FragmentSemanticRetriever._callBackend('fragment query', () => { var _a; return backend.fragmentIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10, options.value); });
+    }
+    /**
+     * Turn the query's consumer-facing narrowing into the storage-address narrowing
+     * the index understands.
+     *
+     * @remarks
+     * `kind` selects the identity codec and the codec computes the record's storage
+     * address, so this is a deterministic resolution rather than a search —
+     * which is what makes a colliding `entityId` across kinds a non-issue.
+     *
+     * A **versioned** kind resolves to the entity's own subtree scope and deliberately
+     * carries no `id`, so the narrowing covers every version of the entity — including
+     * superseded ones, which are invalidated but never pruned from the index. A
+     * non-versioned kind resolves to exactly one record.
+     */
+    _resolveOptions(query) {
+        const { entityId, kind, maxPerRecord } = query;
+        if (entityId === undefined && kind === undefined) {
+            return succeed({ maxPerRecord });
+        }
+        if (entityId === undefined || kind === undefined) {
+            return fail(FRAGMENT_NARROWING_INCOMPLETE_MESSAGE);
+        }
+        if (this._identityResolver === undefined) {
+            return fail(FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE);
+        }
+        const resolver = this._identityResolver;
+        // `identityResolver` is a consumer-injectable seam like the two backend hooks,
+        // so a throw has to become a `Failure` here rather than escaping `retrieve()`
+        // and breaking its `Promise<Result<...>>` contract. `captureResult` yields a
+        // nested `Result`, which the identity `onSuccess` flattens.
+        return captureResult(() => resolver.resolveIdentity(kind, entityId))
+            .onSuccess((resolved) => resolved)
+            .withErrorFormat((msg) => `fragment recall: cannot resolve '${kind}'/'${entityId}': ${msg}`)
+            .onSuccess((address) => {
+            // A versioned kind's every version lives under the entity subtree the
+            // codec returned, so omitting `id` is what makes the narrowing mean
+            // "this entity" rather than "one of its versions".
+            if (address.isVersioned) {
+                return succeed({ maxPerRecord, scope: address.scope });
+            }
+            // `idStem` is a plain `string` on the codec result, but a `MemoryId` IS the
+            // filename stem by contract and `Convert.memoryId` is what enforces that —
+            // so validate rather than assert. A resolver that returned a path-unsafe
+            // stem could otherwise smuggle it into the index query, where it would
+            // match nothing and look like an empty result rather than a caller bug.
+            return Convert.memoryId
+                .convert(address.idStem)
+                .withErrorFormat((msg) => `fragment recall: '${kind}'/'${entityId}' resolved to an unusable record id: ${msg}`)
+                .onSuccess((id) => succeed({ maxPerRecord, scope: address.scope, id }));
+        });
     }
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`

package/dist/packlets/retrieve/fragmentSemanticRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"fragmentSemanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAItD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAC5C,6GAA6G,CAAC;AA0ChH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,yBAAyB;IAGpC,YAAoB,OAA6C;QAC/D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,mDAAmD;IACnD,IAAW,YAAY;QACrB,OAAO,EAAE,sBAAsB,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;IACjE,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,MAEpB;QACC,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAqB;QACzC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACjD,CAAC;QACD,MAAM,OAAO,GAA6B,IAAI,CAAC,QAAQ,CAAC;QACxD,4EAA4E;QAC5E,uEAAuE;QACvE,gEAAgE;QAChE,MAAM,QAAQ,GAAyB,MAAM,yBAAyB,CAAC,YAAY,CACjF,iBAAiB,EACjB,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CACzC,CAAC;QACF,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,yBAAyB,CAAC,YAAY,CAAC,gBAAgB,EAAE,GAAG,EAAE,WACnE,OAAA,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAA,KAAK,CAAC,IAAI,mCAAI,EAAE,EAAE,KAAK,CAAC,YAAY,CAAC,CAAA,EAAA,CAClF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,KAAK,CAAC,YAAY,CAAI,KAAa,EAAE,EAA4B;QAC9E,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,KAAK,YAAY,GAAG,EAAE,CAAC,CAAC;QAC3F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,oBAAoB,KAAK,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IFragmentVectorIndex, IVectorQueryHit } from '../vector';\nimport { QueryEmbedder } from './semanticRetriever';\n\n/**\n * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a\n * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is\n * wired — the discovery surface NEVER answers a fragment query with a silent empty.\n * @public\n */\nexport const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string =\n  'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';\n\n/**\n * The fragment backend wired into a {@link FragmentSemanticRetriever}: the fragment\n * index to query and the embedder that turns the query text into a vector. Both are\n * required together — a fragment index is useless without a way to embed the query.\n * @public\n */\nexport interface IFragmentSemanticBackend {\n  /** The fragment-granular vector index to query. */\n  readonly fragmentIndex: IFragmentVectorIndex;\n  /** Turns the query text into a vector. */\n  readonly embedQuery: QueryEmbedder;\n}\n\n/**\n * A sub-document semantic-search request: the natural-language `semantic` text to\n * match, an optional `topK` result cap (default 10), and an optional\n * `maxPerRecord` cap that keeps one long document from monopolizing the result.\n * @public\n */\nexport interface IFragmentQuery {\n  /** The natural-language text to embed and match against stored fragments. */\n  readonly semantic: string;\n  /** Maximum number of fragment hits to return. Defaults to 10. */\n  readonly topK?: number;\n  /**\n   * Maximum number of fragments any single record may contribute to the result.\n   * Applied during selection (before the `topK` cut). Omit for uncapped.\n   */\n  readonly maxPerRecord?: number;\n}\n\n/**\n * What a {@link FragmentSemanticRetriever} can do given its wiring.\n * @public\n */\nexport interface IFragmentRetrieverCapabilities {\n  /** `true` when a fragment backend is wired and fragment recall is operational. */\n  readonly supportsFragmentRecall: boolean;\n}\n\n/**\n * The sub-document semantic-search retriever — the \"discovery\" half of a\n * search-then-read contract. It embeds a fragment query, queries the\n * {@link IFragmentVectorIndex}, and returns the raw per-fragment\n * {@link IVectorQueryHit | hits} (each carrying a record `target` AND whichever of\n * `locator` / `fragmentId` the stored fragment was indexed with), NOT resolved\n * records: the consumer re-reads each record and resolves the fragment on its own\n * read side. Note the `locator` span is advisory — see {@link IFragmentLocator}; it\n * is not a slice guaranteed to reproduce the fragment's text.\n *\n * @remarks\n * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and\n * returns records; fragment discovery is fragment-granular and returns fragment\n * identities. Keeping it a distinct surface matches the consumer contract (memory\n * stays record-granular; sub-document knowledge uses a separate fragment index) and\n * avoids overloading the record retriever's return type with identity fields that\n * only make sense here.\n *\n * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment\n * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER\n * returns a silent empty. A consumer-supplied backend that rejects (throws) is\n * normalized into a `Failure`.\n * @public\n */\nexport class FragmentSemanticRetriever {\n  private readonly _backend: IFragmentSemanticBackend | undefined;\n\n  private constructor(backend: IFragmentSemanticBackend | undefined) {\n    this._backend = backend;\n  }\n\n  /** What this retriever can do given its wiring. */\n  public get capabilities(): IFragmentRetrieverCapabilities {\n    return { supportsFragmentRecall: this._backend !== undefined };\n  }\n\n  /** Family-convention factory. */\n  public static create(params: {\n    readonly backend?: IFragmentSemanticBackend;\n  }): Result<FragmentSemanticRetriever> {\n    return succeed(new FragmentSemanticRetriever(params.backend));\n  }\n\n  /**\n   * Embed `query.semantic`, query the fragment index, and return the per-fragment\n   * hits in descending score order. Fails loudly when no backend is wired.\n   */\n  public async retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (this._backend === undefined) {\n      return fail(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);\n    }\n    const backend: IFragmentSemanticBackend = this._backend;\n    // Consumer-supplied hooks may throw; normalize both a returned `fail` and a\n    // rejection into a single `fragment recall: <label> failed` Failure so\n    // `retrieve` always honors its `Promise<Result<...>>` contract.\n    const embedded: Result<Float32Array> = await FragmentSemanticRetriever._callBackend(\n      'query embedding',\n      () => backend.embedQuery(query.semantic)\n    );\n    if (embedded.isFailure()) {\n      return fail(embedded.message);\n    }\n    return FragmentSemanticRetriever._callBackend('fragment query', () =>\n      backend.fragmentIndex.query(embedded.value, query.topK ?? 10, query.maxPerRecord)\n    );\n  }\n\n  /**\n   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`\n   * and a thrown/rejected promise into a single `fragment recall: <label> failed`\n   * `Failure`.\n   */\n  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {\n    try {\n      return (await op()).withErrorFormat((msg) => `fragment recall: ${label} failed: ${msg}`);\n    } catch (err) {\n      return fail(`fragment recall: ${label} failed: ${String(err)}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"fragmentSemanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport { Convert, EntityId, IIdentityCodecResult, IIdentityResolver, Kind, MemoryId } from '../types';\nimport { IFragmentQueryOptions, IFragmentVectorIndex, IVectorQueryHit } from '../vector';\nimport { QueryEmbedder } from './semanticRetriever';\n\n/**\n * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a\n * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is\n * wired — the discovery surface NEVER answers a fragment query with a silent empty.\n * @public\n */\nexport const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string =\n  'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';\n\n/**\n * The loud-degradation message returned when a query carries a record narrowing but\n * no {@link IIdentityResolver} is wired to resolve it.\n *\n * @remarks\n * Deliberately a `Failure` rather than a silently-global search: answering a scoped\n * question with an unscoped result is the failure this narrowing exists to remove.\n * @public\n */\nexport const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE: string =\n  'fragment recall: a record narrowing was supplied but no identity resolver is wired; pass one to FragmentSemanticRetriever.create';\n\n/**\n * The message returned when exactly one of `entityId` / `kind` is supplied.\n *\n * @remarks\n * They travel together because `kind` is what selects the identity codec, and the\n * codec is what makes the resolution unambiguous. One without the other is not a\n * partial narrowing that could be honored best-effort — it is not a narrowing at all.\n * @public\n */\nexport const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE: string =\n  'fragment recall: `entityId` and `kind` must be supplied together — `kind` selects the identity codec that resolves the narrowing';\n\n/**\n * The fragment backend wired into a {@link FragmentSemanticRetriever}: the fragment\n * index to query and the embedder that turns the query text into a vector. Both are\n * required together — a fragment index is useless without a way to embed the query.\n * @public\n */\nexport interface IFragmentSemanticBackend {\n  /** The fragment-granular vector index to query. */\n  readonly fragmentIndex: IFragmentVectorIndex;\n  /** Turns the query text into a vector. */\n  readonly embedQuery: QueryEmbedder;\n}\n\n/**\n * A sub-document semantic-search request: the natural-language `semantic` text to\n * match, an optional `topK` result cap (default 10), and an optional\n * `maxPerRecord` cap that keeps one long document from monopolizing the result.\n * @public\n */\nexport interface IFragmentQuery {\n  /** The natural-language text to embed and match against stored fragments. */\n  readonly semantic: string;\n  /** Maximum number of fragment hits to return. Defaults to 10. */\n  readonly topK?: number;\n  /**\n   * Maximum number of fragments any single record may contribute to the result.\n   * Applied during selection (before the `topK` cut). Omit for uncapped.\n   */\n  readonly maxPerRecord?: number;\n\n  /**\n   * Narrow the search to one record's fragments: the consumer-supplied domain key\n   * of the record to search within. **Must be supplied with\n   * {@link IFragmentQuery.kind}.**\n   *\n   * @remarks\n   * The narrowing is applied **during selection, before the `topK` cut**, so the\n   * `topK` you ask for is the `topK` you get. Filtering a global result afterwards\n   * is not equivalent: it truncates to `topK` across every record first, so a scoped\n   * search would come back short whenever other records outscored this one's\n   * fragments.\n   *\n   * For a versioned kind this narrows to **every version of the entity** — literally\n   * every version, superseded ones included, because invalidation stamps `invalid_at`\n   * without pruning that version's fragments. Nothing on a hit distinguishes a\n   * current fragment from a historical one. That matches the record-granular vector\n   * lane; it is not currency filtering.\n   */\n  readonly entityId?: EntityId;\n\n  /**\n   * The kind of the record named by {@link IFragmentQuery.entityId}. **Must be\n   * supplied with it.**\n   *\n   * @remarks\n   * This is not decoration and not a filter: `kind` **selects the identity codec**,\n   * and the codec computes the storage address. An `EntityId` promises no uniqueness\n   * beyond a scope — the same id under two kinds is the ordinary case, not a\n   * pathological one — so without `kind` the resolution is ambiguous, and with it\n   * ambiguity is structurally impossible.\n   */\n  readonly kind?: Kind;\n}\n\n/**\n * What a {@link FragmentSemanticRetriever} can do given its wiring.\n * @public\n */\nexport interface IFragmentRetrieverCapabilities {\n  /** `true` when a fragment backend is wired and fragment recall is operational. */\n  readonly supportsFragmentRecall: boolean;\n}\n\n/**\n * The sub-document semantic-search retriever — the \"discovery\" half of a\n * search-then-read contract. It embeds a fragment query, queries the\n * {@link IFragmentVectorIndex}, and returns the raw per-fragment\n * {@link IVectorQueryHit | hits} (each carrying a record `target` AND whichever of\n * `locator` / `fragmentId` the stored fragment was indexed with), NOT resolved\n * records: the consumer re-reads each record and resolves the fragment on its own\n * read side. Note the `locator` span is advisory — see {@link IFragmentLocator}; it\n * is not a slice guaranteed to reproduce the fragment's text.\n *\n * @remarks\n * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and\n * returns records; fragment discovery is fragment-granular and returns fragment\n * identities. Keeping it a distinct surface matches the consumer contract (memory\n * stays record-granular; sub-document knowledge uses a separate fragment index) and\n * avoids overloading the record retriever's return type with identity fields that\n * only make sense here.\n *\n * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment\n * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER\n * returns a silent empty. A consumer-supplied backend that rejects (throws) is\n * normalized into a `Failure`.\n * @public\n */\nexport class FragmentSemanticRetriever {\n  private readonly _backend: IFragmentSemanticBackend | undefined;\n  private readonly _identityResolver: IIdentityResolver | undefined;\n\n  private constructor(\n    backend: IFragmentSemanticBackend | undefined,\n    identityResolver: IIdentityResolver | undefined\n  ) {\n    this._backend = backend;\n    this._identityResolver = identityResolver;\n  }\n\n  /** What this retriever can do given its wiring. */\n  public get capabilities(): IFragmentRetrieverCapabilities {\n    return { supportsFragmentRecall: this._backend !== undefined };\n  }\n\n  /**\n   * Family-convention factory.\n   *\n   * @param params - `backend` wires fragment recall itself. `identityResolver`\n   * resolves a query's `(kind, entityId)` narrowing to a storage address;\n   * `IMemoryStore` implements it, so the usual wiring is\n   * `{ backend, identityResolver: store }`. It is optional because an unscoped\n   * fragment search needs nothing to resolve — but a query that *does* carry a\n   * narrowing fails loudly without it rather than quietly searching everything.\n   */\n  public static create(params: {\n    readonly backend?: IFragmentSemanticBackend;\n    readonly identityResolver?: IIdentityResolver;\n  }): Result<FragmentSemanticRetriever> {\n    return succeed(new FragmentSemanticRetriever(params.backend, params.identityResolver));\n  }\n\n  /**\n   * Embed `query.semantic`, query the fragment index, and return the per-fragment\n   * hits in descending score order. Fails loudly when no backend is wired.\n   */\n  public async retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (this._backend === undefined) {\n      return fail(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);\n    }\n    const backend: IFragmentSemanticBackend = this._backend;\n    // Resolve the narrowing FIRST. It is synchronous, local, and cheap, while\n    // `embedQuery` is typically a paid network round trip — so a typo'd `kind`, a\n    // missing resolver, or a half-supplied narrowing should cost nothing.\n    const options: Result<IFragmentQueryOptions> = this._resolveOptions(query);\n    if (options.isFailure()) {\n      return fail(options.message);\n    }\n    // Consumer-supplied hooks may throw; normalize both a returned `fail` and a\n    // rejection into a single `fragment recall: <label> failed` Failure so\n    // `retrieve` always honors its `Promise<Result<...>>` contract.\n    const embedded: Result<Float32Array> = await FragmentSemanticRetriever._callBackend(\n      'query embedding',\n      () => backend.embedQuery(query.semantic)\n    );\n    if (embedded.isFailure()) {\n      return fail(embedded.message);\n    }\n    return FragmentSemanticRetriever._callBackend('fragment query', () =>\n      backend.fragmentIndex.query(embedded.value, query.topK ?? 10, options.value)\n    );\n  }\n\n  /**\n   * Turn the query's consumer-facing narrowing into the storage-address narrowing\n   * the index understands.\n   *\n   * @remarks\n   * `kind` selects the identity codec and the codec computes the record's storage\n   * address, so this is a deterministic resolution rather than a search —\n   * which is what makes a colliding `entityId` across kinds a non-issue.\n   *\n   * A **versioned** kind resolves to the entity's own subtree scope and deliberately\n   * carries no `id`, so the narrowing covers every version of the entity — including\n   * superseded ones, which are invalidated but never pruned from the index. A\n   * non-versioned kind resolves to exactly one record.\n   */\n  private _resolveOptions(query: IFragmentQuery): Result<IFragmentQueryOptions> {\n    const { entityId, kind, maxPerRecord } = query;\n    if (entityId === undefined && kind === undefined) {\n      return succeed({ maxPerRecord });\n    }\n    if (entityId === undefined || kind === undefined) {\n      return fail(FRAGMENT_NARROWING_INCOMPLETE_MESSAGE);\n    }\n    if (this._identityResolver === undefined) {\n      return fail(FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE);\n    }\n    const resolver: IIdentityResolver = this._identityResolver;\n    // `identityResolver` is a consumer-injectable seam like the two backend hooks,\n    // so a throw has to become a `Failure` here rather than escaping `retrieve()`\n    // and breaking its `Promise<Result<...>>` contract. `captureResult` yields a\n    // nested `Result`, which the identity `onSuccess` flattens.\n    return captureResult(() => resolver.resolveIdentity(kind, entityId))\n      .onSuccess((resolved: Result<IIdentityCodecResult>) => resolved)\n      .withErrorFormat((msg) => `fragment recall: cannot resolve '${kind}'/'${entityId}': ${msg}`)\n      .onSuccess((address: IIdentityCodecResult) => {\n        // A versioned kind's every version lives under the entity subtree the\n        // codec returned, so omitting `id` is what makes the narrowing mean\n        // \"this entity\" rather than \"one of its versions\".\n        if (address.isVersioned) {\n          return succeed({ maxPerRecord, scope: address.scope });\n        }\n        // `idStem` is a plain `string` on the codec result, but a `MemoryId` IS the\n        // filename stem by contract and `Convert.memoryId` is what enforces that —\n        // so validate rather than assert. A resolver that returned a path-unsafe\n        // stem could otherwise smuggle it into the index query, where it would\n        // match nothing and look like an empty result rather than a caller bug.\n        return Convert.memoryId\n          .convert(address.idStem)\n          .withErrorFormat(\n            (msg) => `fragment recall: '${kind}'/'${entityId}' resolved to an unusable record id: ${msg}`\n          )\n          .onSuccess((id: MemoryId) => succeed({ maxPerRecord, scope: address.scope, id }));\n      });\n  }\n\n  /**\n   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`\n   * and a thrown/rejected promise into a single `fragment recall: <label> failed`\n   * `Failure`.\n   */\n  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {\n    try {\n      return (await op()).withErrorFormat((msg) => `fragment recall: ${label} failed: ${msg}`);\n    } catch (err) {\n      return fail(`fragment recall: ${label} failed: ${String(err)}`);\n    }\n  }\n}\n"]}

package/dist/packlets/store/fileTreeMemoryStore.js

@@ -3,11 +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, verifyOccupantKind } from './storeIdentity';
+import { deleteRecordFile, resolveScopeDir, writeRecordFile } from './storeFileAccess';
 import { reconcileVectors } from './storeReconcile';
 import { MemoryIndex } from '../index';
 import { defaultMemoryScopeEncoding } from './scopeEncoding';
@@ -119,7 +120,7 @@ export class FileTreeMemoryStore {
     /** {@inheritDoc IMemoryStore.get} */
     async get(kind, entityId) {
         var _a;
-        const result = this._codecFor(kind).onSuccess((codec) => codec.encode(entityId).onSuccess((addr) => {
+        const result = codecFor(this._codecs, this._defaultCodec, kind).onSuccess((codec) => codec.encode(entityId).onSuccess((addr) => {
             if (addr.isVersioned) {
                 if (!isTemporalIdentityCodec(codec)) {
                     return fail(`memory get '${entityId}': codec for versioned kind '${kind}' does not implement the temporal codec interface`);
@@ -128,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',
@@ -225,6 +226,13 @@ export class FileTreeMemoryStore {
     resolveRecord(scope, id) {
         return this._readRecord(scope, id);
     }
+    _codec(kind) {
+        return codecFor(this._codecs, this._defaultCodec, kind);
+    }
+    /** {@inheritDoc IIdentityResolver.resolveIdentity} */
+    resolveIdentity(kind, entityId) {
+        return resolveIdentity(this._codecs, this._defaultCodec, kind, entityId);
+    }
     /**
      * Materialize a selected set of entries into records, dropping any that have
      * vanished since selection.
@@ -414,7 +422,7 @@ export class FileTreeMemoryStore {
     }
     /** Resolve a scope for an observation, best-effort (undefined when unresolvable). */
     _scopeBestEffort(kind, entityId) {
-        return this._codecFor(kind)
+        return this._codec(kind)
             .onSuccess((codec) => codec.encode(entityId))
             .onSuccess((addr) => succeed(addr.scope))
             .orDefault();
@@ -432,7 +440,7 @@ export class FileTreeMemoryStore {
         return this._registry
             .convert(envelope.kind, body)
             .withErrorFormat((msg) => `memory put '${envelope.id}': invalid body: ${msg}`)
-            .onSuccess(() => this._codecFor(envelope.kind))
+            .onSuccess(() => this._codec(envelope.kind))
             .thenOnSuccess((codec) => codec.encode(envelope.entityId).thenOnSuccess((addr) => {
             if (addr.isVersioned) {
                 if (!isTemporalIdentityCodec(codec)) {
@@ -482,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
@@ -608,19 +616,19 @@ 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));
     }
     async _deleteLocked(kind, entityId) {
-        return this._codecFor(kind).thenOnSuccess((codec) => codec.encode(entityId).thenOnSuccess((addr) => {
+        return this._codec(kind).thenOnSuccess((codec) => codec.encode(entityId).thenOnSuccess((addr) => {
             if (addr.isVersioned) {
                 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);
         }));
     }
     /**
@@ -628,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 });
@@ -650,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
@@ -660,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
@@ -696,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);
         }
@@ -825,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);
         }
@@ -849,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));
         });
@@ -999,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`);
@@ -1074,14 +1082,6 @@ export class FileTreeMemoryStore {
             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;
-        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;
@@ -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));
             });
         });
     }
@@ -1130,95 +1131,7 @@ export class FileTreeMemoryStore {
      * verbatim downstream (e.g. merge-into re-addressing). Cross-check it here.
      */
     _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).onSuccess(() => codec.decode(scope, file.baseName)))
-            .withErrorFormat((msg) => `memory file '${file.absolutePath}': ${msg}`)
-            .onSuccess((decodedEntityId) => {
-            if (decodedEntityId !== record.envelope.entityId) {
-                return fail(`memory file '${file.absolutePath}': envelope entityId '${record.envelope.entityId}' does not match scope-derived entityId '${decodedEntityId}'`);
-            }
-            return 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));
-            });
-        });
+        return verifyLoadedIdentity(this._codec(record.envelope.kind), scope, file, record);
     }
     /**
      * Walk the FileTree once and rebuild the index. Also resumes the `seq`