@fgv/ts-agent-memory 5.1.0-36

package/dist/packlets/types/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export * from './ids';
+export * from './envelope';
+export * from './filenameSafety';
+export * from './identityCodec';
+export * from './writePolicy';
+//# sourceMappingURL=index.js.map

package/dist/packlets/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './ids';\nexport * from './envelope';\nexport * from './filenameSafety';\nexport * from './identityCodec';\nexport * from './writePolicy';\n"]}

package/dist/packlets/types/writePolicy.js

@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { fail, succeed } from '@fgv/ts-utils';
+import { JsonEditor } from '@fgv/ts-json';
+/**
+ * The default {@link DedupScope} applied when a policy does not declare one.
+ * Entity-scoped dedup is the safe default — it never silently collapses two
+ * distinct entities with coincidentally-identical content.
+ * @public
+ */
+export const DEFAULT_DEDUP_SCOPE = 'entity';
+/**
+ * RFC-7386-compliant merge options for {@link IWritePolicy.applyUpdate}.
+ *
+ * @remarks
+ * Phase-A verification (design-lock §5.1) confirmed `@fgv/ts-json`'s
+ * `JsonEditor` diverges from RFC-7386 under its defaults on two axes —
+ * `nullAsDelete` defaults `false` and `arrayMergeBehavior` defaults
+ * `'append'`. Both are corrected here via the existing option surface, so the
+ * primitive is composed (not extended, not hand-rolled).
+ */
+const MERGE_PATCH_OPTIONS = {
+    merge: {
+        nullAsDelete: true,
+        arrayMergeBehavior: 'replace'
+    }
+};
+/**
+ * Last-write-wins write policy for the knowledge kind family. Admission
+ * always accepts (no cap, no cull); updates apply an RFC-7386 merge patch
+ * restricted to the knowledge mutable surface.
+ *
+ * @remarks
+ * **Merge-surface pin (resolves design-lock §5.3's body-vs-envelope muddle).**
+ * The declared `mutableFields` span both axes of a record: `body` is the
+ * per-kind body, while `tags` / `links` / `provenance` / `embeddingRef` live
+ * on the {@link IMemoryEnvelope}. `applyUpdate` projects exactly those fields
+ * — each read from its canonical location — into a single record-level JSON
+ * view, runs the merge over that view, then rebuilds a coherent record. The
+ * identity and transaction-time envelope fields (`id`, `entityId`, `kind`,
+ * `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are
+ * preserved verbatim; the store stamps `updated` / `seq` on write.
+ * @public
+ */
+export class KnowledgeLwwPolicy {
+    constructor(cloneEditor, mergeEditor) {
+        /**
+         * The knowledge mutable surface: the body plus the envelope metadata a
+         * consumer may revise without minting a new entity.
+         */
+        this.mutableFields = [
+            'body',
+            'tags',
+            'links',
+            'provenance',
+            'embeddingRef'
+        ];
+        /**
+         * Knowledge dedups scope-wide: an identical `{ kind, body, links }` triple
+         * anywhere in the `knowledge` scope — even under a different `docId` — is a
+         * no-op. Declared explicitly so the B1 content-dedup behavior (and its tests)
+         * are unchanged by the {@link DedupScope} amendment.
+         */
+        this.dedupScope = 'content';
+        this._cloneEditor = cloneEditor;
+        this._mergeEditor = mergeEditor;
+    }
+    /**
+     * Family-convention factory. Constructs the shared `JsonEditor` instances
+     * (one for cloning, one for the RFC-7386 merge), both with the template /
+     * conditional / multivalue / reference rules disabled (empty rules array).
+     */
+    static create() {
+        return JsonEditor.create({}, []).onSuccess((cloneEditor) => JsonEditor.create(MERGE_PATCH_OPTIONS, []).onSuccess((mergeEditor) => succeed(new KnowledgeLwwPolicy(cloneEditor, mergeEditor))));
+    }
+    /** {@inheritDoc IWritePolicy.admit} */
+    admit(__incoming, __existing) {
+        // Last-write-wins: always accept. No cap, no cull.
+        return succeed({ decision: 'accept' });
+    }
+    /** {@inheritDoc IWritePolicy.applyUpdate} */
+    applyUpdate(existing, patch) {
+        // Project the mutable fields into a single record-level view, each sourced
+        // from its canonical location. `embeddingRef` is omitted when `undefined`
+        // (the editor rejects undefined property values).
+        const view = {
+            body: existing.body,
+            tags: existing.envelope.tags,
+            links: existing.envelope.links,
+            provenance: existing.envelope.provenance
+        };
+        if (existing.envelope.embeddingRef !== undefined) {
+            view.embeddingRef = existing.envelope.embeddingRef;
+        }
+        // Restrict the incoming patch to the declared mutable fields; out-of-scope
+        // keys are never applied (the store enforces the same constraint).
+        const scopedPatch = {};
+        for (const field of this.mutableFields) {
+            if (field in patch) {
+                scopedPatch[field] = patch[field];
+            }
+        }
+        // Clone the view (no null-deletion), then apply the RFC-7386 merge patch
+        // onto the clone so the persisted record is never mutated in place.
+        return this._cloneEditor
+            .mergeObjectInPlace({}, view)
+            .onSuccess((clone) => this._mergeEditor.mergeObjectInPlace(clone, scopedPatch))
+            .onSuccess((merged) => this._rebuild(existing, merged));
+    }
+    /**
+     * Reassemble a record from the merged mutable view. `body` / `tags` /
+     * `links` / `provenance` are required and may not be deleted by a patch.
+     * `embeddingRef` is optional: when it is absent from the merged view —
+     * because the existing record never carried it OR a `null` patch deleted it
+     * (RFC-7386) — it is restored as `undefined` (absent), NOT `null`. This keeps
+     * an originally-absent `embeddingRef` from silently flipping to `null` on an
+     * unrelated update, so the field round-trips hash-stably through the store's
+     * content-hash recomputation.
+     */
+    _rebuild(existing, merged) {
+        const required = ['body', 'tags', 'links', 'provenance'];
+        const missing = required.filter((field) => !(field in merged));
+        if (missing.length > 0) {
+            return fail(`knowledge LWW: merge patch may not delete required field(s): ${missing.join(', ')}`);
+        }
+        // The merged values are JSON projections of the already-validated typed
+        // record; restore the domain types. (The types packlet cannot import the
+        // converters packlet without a cycle, so these are structural restorations
+        // of fields the merge preserved, not fresh untrusted input.)
+        const envelope = Object.assign(Object.assign({}, existing.envelope), { tags: merged.tags, links: merged.links, provenance: merged.provenance, embeddingRef: 'embeddingRef' in merged ? merged.embeddingRef : undefined });
+        return succeed({ envelope, body: merged.body });
+    }
+}
+/**
+ * The record-level fields a {@link MemoryCapCullPolicy} merge-patch may project,
+ * mapped to their canonical location on a record. Mirrors the store's
+ * mutable-field accessor vocabulary; a declared mutable field outside this set
+ * is inert (the store cannot project it either).
+ */
+const CAP_CULL_FIELD_READERS = new Map([
+    ['body', (r) => r.body],
+    ['tags', (r) => r.envelope.tags],
+    ['links', (r) => r.envelope.links],
+    ['provenance', (r) => r.envelope.provenance],
+    ['embeddingRef', (r) => r.envelope.embeddingRef]
+]);
+/** The record-level mutable fields that may never be deleted by a merge patch. */
+const CAP_CULL_REQUIRED_FIELDS = new Set([
+    'body',
+    'tags',
+    'links',
+    'provenance'
+]);
+/**
+ * Bounded-ring write policy for the experience (memory) kind families.
+ * Admission accepts until `maxRecords` is reached, then evicts the oldest
+ * record(s) by `created` ascending (design-lock §5.3); updates apply the same
+ * RFC-7386 merge patch as {@link KnowledgeLwwPolicy}, restricted to the declared
+ * {@link IMemoryCapCullPolicyParams.mutableFields | mutableFields}.
+ *
+ * @remarks
+ * - **Dedup scope.** Declares `dedupScope: 'entity'` — two distinct memory
+ *   entities (e.g. `turn-5` / `turn-9`) with identical `{ kind, body, links }`
+ *   never collapse; only an identical re-put of the SAME entity is a no-op.
+ * - **Eviction boundary.** `admit` only DECIDES (returns the `MemoryId`s to
+ *   evict); the store executes the file deletions and index patches. The
+ *   `existing` cohort the cap counts against is whatever the store supplies to
+ *   `admit`.
+ * @public
+ */
+export class MemoryCapCullPolicy {
+    constructor(params, cloneEditor, mergeEditor) {
+        /** Experience kinds dedup per-entity (see the class remarks). */
+        this.dedupScope = 'entity';
+        this.mutableFields = params.mutableFields;
+        this._maxRecords = params.maxRecords;
+        this._cloneEditor = cloneEditor;
+        this._mergeEditor = mergeEditor;
+    }
+    /**
+     * Family-convention factory. Constructs the shared `JsonEditor` instances
+     * (one for cloning, one for the RFC-7386 merge) with the same merge config as
+     * {@link KnowledgeLwwPolicy} (`nullAsDelete` true, `arrayMergeBehavior`
+     * `'replace'`, rules disabled).
+     */
+    static create(params) {
+        return JsonEditor.create({}, []).onSuccess((cloneEditor) => JsonEditor.create(MERGE_PATCH_OPTIONS, []).onSuccess((mergeEditor) => succeed(new MemoryCapCullPolicy(params, cloneEditor, mergeEditor))));
+    }
+    /** {@inheritDoc IWritePolicy.admit} */
+    admit(__incoming, existing) {
+        if (this._maxRecords === undefined || existing.length < this._maxRecords) {
+            return succeed({ decision: 'accept' });
+        }
+        // Cap reached: evict the oldest by `created` ascending so the post-write
+        // count is exactly `maxRecords` (existing.length - maxRecords + 1 victims).
+        const evict = [...existing]
+            .sort((a, b) => a.envelope.created - b.envelope.created)
+            .slice(0, existing.length - this._maxRecords + 1)
+            .map((record) => record.envelope.id);
+        return succeed({ decision: 'cull-oldest', evict });
+    }
+    /** {@inheritDoc IWritePolicy.applyUpdate} */
+    applyUpdate(existing, patch) {
+        // Project the declared mutable fields (restricted to the known record-level
+        // vocabulary) into a single record-level view from their canonical
+        // locations. An `undefined` value is omitted (the editor rejects undefined
+        // property values).
+        const view = {};
+        for (const field of this.mutableFields) {
+            const reader = CAP_CULL_FIELD_READERS.get(field);
+            if (reader !== undefined) {
+                const value = reader(existing);
+                if (value !== undefined) {
+                    view[field] = value;
+                }
+            }
+        }
+        // Restrict the incoming patch to the declared mutable fields.
+        const scopedPatch = {};
+        for (const field of this.mutableFields) {
+            if (field in patch) {
+                scopedPatch[field] = patch[field];
+            }
+        }
+        // Clone the view (no null-deletion), then apply the RFC-7386 merge patch
+        // onto the clone so the persisted record is never mutated in place.
+        return this._cloneEditor
+            .mergeObjectInPlace({}, view)
+            .onSuccess((clone) => this._mergeEditor.mergeObjectInPlace(clone, scopedPatch))
+            .onSuccess((merged) => this._rebuild(existing, merged));
+    }
+    /**
+     * Reassemble a record from the merged mutable view. Only the declared mutable
+     * fields are taken from the merge; undeclared fields are preserved verbatim
+     * from `existing`. A `null` patch that deletes a *declared mutable* required
+     * field (`body` / `tags` / `links` / `provenance`) is an error — a required
+     * field that is NOT declared mutable simply falls through to its `existing.*`
+     * value and is never at risk. `embeddingRef`, when mutable, is restored as
+     * `undefined` (absent) if the merge dropped it — same hash-stable semantics as
+     * {@link KnowledgeLwwPolicy}.
+     */
+    _rebuild(existing, merged) {
+        const deleted = this.mutableFields.filter((field) => CAP_CULL_REQUIRED_FIELDS.has(field) && !(field in merged));
+        if (deleted.length > 0) {
+            return fail(`memory cap-cull: merge patch may not delete required field(s): ${deleted.join(', ')}`);
+        }
+        // The merged values are JSON projections of the already-validated typed
+        // record; restore the domain types. (The types packlet cannot import the
+        // converters packlet without a cycle, so these are structural restorations
+        // of fields the merge preserved, not fresh untrusted input — mirrors
+        // KnowledgeLwwPolicy._rebuild.)
+        const embeddingRefMutable = this.mutableFields.includes('embeddingRef');
+        const envelope = Object.assign(Object.assign({}, existing.envelope), { tags: 'tags' in merged ? merged.tags : existing.envelope.tags, links: 'links' in merged ? merged.links : existing.envelope.links, provenance: 'provenance' in merged ? merged.provenance : existing.envelope.provenance, embeddingRef: embeddingRefMutable
+                ? 'embeddingRef' in merged
+                    ? merged.embeddingRef
+                    : undefined
+                : existing.envelope.embeddingRef });
+        return succeed({ envelope, body: 'body' in merged ? merged.body : existing.body });
+    }
+}
+//# sourceMappingURL=writePolicy.js.map

package/dist/packlets/types/writePolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePolicy.js","sourceRoot":"","sources":["../../../src/packlets/types/writePolicy.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { JsonObject } from '@fgv/ts-json-base';\nimport { IJsonEditorOptions, JsonEditor } from '@fgv/ts-json';\nimport { IEdge, IMemoryEnvelope, IMemoryRecord, IProvenance } from './envelope';\nimport { MemoryId, Tag } from './ids';\n\n/**\n * The granularity at which the store deduplicates an incoming write against the\n * existing vault, declared per kind via {@link IWritePolicy.dedupScope}.\n *\n * - `'content'`: scope-wide cross-id content dedup. An identical\n *   `{ kind, body, links }` triple ANYWHERE in the scope — even under a\n *   different id — is a no-op that returns the existing record. The knowledge\n *   kind family uses this.\n * - `'entity'`: same-id content dedup only. An identical re-put of the SAME\n *   entity is a no-op, but two DISTINCT entities with identical content never\n *   collapse. The experience (memory) kind families use this so that, e.g.,\n *   two turns whose summaries happen to be byte-identical both persist.\n * @public\n */\nexport type DedupScope = 'content' | 'entity';\n\n/**\n * The default {@link DedupScope} applied when a policy does not declare one.\n * Entity-scoped dedup is the safe default — it never silently collapses two\n * distinct entities with coincidentally-identical content.\n * @public\n */\nexport const DEFAULT_DEDUP_SCOPE: DedupScope = 'entity';\n\n/**\n * The admission decision returned by {@link IWritePolicy.admit}.\n * @public\n */\nexport type AdmissionDecision =\n  | { readonly decision: 'accept' }\n  | { readonly decision: 'reject'; readonly reason: string }\n  | {\n      readonly decision: 'cull-oldest';\n      /** {@link MemoryId}s to evict before writing the incoming record. */\n      readonly evict: ReadonlyArray<MemoryId>;\n    };\n\n/**\n * A per-kind write policy, injected at store construction. Invoked AFTER\n * content-hash dedup (dedup is always pre-policy). The policy decides\n * admission and, on update, applies a JSON Merge Patch (RFC-7386) restricted\n * to the declared mutable fields.\n * @public\n */\nexport interface IWritePolicy {\n  /**\n   * Names of the fields a merge-patch update may touch. Fields outside this\n   * list are immutable; a change to one constitutes a new entity (its\n   * `contentHash` differs). Used by {@link IWritePolicy.applyUpdate} to\n   * restrict which fields the patch applies.\n   */\n  readonly mutableFields: ReadonlyArray<string>;\n\n  /**\n   * The granularity at which the store deduplicates an incoming write for this\n   * kind. Optional; when absent the store applies {@link DEFAULT_DEDUP_SCOPE}\n   * (`'entity'`). See {@link DedupScope}.\n   */\n  readonly dedupScope?: DedupScope;\n\n  /**\n   * Determine whether the incoming record is admitted.\n   * @param incoming - The record about to be written.\n   * @param existing - The admission cohort the kind's cap applies to: the\n   * records in the same scope of the same kind, EXCLUDING the record at\n   * `incoming`'s target id. Empty on a first write into an empty cohort.\n   * Excluding the target id makes the post-write count uniform\n   * (`existing.length + 1`) across first-writes and same-id updates. A\n   * last-write-wins policy that has no cap ignores this argument.\n   * @returns A {@link AdmissionDecision}.\n   */\n  admit(\n    incoming: IMemoryRecord<unknown>,\n    existing: ReadonlyArray<IMemoryRecord<unknown>>\n  ): Result<AdmissionDecision>;\n\n  /**\n   * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing\n   * record. Called when admission is `accept` AND a record with the same\n   * `entityId` already exists (an update, not a first write).\n   *\n   * @param existing - The current persisted record.\n   * @param patch - A partial JSON object in Merge Patch format. `null`\n   * deletes the corresponding key; arrays replace wholesale; nested objects\n   * deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n   * @returns The updated record (envelope + body).\n   */\n  applyUpdate(\n    existing: IMemoryRecord<unknown>,\n    patch: Record<string, unknown>\n  ): Result<IMemoryRecord<unknown>>;\n}\n\n/**\n * RFC-7386-compliant merge options for {@link IWritePolicy.applyUpdate}.\n *\n * @remarks\n * Phase-A verification (design-lock §5.1) confirmed `@fgv/ts-json`'s\n * `JsonEditor` diverges from RFC-7386 under its defaults on two axes —\n * `nullAsDelete` defaults `false` and `arrayMergeBehavior` defaults\n * `'append'`. Both are corrected here via the existing option surface, so the\n * primitive is composed (not extended, not hand-rolled).\n */\nconst MERGE_PATCH_OPTIONS: Partial<IJsonEditorOptions> = {\n  merge: {\n    nullAsDelete: true,\n    arrayMergeBehavior: 'replace'\n  }\n};\n\n/**\n * Last-write-wins write policy for the knowledge kind family. Admission\n * always accepts (no cap, no cull); updates apply an RFC-7386 merge patch\n * restricted to the knowledge mutable surface.\n *\n * @remarks\n * **Merge-surface pin (resolves design-lock §5.3's body-vs-envelope muddle).**\n * The declared `mutableFields` span both axes of a record: `body` is the\n * per-kind body, while `tags` / `links` / `provenance` / `embeddingRef` live\n * on the {@link IMemoryEnvelope}. `applyUpdate` projects exactly those fields\n * — each read from its canonical location — into a single record-level JSON\n * view, runs the merge over that view, then rebuilds a coherent record. The\n * identity and transaction-time envelope fields (`id`, `entityId`, `kind`,\n * `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are\n * preserved verbatim; the store stamps `updated` / `seq` on write.\n * @public\n */\nexport class KnowledgeLwwPolicy implements IWritePolicy {\n  /**\n   * The knowledge mutable surface: the body plus the envelope metadata a\n   * consumer may revise without minting a new entity.\n   */\n  public readonly mutableFields: ReadonlyArray<string> = [\n    'body',\n    'tags',\n    'links',\n    'provenance',\n    'embeddingRef'\n  ];\n\n  /**\n   * Knowledge dedups scope-wide: an identical `{ kind, body, links }` triple\n   * anywhere in the `knowledge` scope — even under a different `docId` — is a\n   * no-op. Declared explicitly so the B1 content-dedup behavior (and its tests)\n   * are unchanged by the {@link DedupScope} amendment.\n   */\n  public readonly dedupScope: DedupScope = 'content';\n\n  /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */\n  private readonly _cloneEditor: JsonEditor;\n  /** Applies the RFC-7386 merge patch. */\n  private readonly _mergeEditor: JsonEditor;\n\n  private constructor(cloneEditor: JsonEditor, mergeEditor: JsonEditor) {\n    this._cloneEditor = cloneEditor;\n    this._mergeEditor = mergeEditor;\n  }\n\n  /**\n   * Family-convention factory. Constructs the shared `JsonEditor` instances\n   * (one for cloning, one for the RFC-7386 merge), both with the template /\n   * conditional / multivalue / reference rules disabled (empty rules array).\n   */\n  public static create(): Result<KnowledgeLwwPolicy> {\n    return JsonEditor.create({}, []).onSuccess((cloneEditor) =>\n      JsonEditor.create(MERGE_PATCH_OPTIONS, []).onSuccess((mergeEditor) =>\n        succeed(new KnowledgeLwwPolicy(cloneEditor, mergeEditor))\n      )\n    );\n  }\n\n  /** {@inheritDoc IWritePolicy.admit} */\n  public admit(\n    __incoming: IMemoryRecord<unknown>,\n    __existing: ReadonlyArray<IMemoryRecord<unknown>>\n  ): Result<AdmissionDecision> {\n    // Last-write-wins: always accept. No cap, no cull.\n    return succeed({ decision: 'accept' });\n  }\n\n  /** {@inheritDoc IWritePolicy.applyUpdate} */\n  public applyUpdate(\n    existing: IMemoryRecord<unknown>,\n    patch: Record<string, unknown>\n  ): Result<IMemoryRecord<unknown>> {\n    // Project the mutable fields into a single record-level view, each sourced\n    // from its canonical location. `embeddingRef` is omitted when `undefined`\n    // (the editor rejects undefined property values).\n    const view: Record<string, unknown> = {\n      body: existing.body,\n      tags: existing.envelope.tags,\n      links: existing.envelope.links,\n      provenance: existing.envelope.provenance\n    };\n    if (existing.envelope.embeddingRef !== undefined) {\n      view.embeddingRef = existing.envelope.embeddingRef;\n    }\n\n    // Restrict the incoming patch to the declared mutable fields; out-of-scope\n    // keys are never applied (the store enforces the same constraint).\n    const scopedPatch: Record<string, unknown> = {};\n    for (const field of this.mutableFields) {\n      if (field in patch) {\n        scopedPatch[field] = patch[field];\n      }\n    }\n\n    // Clone the view (no null-deletion), then apply the RFC-7386 merge patch\n    // onto the clone so the persisted record is never mutated in place.\n    return this._cloneEditor\n      .mergeObjectInPlace({}, view as JsonObject)\n      .onSuccess((clone) => this._mergeEditor.mergeObjectInPlace(clone, scopedPatch as JsonObject))\n      .onSuccess((merged) => this._rebuild(existing, merged));\n  }\n\n  /**\n   * Reassemble a record from the merged mutable view. `body` / `tags` /\n   * `links` / `provenance` are required and may not be deleted by a patch.\n   * `embeddingRef` is optional: when it is absent from the merged view —\n   * because the existing record never carried it OR a `null` patch deleted it\n   * (RFC-7386) — it is restored as `undefined` (absent), NOT `null`. This keeps\n   * an originally-absent `embeddingRef` from silently flipping to `null` on an\n   * unrelated update, so the field round-trips hash-stably through the store's\n   * content-hash recomputation.\n   */\n  private _rebuild(existing: IMemoryRecord<unknown>, merged: JsonObject): Result<IMemoryRecord<unknown>> {\n    const required: ReadonlyArray<string> = ['body', 'tags', 'links', 'provenance'];\n    const missing: ReadonlyArray<string> = required.filter((field) => !(field in merged));\n    if (missing.length > 0) {\n      return fail(`knowledge LWW: merge patch may not delete required field(s): ${missing.join(', ')}`);\n    }\n\n    // The merged values are JSON projections of the already-validated typed\n    // record; restore the domain types. (The types packlet cannot import the\n    // converters packlet without a cycle, so these are structural restorations\n    // of fields the merge preserved, not fresh untrusted input.)\n    const envelope: IMemoryEnvelope = {\n      ...existing.envelope,\n      tags: merged.tags as unknown as ReadonlyArray<Tag>,\n      links: merged.links as unknown as ReadonlyArray<IEdge>,\n      provenance: merged.provenance as unknown as IProvenance,\n      embeddingRef: 'embeddingRef' in merged ? (merged.embeddingRef as string | null) : undefined\n    };\n    return succeed({ envelope, body: merged.body });\n  }\n}\n\n/**\n * Parameters for {@link MemoryCapCullPolicy.create}.\n * @public\n */\nexport interface IMemoryCapCullPolicyParams {\n  /**\n   * Maximum number of records the policy admits before culling the oldest.\n   * Counted over the `existing` cohort passed to {@link IWritePolicy.admit}.\n   * Absent = no cap (admission always accepts).\n   */\n  readonly maxRecords?: number;\n  /**\n   * The fields a merge-patch update may touch (drawn from the record-level\n   * mutable vocabulary: `body` / `tags` / `links` / `provenance` /\n   * `embeddingRef`). Fields outside this list are immutable.\n   */\n  readonly mutableFields: ReadonlyArray<string>;\n}\n\n/**\n * The record-level fields a {@link MemoryCapCullPolicy} merge-patch may project,\n * mapped to their canonical location on a record. Mirrors the store's\n * mutable-field accessor vocabulary; a declared mutable field outside this set\n * is inert (the store cannot project it either).\n */\nconst CAP_CULL_FIELD_READERS: ReadonlyMap<string, (record: IMemoryRecord<unknown>) => unknown> = new Map<\n  string,\n  (record: IMemoryRecord<unknown>) => unknown\n>([\n  ['body', (r) => r.body],\n  ['tags', (r) => r.envelope.tags],\n  ['links', (r) => r.envelope.links],\n  ['provenance', (r) => r.envelope.provenance],\n  ['embeddingRef', (r) => r.envelope.embeddingRef]\n]);\n\n/** The record-level mutable fields that may never be deleted by a merge patch. */\nconst CAP_CULL_REQUIRED_FIELDS: ReadonlySet<string> = new Set<string>([\n  'body',\n  'tags',\n  'links',\n  'provenance'\n]);\n\n/**\n * Bounded-ring write policy for the experience (memory) kind families.\n * Admission accepts until `maxRecords` is reached, then evicts the oldest\n * record(s) by `created` ascending (design-lock §5.3); updates apply the same\n * RFC-7386 merge patch as {@link KnowledgeLwwPolicy}, restricted to the declared\n * {@link IMemoryCapCullPolicyParams.mutableFields | mutableFields}.\n *\n * @remarks\n * - **Dedup scope.** Declares `dedupScope: 'entity'` — two distinct memory\n *   entities (e.g. `turn-5` / `turn-9`) with identical `{ kind, body, links }`\n *   never collapse; only an identical re-put of the SAME entity is a no-op.\n * - **Eviction boundary.** `admit` only DECIDES (returns the `MemoryId`s to\n *   evict); the store executes the file deletions and index patches. The\n *   `existing` cohort the cap counts against is whatever the store supplies to\n *   `admit`.\n * @public\n */\nexport class MemoryCapCullPolicy implements IWritePolicy {\n  /** {@inheritDoc IWritePolicy.mutableFields} */\n  public readonly mutableFields: ReadonlyArray<string>;\n\n  /** Experience kinds dedup per-entity (see the class remarks). */\n  public readonly dedupScope: DedupScope = 'entity';\n\n  /** The admission cap; `undefined` = no cap. */\n  private readonly _maxRecords: number | undefined;\n  /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */\n  private readonly _cloneEditor: JsonEditor;\n  /** Applies the RFC-7386 merge patch. */\n  private readonly _mergeEditor: JsonEditor;\n\n  private constructor(params: IMemoryCapCullPolicyParams, cloneEditor: JsonEditor, mergeEditor: JsonEditor) {\n    this.mutableFields = params.mutableFields;\n    this._maxRecords = params.maxRecords;\n    this._cloneEditor = cloneEditor;\n    this._mergeEditor = mergeEditor;\n  }\n\n  /**\n   * Family-convention factory. Constructs the shared `JsonEditor` instances\n   * (one for cloning, one for the RFC-7386 merge) with the same merge config as\n   * {@link KnowledgeLwwPolicy} (`nullAsDelete` true, `arrayMergeBehavior`\n   * `'replace'`, rules disabled).\n   */\n  public static create(params: IMemoryCapCullPolicyParams): Result<MemoryCapCullPolicy> {\n    return JsonEditor.create({}, []).onSuccess((cloneEditor) =>\n      JsonEditor.create(MERGE_PATCH_OPTIONS, []).onSuccess((mergeEditor) =>\n        succeed(new MemoryCapCullPolicy(params, cloneEditor, mergeEditor))\n      )\n    );\n  }\n\n  /** {@inheritDoc IWritePolicy.admit} */\n  public admit(\n    __incoming: IMemoryRecord<unknown>,\n    existing: ReadonlyArray<IMemoryRecord<unknown>>\n  ): Result<AdmissionDecision> {\n    if (this._maxRecords === undefined || existing.length < this._maxRecords) {\n      return succeed({ decision: 'accept' });\n    }\n    // Cap reached: evict the oldest by `created` ascending so the post-write\n    // count is exactly `maxRecords` (existing.length - maxRecords + 1 victims).\n    const evict: ReadonlyArray<MemoryId> = [...existing]\n      .sort((a, b) => a.envelope.created - b.envelope.created)\n      .slice(0, existing.length - this._maxRecords + 1)\n      .map((record) => record.envelope.id);\n    return succeed({ decision: 'cull-oldest', evict });\n  }\n\n  /** {@inheritDoc IWritePolicy.applyUpdate} */\n  public applyUpdate(\n    existing: IMemoryRecord<unknown>,\n    patch: Record<string, unknown>\n  ): Result<IMemoryRecord<unknown>> {\n    // Project the declared mutable fields (restricted to the known record-level\n    // vocabulary) into a single record-level view from their canonical\n    // locations. An `undefined` value is omitted (the editor rejects undefined\n    // property values).\n    const view: Record<string, unknown> = {};\n    for (const field of this.mutableFields) {\n      const reader: ((record: IMemoryRecord<unknown>) => unknown) | undefined =\n        CAP_CULL_FIELD_READERS.get(field);\n      if (reader !== undefined) {\n        const value: unknown = reader(existing);\n        if (value !== undefined) {\n          view[field] = value;\n        }\n      }\n    }\n\n    // Restrict the incoming patch to the declared mutable fields.\n    const scopedPatch: Record<string, unknown> = {};\n    for (const field of this.mutableFields) {\n      if (field in patch) {\n        scopedPatch[field] = patch[field];\n      }\n    }\n\n    // Clone the view (no null-deletion), then apply the RFC-7386 merge patch\n    // onto the clone so the persisted record is never mutated in place.\n    return this._cloneEditor\n      .mergeObjectInPlace({}, view as JsonObject)\n      .onSuccess((clone) => this._mergeEditor.mergeObjectInPlace(clone, scopedPatch as JsonObject))\n      .onSuccess((merged) => this._rebuild(existing, merged));\n  }\n\n  /**\n   * Reassemble a record from the merged mutable view. Only the declared mutable\n   * fields are taken from the merge; undeclared fields are preserved verbatim\n   * from `existing`. A `null` patch that deletes a *declared mutable* required\n   * field (`body` / `tags` / `links` / `provenance`) is an error — a required\n   * field that is NOT declared mutable simply falls through to its `existing.*`\n   * value and is never at risk. `embeddingRef`, when mutable, is restored as\n   * `undefined` (absent) if the merge dropped it — same hash-stable semantics as\n   * {@link KnowledgeLwwPolicy}.\n   */\n  private _rebuild(existing: IMemoryRecord<unknown>, merged: JsonObject): Result<IMemoryRecord<unknown>> {\n    const deleted: ReadonlyArray<string> = this.mutableFields.filter(\n      (field) => CAP_CULL_REQUIRED_FIELDS.has(field) && !(field in merged)\n    );\n    if (deleted.length > 0) {\n      return fail(`memory cap-cull: merge patch may not delete required field(s): ${deleted.join(', ')}`);\n    }\n\n    // The merged values are JSON projections of the already-validated typed\n    // record; restore the domain types. (The types packlet cannot import the\n    // converters packlet without a cycle, so these are structural restorations\n    // of fields the merge preserved, not fresh untrusted input — mirrors\n    // KnowledgeLwwPolicy._rebuild.)\n    const embeddingRefMutable: boolean = this.mutableFields.includes('embeddingRef');\n    const envelope: IMemoryEnvelope = {\n      ...existing.envelope,\n      tags: 'tags' in merged ? (merged.tags as unknown as ReadonlyArray<Tag>) : existing.envelope.tags,\n      links: 'links' in merged ? (merged.links as unknown as ReadonlyArray<IEdge>) : existing.envelope.links,\n      provenance:\n        'provenance' in merged ? (merged.provenance as unknown as IProvenance) : existing.envelope.provenance,\n      embeddingRef: embeddingRefMutable\n        ? 'embeddingRef' in merged\n          ? (merged.embeddingRef as string | null)\n          : undefined\n        : existing.envelope.embeddingRef\n    };\n    return succeed({ envelope, body: 'body' in merged ? merged.body : existing.body });\n  }\n}\n"]}

package/dist/packlets/vector/inMemoryCosineIndex.js

@@ -0,0 +1,150 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { fail, succeed } from '@fgv/ts-utils';
+/**
+ * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
+ * `Float32Array` per record and answers a query by computing cosine similarity
+ * against every stored vector, returning the top-k by descending score.
+ *
+ * @remarks
+ * This is the **complete** vector implementation for the fgv regime — large-N is
+ * explicitly out of scope (the seam stays open for a consumer to swap an external
+ * ANN backend once N grows beyond "thousands of records"). No external dependency
+ * and no ANN structure: a linear scan over a few thousand vectors is well within
+ * an interactive budget.
+ *
+ * The index has a single dimension established by the first vector added; every
+ * subsequent `add` and every `query` vector must match that dimension or fail
+ * loudly — a mismatched dimension is an embedder-wiring bug, never a silent
+ * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears
+ * the index, so a re-embed with a different model (hence dimension) is supported.
+ *
+ * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the
+ * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a
+ * future nicety.
+ * @public
+ */
+export class InMemoryCosineIndex {
+    constructor() {
+        this._vectors = new Map();
+        this._dimension = undefined;
+    }
+    /** The number of vectors currently held. */
+    get size() {
+        return this._vectors.size;
+    }
+    /** Family-convention factory. */
+    static create() {
+        return succeed(new InMemoryCosineIndex());
+    }
+    /** {@inheritDoc IVectorIndex.add} */
+    add(id, vector) {
+        if (vector.length === 0) {
+            return Promise.resolve(fail(`vector index: cannot add '${id}': empty vector`));
+        }
+        if (this._dimension === undefined) {
+            this._dimension = vector.length;
+        }
+        else if (vector.length !== this._dimension) {
+            return Promise.resolve(fail(`vector index: cannot add '${id}': dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        // Defensive copy: the caller may reuse or mutate the buffer after `add`, and
+        // the index must keep serving the embedding it was given.
+        this._vectors.set(id, Float32Array.from(vector));
+        // The in-memory index keys entries by id, so the id IS the entry reference.
+        return Promise.resolve(succeed(id));
+    }
+    /** {@inheritDoc IVectorIndex.remove} */
+    remove(id) {
+        this._vectors.delete(id);
+        return Promise.resolve(succeed(id));
+    }
+    /** {@inheritDoc IVectorIndex.query} */
+    query(vector, topK) {
+        if (topK <= 0 || this._vectors.size === 0) {
+            return Promise.resolve(succeed([]));
+        }
+        if (vector.length !== this._dimension) {
+            return Promise.resolve(fail(`vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`));
+        }
+        const queryMagnitude = InMemoryCosineIndex._magnitude(vector);
+        const hits = [];
+        for (const [id, stored] of this._vectors) {
+            hits.push({ id, score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored) });
+        }
+        // Descending by score; a `seq`-free tiebreak is unnecessary here because the
+        // caller (SemanticRetriever) re-resolves hits against the record index.
+        hits.sort((a, b) => b.score - a.score);
+        return Promise.resolve(succeed(hits.length > topK ? hits.slice(0, topK) : hits));
+    }
+    /**
+     * Re-embed every record from `source` and rebuild the index from scratch.
+     * Clears the current contents (and the established dimension) first, so a
+     * re-embed with a different model is supported. Returns the number of vectors
+     * indexed.
+     *
+     * On any failure (list, embed, or add) the index is rolled back to empty
+     * rather than left in a partially-rebuilt state — a caller that retries a query
+     * after a failed rebuild sees a clean empty index, never a half-populated one.
+     *
+     * @param source - The record source to re-embed (an {@link IMemoryStore}
+     * satisfies this structurally).
+     * @param embed - The embedder applied to each record.
+     */
+    async rebuild(source, embed) {
+        // Reset up front so the "any failure leaves the index empty" contract holds
+        // even when the listing itself fails (no stale vectors survive a failed
+        // rebuild).
+        this._reset();
+        const listed = await source.list();
+        if (listed.isFailure()) {
+            return fail(`vector index rebuild: failed to list records: ${listed.message}`);
+        }
+        for (const record of listed.value) {
+            const embedded = await embed(record);
+            if (embedded.isFailure()) {
+                this._reset();
+                return fail(`vector index rebuild: embedding '${record.envelope.id}' failed: ${embedded.message}`);
+            }
+            const added = await this.add(record.envelope.id, embedded.value);
+            if (added.isFailure()) {
+                this._reset();
+                return fail(`vector index rebuild: ${added.message}`);
+            }
+        }
+        return succeed(this._vectors.size);
+    }
+    /** Empty the index and forget the established dimension. */
+    _reset() {
+        this._vectors.clear();
+        this._dimension = undefined;
+    }
+    /** The Euclidean magnitude (L2 norm) of a vector. */
+    static _magnitude(vector) {
+        let sum = 0;
+        for (let i = 0; i < vector.length; i++) {
+            sum += vector[i] * vector[i];
+        }
+        return Math.sqrt(sum);
+    }
+    /**
+     * Cosine similarity between the query (whose magnitude is precomputed once and
+     * reused across the scan) and a stored vector. A zero-magnitude vector on
+     * either side yields `0` rather than `NaN` — a degenerate vector is simply
+     * maximally dissimilar, not an error.
+     */
+    static _cosine(query, queryMagnitude, stored) {
+        const storedMagnitude = InMemoryCosineIndex._magnitude(stored);
+        if (queryMagnitude === 0 || storedMagnitude === 0) {
+            return 0;
+        }
+        let dot = 0;
+        for (let i = 0; i < query.length; i++) {
+            dot += query[i] * stored[i];
+        }
+        return dot / (queryMagnitude * storedMagnitude);
+    }
+}
+//# sourceMappingURL=inMemoryCosineIndex.js.map

package/dist/packlets/vector/inMemoryCosineIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryCosineIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,mBAAmB;IAK9B;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;QAClD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,4CAA4C;IAC5C,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,OAAO,CAAC,IAAI,mBAAmB,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,qCAAqC;IAC9B,GAAG,CAAC,EAAY,EAAE,MAAoB;QAC3C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC;QAClC,CAAC;aAAM,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;YAC7C,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,CACF,6BAA6B,EAAE,gBAAgB,MAAM,CAAC,MAAM,mCAAmC,IAAI,CAAC,UAAU,EAAE,CACjH,CACF,CAAC;QACJ,CAAC;QACD,6EAA6E;QAC7E,0DAA0D;QAC1D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,4EAA4E;QAC5E,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAY,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,wCAAwC;IACjC,MAAM,CAAC,EAAY;QACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,uCAAuC;IAChC,KAAK,CAAC,MAAoB,EAAE,IAAY;QAC7C,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;YACtC,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,CACF,iCAAiC,MAAM,CAAC,MAAM,mCAAmC,IAAI,CAAC,UAAU,EAAE,CACnG,CACF,CAAC;QACJ,CAAC;QACD,MAAM,cAAc,GAAW,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACtE,MAAM,IAAI,GAAsB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,6EAA6E;QAC7E,wEAAwE;QACxE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,KAAK,CAAC,OAAO,CAAC,MAA2B,EAAE,KAAqB;QACrE,4EAA4E;QAC5E,wEAAwE;QACxE,YAAY;QACZ,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,MAAM,GAAkD,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAClF,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,iDAAiD,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAyB,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;gBACzB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,oCAAoC,MAAM,CAAC,QAAQ,CAAC,EAAE,aAAa,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;YACrG,CAAC;YACD,MAAM,KAAK,GAAmB,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;YACjF,IAAI,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;gBACtB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,4DAA4D;IACpD,MAAM;QACZ,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,qDAAqD;IAC7C,MAAM,CAAC,UAAU,CAAC,MAAoB;QAC5C,IAAI,GAAG,GAAW,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,OAAO,CAAC,KAAmB,EAAE,cAAsB,EAAE,MAAoB;QACtF,MAAM,eAAe,GAAW,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACvE,IAAI,cAAc,KAAK,CAAC,IAAI,eAAe,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,GAAG,GAAW,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9C,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,GAAG,GAAG,CAAC,cAAc,GAAG,eAAe,CAAC,CAAC;IAClD,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 { IMemoryRecord, MemoryId } from '../types';\nimport { IMemoryRecordSource, IVectorIndex, IVectorQueryHit, MemoryEmbedder } from './vectorIndex';\n\n/**\n * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one\n * `Float32Array` per record and answers a query by computing cosine similarity\n * against every stored vector, returning the top-k by descending score.\n *\n * @remarks\n * This is the **complete** vector implementation for the fgv regime — large-N is\n * explicitly out of scope (the seam stays open for a consumer to swap an external\n * ANN backend once N grows beyond \"thousands of records\"). No external dependency\n * and no ANN structure: a linear scan over a few thousand vectors is well within\n * an interactive budget.\n *\n * The index has a single dimension established by the first vector added; every\n * subsequent `add` and every `query` vector must match that dimension or fail\n * loudly — a mismatched dimension is an embedder-wiring bug, never a silent\n * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears\n * the index, so a re-embed with a different model (hence dimension) is supported.\n *\n * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the\n * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a\n * future nicety.\n * @public\n */\nexport class InMemoryCosineIndex implements IVectorIndex {\n  private readonly _vectors: Map<MemoryId, Float32Array>;\n  /** The dimension of every stored vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._vectors = new Map<MemoryId, Float32Array>();\n    this._dimension = undefined;\n  }\n\n  /** The number of vectors currently held. */\n  public get size(): number {\n    return this._vectors.size;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryCosineIndex> {\n    return succeed(new InMemoryCosineIndex());\n  }\n\n  /** {@inheritDoc IVectorIndex.add} */\n  public add(id: MemoryId, vector: Float32Array): Promise<Result<string>> {\n    if (vector.length === 0) {\n      return Promise.resolve(fail(`vector index: cannot add '${id}': empty vector`));\n    }\n    if (this._dimension === undefined) {\n      this._dimension = vector.length;\n    } else if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: cannot add '${id}': dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    // Defensive copy: the caller may reuse or mutate the buffer after `add`, and\n    // the index must keep serving the embedding it was given.\n    this._vectors.set(id, Float32Array.from(vector));\n    // The in-memory index keys entries by id, so the id IS the entry reference.\n    return Promise.resolve(succeed(id as string));\n  }\n\n  /** {@inheritDoc IVectorIndex.remove} */\n  public remove(id: MemoryId): Promise<Result<MemoryId>> {\n    this._vectors.delete(id);\n    return Promise.resolve(succeed(id));\n  }\n\n  /** {@inheritDoc IVectorIndex.query} */\n  public query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._vectors.size === 0) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    const queryMagnitude: number = InMemoryCosineIndex._magnitude(vector);\n    const hits: IVectorQueryHit[] = [];\n    for (const [id, stored] of this._vectors) {\n      hits.push({ id, score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored) });\n    }\n    // Descending by score; a `seq`-free tiebreak is unnecessary here because the\n    // caller (SemanticRetriever) re-resolves hits against the record index.\n    hits.sort((a, b) => b.score - a.score);\n    return Promise.resolve(succeed(hits.length > topK ? hits.slice(0, topK) : hits));\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the index from scratch.\n   * Clears the current contents (and the established dimension) first, so a\n   * re-embed with a different model is supported. Returns the number of vectors\n   * indexed.\n   *\n   * On any failure (list, embed, or add) the index is rolled back to empty\n   * rather than left in a partially-rebuilt state — a caller that retries a query\n   * after a failed rebuild sees a clean empty index, never a half-populated one.\n   *\n   * @param source - The record source to re-embed (an {@link IMemoryStore}\n   * satisfies this structurally).\n   * @param embed - The embedder applied to each record.\n   */\n  public async rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>> {\n    // Reset up front so the \"any failure leaves the index empty\" contract holds\n    // even when the listing itself fails (no stale vectors survive a failed\n    // rebuild).\n    this._reset();\n    const listed: Result<ReadonlyArray<IMemoryRecord<unknown>>> = await source.list();\n    if (listed.isFailure()) {\n      return fail(`vector index rebuild: failed to list records: ${listed.message}`);\n    }\n    for (const record of listed.value) {\n      const embedded: Result<Float32Array> = await embed(record);\n      if (embedded.isFailure()) {\n        this._reset();\n        return fail(`vector index rebuild: embedding '${record.envelope.id}' failed: ${embedded.message}`);\n      }\n      const added: Result<string> = await this.add(record.envelope.id, embedded.value);\n      if (added.isFailure()) {\n        this._reset();\n        return fail(`vector index rebuild: ${added.message}`);\n      }\n    }\n    return succeed(this._vectors.size);\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._vectors.clear();\n    this._dimension = undefined;\n  }\n\n  /** The Euclidean magnitude (L2 norm) of a vector. */\n  private static _magnitude(vector: Float32Array): number {\n    let sum: number = 0;\n    for (let i: number = 0; i < vector.length; i++) {\n      sum += vector[i] * vector[i];\n    }\n    return Math.sqrt(sum);\n  }\n\n  /**\n   * Cosine similarity between the query (whose magnitude is precomputed once and\n   * reused across the scan) and a stored vector. A zero-magnitude vector on\n   * either side yields `0` rather than `NaN` — a degenerate vector is simply\n   * maximally dissimilar, not an error.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryCosineIndex._magnitude(stored);\n    if (queryMagnitude === 0 || storedMagnitude === 0) {\n      return 0;\n    }\n    let dot: number = 0;\n    for (let i: number = 0; i < query.length; i++) {\n      dot += query[i] * stored[i];\n    }\n    return dot / (queryMagnitude * storedMagnitude);\n  }\n}\n"]}

package/dist/packlets/vector/index.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export * from './vectorIndex';
+export * from './inMemoryCosineIndex';
+//# sourceMappingURL=index.js.map

package/dist/packlets/vector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/vector/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './vectorIndex';\nexport * from './inMemoryCosineIndex';\n"]}

package/dist/packlets/vector/vectorIndex.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=vectorIndex.js.map

package/dist/packlets/vector/vectorIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/vectorIndex.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 { IMemoryRecord, MemoryId } from '../types';\n\n/**\n * A single hit returned by {@link IVectorIndex.query}: the matched record id and\n * the backend's similarity score (higher = more similar; the exact scale is\n * backend-defined). Hits are returned in descending score order.\n * @public\n */\nexport interface IVectorQueryHit {\n  /** The id of the matched record. */\n  readonly id: MemoryId;\n  /** Backend similarity score; higher is more similar. */\n  readonly score: number;\n}\n\n/**\n * The vector-index seam an embedding backend implements to make\n * {@link SemanticRetriever | semantic recall} operational.\n *\n * @remarks\n * Vectors cross this seam as `Float32Array` (the in-memory representation an\n * embedding model produces); `number[]` is reserved for the JSON-wire edges\n * (e.g. a provider's embedding response). The in-package brute-force cosine\n * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external\n * ANN backend behind the same seam once N grows beyond the in-memory regime.\n *\n * Every operation returns a `Result` (async, since a real backend does I/O) so\n * failure is explicit and never throws across the seam.\n * @public\n */\nexport interface IVectorIndex {\n  /**\n   * Add (or replace) the embedding for `id`. Returns the opaque\n   * {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps onto\n   * the envelope so a later read knows the record is embedded.\n   */\n  add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;\n\n  /**\n   * Remove the embedding for `id`. Returns the removed id. Idempotent — removing\n   * an id with no embedding still succeeds (returns the id).\n   */\n  remove(id: MemoryId): Promise<Result<MemoryId>>;\n\n  /**\n   * Return the `topK` nearest records to `vector`, in descending score order.\n   */\n  query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n}\n\n/**\n * Embeds a complete record into a vector for the store's embed-on-write hook.\n * Async and `Result`-returning, since a real embedder does a network call (cloud\n * provider) or in-process model inference. The consumer wires this — the core\n * package never calls an embedding provider directly, staying embedder-agnostic.\n * @public\n */\nexport type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;\n\n/**\n * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to\n * re-embed an entire vault. {@link IMemoryStore} satisfies it structurally (its\n * `list` accepts an optional filter, which is assignable to this no-argument\n * shape), so a consumer passes the store directly — without the vector packlet\n * taking a dependency on the store packlet (which depends on the vector packlet\n * for {@link IVectorIndex}, so the reverse import would be a cycle).\n * @public\n */\nexport interface IMemoryRecordSource {\n  /** List every record in the vault. */\n  list(): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;\n}\n"]}

package/dist/test/unit/converters/bodyConverterRegistry.test.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import '@fgv/ts-utils-jest';
+import { Converters } from '@fgv/ts-utils';
+import { JsonSchema } from '@fgv/ts-json-base';
+import { BodyConverterRegistry } from '../../../packlets/converters';
+const knowledgeKind = 'knowledge';
+const profileKind = 'profile';
+describe('BodyConverterRegistry', () => {
+    let registry;
+    beforeEach(() => {
+        registry = BodyConverterRegistry.create().orThrow();
+    });
+    test('create succeeds', () => {
+        expect(BodyConverterRegistry.create()).toSucceed();
+    });
+    describe('register / has / convert', () => {
+        test('registers a Converter and converts a matching body', () => {
+            registry.register(knowledgeKind, Converters.string);
+            expect(registry.has(knowledgeKind)).toBe(true);
+            expect(registry.convert(knowledgeKind, 'a knowledge doc')).toSucceedWith('a knowledge doc');
+        });
+        test('a registered Converter rejects an invalid body', () => {
+            registry.register(knowledgeKind, Converters.string);
+            expect(registry.convert(knowledgeKind, 42)).toFail();
+        });
+        test('has returns false for an unregistered kind', () => {
+            expect(registry.has(knowledgeKind)).toBe(false);
+        });
+        test('convert fails for an unregistered kind', () => {
+            expect(registry.convert(knowledgeKind, 'x')).toFailWith(/no converter registered for kind 'knowledge'/i);
+        });
+        test('register replaces a prior registration for the same kind', () => {
+            registry.register(knowledgeKind, Converters.string);
+            registry.register(knowledgeKind, Converters.number);
+            expect(registry.convert(knowledgeKind, 7)).toSucceedWith(7);
+            expect(registry.convert(knowledgeKind, 'x')).toFail();
+        });
+    });
+    describe('getConverter', () => {
+        test('returns the registered converter', () => {
+            registry.register(knowledgeKind, Converters.string);
+            expect(registry.getConverter(knowledgeKind)).toSucceedAndSatisfy((converter) => {
+                expect(converter.convert('hello')).toSucceedWith('hello');
+            });
+        });
+        test('fails for an unregistered kind', () => {
+            expect(registry.getConverter(knowledgeKind)).toFailWith(/no converter registered for kind/i);
+        });
+    });
+    describe('registerSchema', () => {
+        const profileSchema = JsonSchema.object({
+            name: JsonSchema.string(),
+            age: JsonSchema.integer()
+        });
+        test('registers a JsonSchema validator and validates a matching body', () => {
+            registry.registerSchema(profileKind, profileSchema);
+            expect(registry.has(profileKind)).toBe(true);
+            expect(registry.convert(profileKind, { name: 'Ada', age: 36 })).toSucceedWith({
+                name: 'Ada',
+                age: 36
+            });
+        });
+        test('a registered schema rejects an invalid body', () => {
+            registry.registerSchema(profileKind, profileSchema);
+            expect(registry.convert(profileKind, { name: 'Ada' })).toFail();
+        });
+    });
+});
+//# sourceMappingURL=bodyConverterRegistry.test.js.map

package/dist/test/unit/converters/bodyConverterRegistry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyConverterRegistry.test.js","sourceRoot":"","sources":["../../../../src/test/unit/converters/bodyConverterRegistry.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\nimport { Converters } from '@fgv/ts-utils';\nimport { JsonSchema } from '@fgv/ts-json-base';\nimport { BodyConverterRegistry } from '../../../packlets/converters';\nimport { Kind } from '../../../packlets/types';\n\nconst knowledgeKind: Kind = 'knowledge' as Kind;\nconst profileKind: Kind = 'profile' as Kind;\n\ndescribe('BodyConverterRegistry', () => {\n  let registry: BodyConverterRegistry;\n\n  beforeEach(() => {\n    registry = BodyConverterRegistry.create().orThrow();\n  });\n\n  test('create succeeds', () => {\n    expect(BodyConverterRegistry.create()).toSucceed();\n  });\n\n  describe('register / has / convert', () => {\n    test('registers a Converter and converts a matching body', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.has(knowledgeKind)).toBe(true);\n      expect(registry.convert(knowledgeKind, 'a knowledge doc')).toSucceedWith('a knowledge doc');\n    });\n\n    test('a registered Converter rejects an invalid body', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.convert(knowledgeKind, 42)).toFail();\n    });\n\n    test('has returns false for an unregistered kind', () => {\n      expect(registry.has(knowledgeKind)).toBe(false);\n    });\n\n    test('convert fails for an unregistered kind', () => {\n      expect(registry.convert(knowledgeKind, 'x')).toFailWith(\n        /no converter registered for kind 'knowledge'/i\n      );\n    });\n\n    test('register replaces a prior registration for the same kind', () => {\n      registry.register(knowledgeKind, Converters.string);\n      registry.register(knowledgeKind, Converters.number);\n      expect(registry.convert(knowledgeKind, 7)).toSucceedWith(7);\n      expect(registry.convert(knowledgeKind, 'x')).toFail();\n    });\n  });\n\n  describe('getConverter', () => {\n    test('returns the registered converter', () => {\n      registry.register(knowledgeKind, Converters.string);\n      expect(registry.getConverter(knowledgeKind)).toSucceedAndSatisfy((converter) => {\n        expect(converter.convert('hello')).toSucceedWith('hello');\n      });\n    });\n\n    test('fails for an unregistered kind', () => {\n      expect(registry.getConverter(knowledgeKind)).toFailWith(/no converter registered for kind/i);\n    });\n  });\n\n  describe('registerSchema', () => {\n    const profileSchema = JsonSchema.object({\n      name: JsonSchema.string(),\n      age: JsonSchema.integer()\n    });\n\n    test('registers a JsonSchema validator and validates a matching body', () => {\n      registry.registerSchema(profileKind, profileSchema);\n      expect(registry.has(profileKind)).toBe(true);\n      expect(registry.convert(profileKind, { name: 'Ada', age: 36 })).toSucceedWith({\n        name: 'Ada',\n        age: 36\n      });\n    });\n\n    test('a registered schema rejects an invalid body', () => {\n      registry.registerSchema(profileKind, profileSchema);\n      expect(registry.convert(profileKind, { name: 'Ada' })).toFail();\n    });\n  });\n});\n"]}