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

package/dist/packlets/tools/memoryTools.js

@@ -0,0 +1,337 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { JsonSchema } from '@fgv/ts-json-base';
+import { Convert } from '../types';
+import { envelopeConverter } from '../converters';
+/**
+ * The default tool subset when {@link ICreateMemoryToolsParams.tools | tools} is
+ * omitted: the read-only set. Mutating tools (`memory_write` / `memory_delete`)
+ * are **off by default** and must be named explicitly — writes stay
+ * curation-mediated unless the host opts in.
+ * @public
+ */
+export const DEFAULT_MEMORY_TOOLS = ['memory_search', 'memory_context'];
+// ---------------------------------------------------------------------------
+// Parameter schemas — authored once via JsonSchema.object(...); the schema IS
+// both the wire schema (.toJson()) and the runtime validator (.convert()).
+// NONE of these declare a `scope` (or scope-widening) property — the adoption
+// gate is enforced structurally and asserted in the tests.
+// ---------------------------------------------------------------------------
+/** A single attributed link edge as authored by the agent on a write. */
+// eslint-disable-next-line @rushstack/typedef-var
+const linkEdgeSchema = JsonSchema.object({
+    type: JsonSchema.string({ description: 'The relation type of the link.' }),
+    target: JsonSchema.string({ description: 'The MemoryId this edge points at.' }),
+    confidence: JsonSchema.optional(JsonSchema.number({ description: 'Optional confidence in [0, 1].' }))
+});
+// eslint-disable-next-line @rushstack/typedef-var
+const writeSchema = JsonSchema.object({
+    kind: JsonSchema.string({ description: 'The record kind (must be an enabled, registered kind).' }),
+    entityId: JsonSchema.string({
+        description: 'The domain entity id. For composite (e.g. medium-term) kinds this is the full composite key.'
+    }),
+    body: JsonSchema.string({ description: "The serialized record body; validated by the kind's converter." }),
+    tags: JsonSchema.optional(JsonSchema.array(JsonSchema.string({ description: 'A tag label.' }))),
+    links: JsonSchema.optional(JsonSchema.array(linkEdgeSchema))
+});
+// eslint-disable-next-line @rushstack/typedef-var
+const readSchema = JsonSchema.object({
+    kind: JsonSchema.string({ description: 'The record kind.' }),
+    entityId: JsonSchema.string({ description: 'The domain entity id to read.' })
+});
+// eslint-disable-next-line @rushstack/typedef-var
+const deleteSchema = JsonSchema.object({
+    kind: JsonSchema.string({ description: 'The record kind.' }),
+    entityId: JsonSchema.string({ description: 'The domain entity id to delete.' })
+});
+// eslint-disable-next-line @rushstack/typedef-var
+const searchSchema = JsonSchema.object({
+    kind: JsonSchema.optional(JsonSchema.string({ description: 'Restrict to this kind.' })),
+    tag: JsonSchema.optional(JsonSchema.string({ description: 'Restrict to records carrying this tag.' })),
+    semantic: JsonSchema.optional(JsonSchema.string({ description: 'Semantic query text (requires a semantic-capable retriever).' })),
+    limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))
+});
+// eslint-disable-next-line @rushstack/typedef-var
+const contextSchema = JsonSchema.object({
+    from: JsonSchema.string({ description: 'The seed MemoryId to traverse links from.' }),
+    kind: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records to this kind.' })),
+    tag: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records carrying this tag.' })),
+    hops: JsonSchema.optional(JsonSchema.integer({ description: 'BFS hop count (default 1).' })),
+    limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))
+});
+// ---------------------------------------------------------------------------
+// Behavior annotations (Component 4) — host-advisory hints; never serialized to
+// the model. openWorldHint is false throughout (a closed, local store).
+// ---------------------------------------------------------------------------
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    openWorldHint: false
+};
+const WRITE_ANNOTATIONS = {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+};
+const DELETE_ANNOTATIONS = {
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false
+};
+// ---------------------------------------------------------------------------
+// Shared validation / projection helpers
+// ---------------------------------------------------------------------------
+/** Validate a `kind` string and assert it is an enabled, registered toolable kind. */
+function assertKindEnabled(ctx, kindStr) {
+    return Convert.kind.convert(kindStr).onSuccess((kind) => {
+        if (!ctx.registry.has(kind)) {
+            return fail(`memory tools: kind '${kind}' has no registered body converter`);
+        }
+        if (ctx.kinds !== undefined && !ctx.kinds.includes(kind)) {
+            return fail(`memory tools: kind '${kind}' is not enabled for memory tools`);
+        }
+        return succeed(kind);
+    });
+}
+/** Validate an optional `kind` string (enabled when present; `undefined` passes through). */
+function resolveOptionalKind(ctx, kindStr) {
+    if (kindStr === undefined) {
+        return succeed(undefined);
+    }
+    return assertKindEnabled(ctx, kindStr);
+}
+/** Project a record into an agent-visible result item, applying the host handle hook when present. */
+function projectItem(ctx, record) {
+    // `handleFor` is a host callback; guard it so a throw degrades to the raw id rather than
+    // escaping the Result chain (and crashing the whole search/context call).
+    const handle = ctx.handleFor !== undefined
+        ? captureResult(() => ctx.handleFor(record)).orDefault(record.envelope.id)
+        : record.envelope.id;
+    return {
+        handle,
+        kind: record.envelope.kind,
+        entityId: record.envelope.entityId,
+        tags: record.envelope.tags,
+        body: record.body
+    };
+}
+/** Resolve the identity codec used by `memory_write` to derive the storage id. */
+function codecForWrite(ctx, kind) {
+    var _a, _b;
+    const codec = (_b = (_a = ctx.codecs) === null || _a === void 0 ? void 0 : _a.get(kind)) !== null && _b !== void 0 ? _b : ctx.defaultCodec;
+    if (codec === undefined) {
+        return fail(`memory_write: no identity codec available for kind '${kind}'`);
+    }
+    return succeed(codec);
+}
+/** Build the record to persist from validated write args (store stamps txn-time metadata). */
+function buildWriteRecord(typed, kind, entityId, idStem) {
+    var _a, _b;
+    // Plain shapes handed to `envelopeConverter`, which validates each field
+    // (type → LinkType, target → MemoryId) and produces the branded IEdge[].
+    const links = ((_a = typed.links) !== null && _a !== void 0 ? _a : []).map((link) => (Object.assign({ type: link.type, target: link.target }, (link.confidence !== undefined ? { confidence: link.confidence } : {}))));
+    return envelopeConverter
+        .convert({
+        id: idStem,
+        entityId,
+        kind,
+        tags: (_b = typed.tags) !== null && _b !== void 0 ? _b : [],
+        links,
+        created: 0,
+        updated: 0,
+        seq: 0,
+        contentHash: '',
+        provenance: { source: 'agent' }
+    })
+        .withErrorFormat((msg) => `memory_write: invalid record: ${msg}`)
+        .onSuccess((envelope) => succeed({ envelope, body: typed.body }));
+}
+/** Resolve the validated write args into the storage id + record (all synchronous). */
+function prepareWrite(ctx, typed) {
+    return assertKindEnabled(ctx, typed.kind).onSuccess((kind) => Convert.entityId.convert(typed.entityId).onSuccess((entityId) => codecForWrite(ctx, kind).onSuccess((codec) => codec.encode(entityId).onSuccess((addr) => {
+        if (addr.isVersioned) {
+            return fail(`memory_write: versioned/temporal kind '${kind}' is not supported`);
+        }
+        return buildWriteRecord(typed, kind, entityId, addr.idStem).onSuccess((record) => succeed({ kind, entityId, record }));
+    }))));
+}
+/**
+ * Discriminate the write outcome from a pre-put snapshot and the returned record.
+ * A dedup no-op returns either a different entity (content-scope dedup) or the
+ * same-id record with an unchanged `seq` (entity-scope re-put); a fresh write or
+ * update advances `seq`.
+ */
+function writeOutcome(before, written, entityId) {
+    if (written.envelope.entityId !== entityId) {
+        return 'deduped';
+    }
+    if (before !== undefined && written.envelope.seq === before.envelope.seq) {
+        return 'deduped';
+    }
+    return 'written';
+}
+// ---------------------------------------------------------------------------
+// Tool builders — config with a JsonSchema.object(...) parametersSchema; execute
+// validates/narrows → delegates to store/retriever → returns the Result (never
+// swallowed), following the ts-extras-mcp adapter shape.
+//
+// Each `execute` re-runs its own `parametersSchema.convert(args)` even though the
+// `executeClientToolTurn` harness already validates against the same schema. This
+// is deliberate: the factory returns a heterogeneous `ReadonlyArray<IAiClientTool>`
+// (TParams erased to `unknown`, since the members carry different param shapes), so
+// `execute` receives `unknown` and must narrow it back to the typed args. The
+// re-validation is also the narrowing step exercised by the direct-call tests (which
+// invoke `execute` with raw args, bypassing the harness). Re-validating an
+// already-conforming shape is a cheap, side-effect-free identity.
+// ---------------------------------------------------------------------------
+function buildWriteTool(ctx) {
+    return {
+        config: {
+            type: 'client_tool',
+            name: 'memory_write',
+            description: 'Store a new memory record or update an existing one by (kind, entityId). ' +
+                'Identical content is a no-op that returns the existing record.',
+            parametersSchema: writeSchema,
+            annotations: WRITE_ANNOTATIONS
+        },
+        execute: async (args) => writeSchema
+            .convert(args)
+            .withErrorFormat((msg) => `memory_write: invalid arguments: ${msg}`)
+            .onSuccess((typed) => prepareWrite(ctx, typed))
+            .thenOnSuccess(async ({ kind, entityId, record }) => 
+        // Read the prior record to discriminate written-vs-deduped. A `Failure`
+        // here (corrupt file, I/O error, codec round-trip failure) is a real
+        // condition distinct from the "not found" success (`undefined`); propagate
+        // it rather than defaulting it away, so a genuine store fault surfaces
+        // instead of being masked as a normal write.
+        (await ctx.store.get(kind, entityId)).thenOnSuccess(async (before) => (await ctx.store.put(record)).onSuccess((persisted) => succeed({
+            outcome: writeOutcome(before, persisted, entityId),
+            id: persisted.envelope.id,
+            entityId,
+            kind
+        }))))
+    };
+}
+function buildReadTool(ctx) {
+    return {
+        config: {
+            type: 'client_tool',
+            name: 'memory_read',
+            description: 'Read a specific memory record by (kind, entityId).',
+            parametersSchema: readSchema,
+            annotations: READ_ONLY_ANNOTATIONS
+        },
+        execute: async (args) => readSchema
+            .convert(args)
+            .withErrorFormat((msg) => `memory_read: invalid arguments: ${msg}`)
+            .onSuccess((typed) => assertKindEnabled(ctx, typed.kind).onSuccess((kind) => Convert.entityId.convert(typed.entityId).onSuccess((entityId) => succeed({ kind, entityId }))))
+            .thenOnSuccess(async ({ kind, entityId }) => (await ctx.store.get(kind, entityId)).onSuccess((record) => record === undefined
+            ? succeed({ found: false })
+            : succeed({ found: true, item: projectItem(ctx, record) })))
+    };
+}
+function buildSearchTool(ctx) {
+    return {
+        config: {
+            type: 'client_tool',
+            name: 'memory_search',
+            description: 'Search memories by tag, kind, or semantic text. Returns ranked results.',
+            parametersSchema: searchSchema,
+            annotations: READ_ONLY_ANNOTATIONS
+        },
+        execute: async (args) => searchSchema
+            .convert(args)
+            .withErrorFormat((msg) => `memory_search: invalid arguments: ${msg}`)
+            .onSuccess((typed) => resolveOptionalKind(ctx, typed.kind).onSuccess((kind) => resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, kind, tag }))))
+            .thenOnSuccess(async ({ typed, kind, tag }) => {
+            const query = Object.assign(Object.assign(Object.assign(Object.assign({}, (kind !== undefined ? { kind } : {})), (tag !== undefined ? { tag } : {})), (typed.semantic !== undefined ? { semantic: typed.semantic } : {})), (typed.limit !== undefined ? { limit: typed.limit } : {}));
+            return (await ctx.retriever.retrieve(query)).onSuccess((records) => succeed({ count: records.length, results: records.map((r) => projectItem(ctx, r)) }));
+        })
+    };
+}
+function buildContextTool(ctx) {
+    return {
+        config: {
+            type: 'client_tool',
+            name: 'memory_context',
+            description: 'Build a context graph from a seed memory: returns the records linked from the seed, up to `hops` hops.',
+            parametersSchema: contextSchema,
+            annotations: READ_ONLY_ANNOTATIONS
+        },
+        execute: async (args) => contextSchema
+            .convert(args)
+            .withErrorFormat((msg) => `memory_context: invalid arguments: ${msg}`)
+            .onSuccess((typed) => Convert.memoryId
+            .convert(typed.from)
+            .onSuccess((from) => resolveOptionalKind(ctx, typed.kind).onSuccess((kind) => resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, from, kind, tag })))))
+            .thenOnSuccess(async ({ typed, from, kind, tag }) => {
+            const query = Object.assign(Object.assign(Object.assign(Object.assign({ linkedFrom: from }, (kind !== undefined ? { kind } : {})), (tag !== undefined ? { tag } : {})), (typed.hops !== undefined ? { hops: typed.hops } : {})), (typed.limit !== undefined ? { limit: typed.limit } : {}));
+            return (await ctx.retriever.retrieve(query)).onSuccess((records) => succeed({ seed: from, count: records.length, results: records.map((r) => projectItem(ctx, r)) }));
+        })
+    };
+}
+function buildDeleteTool(ctx) {
+    return {
+        config: {
+            type: 'client_tool',
+            name: 'memory_delete',
+            description: 'Delete a memory record by (kind, entityId). Destructive for non-temporal kinds.',
+            parametersSchema: deleteSchema,
+            annotations: DELETE_ANNOTATIONS
+        },
+        execute: async (args) => deleteSchema
+            .convert(args)
+            .withErrorFormat((msg) => `memory_delete: invalid arguments: ${msg}`)
+            .onSuccess((typed) => assertKindEnabled(ctx, typed.kind).onSuccess((kind) => Convert.entityId.convert(typed.entityId).onSuccess((entityId) => succeed({ kind, entityId }))))
+            .thenOnSuccess(async ({ kind, entityId }) => (await ctx.store.delete(kind, entityId)).onSuccess((id) => succeed({ deleted: true, id, entityId, kind })))
+    };
+}
+/** Validate an optional `tag` string (`undefined` passes through). */
+function resolveOptionalTag(tagStr) {
+    if (tagStr === undefined) {
+        return succeed(undefined);
+    }
+    return Convert.tag.convert(tagStr);
+}
+/** Ordered registry of the five tool builders, keyed by name. */
+const TOOL_BUILDERS = [
+    { name: 'memory_write', build: buildWriteTool },
+    { name: 'memory_read', build: buildReadTool },
+    { name: 'memory_search', build: buildSearchTool },
+    { name: 'memory_context', build: buildContextTool },
+    { name: 'memory_delete', build: buildDeleteTool }
+];
+/**
+ * Build the selected suite of memory `AiAssist.IAiClientTool`s over a
+ * pre-scoped store — ready to hand to `AiAssist.executeClientToolTurn` (and, via
+ * the shared `JsonSchema.object(...)` schemas, `@fgv/ts-extras-mcp`).
+ *
+ * @remarks
+ * **Scope isolation is make-or-break.** The returned tools close over the
+ * pre-scoped {@link ICreateMemoryToolsParams.store | store}; no tool's
+ * `parametersSchema` declares a `scope` (or any scope-widening) property, so an
+ * LLM cannot steer a tool at another actor's memory. The store instance is the
+ * sole scope authority.
+ *
+ * The default selection is {@link DEFAULT_MEMORY_TOOLS} (the read-only set) —
+ * `memory_write` / `memory_delete` are included only when named in
+ * {@link ICreateMemoryToolsParams.tools | tools}.
+ * @public
+ */
+export function createMemoryTools(params) {
+    var _a;
+    const ctx = {
+        store: params.store,
+        retriever: params.retriever,
+        registry: params.registry,
+        kinds: params.kinds,
+        codecs: params.codecs,
+        defaultCodec: params.defaultCodec,
+        handleFor: params.handleFor
+    };
+    const selected = new Set((_a = params.tools) !== null && _a !== void 0 ? _a : DEFAULT_MEMORY_TOOLS);
+    return TOOL_BUILDERS.filter((builder) => selected.has(builder.name)).map((builder) => builder.build(ctx));
+}
+//# sourceMappingURL=memoryTools.js.map

package/dist/packlets/tools/memoryTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryTools.js","sourceRoot":"","sources":["../../../src/packlets/tools/memoryTools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAgE,MAAM,UAAU,CAAC;AACjG,OAAO,EAA0B,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAgB1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkC,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;AAsHvG,8EAA8E;AAC9E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E;AAE9E,yEAAyE;AACzE,kDAAkD;AAClD,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC;IAC1E,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,mCAAmC,EAAE,CAAC;IAC/E,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC,CAAC;CACtG,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wDAAwD,EAAE,CAAC;IAClG,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC;QAC1B,WAAW,EACT,8FAA8F;KACjG,CAAC;IACF,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gEAAgE,EAAE,CAAC;IAC1G,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;IAC/F,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;CAC7D,CAAC,CAAC;AAGH,kDAAkD;AAClD,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAC5D,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,+BAA+B,EAAE,CAAC;CAC9E,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAC5D,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,iCAAiC,EAAE,CAAC;CAChF,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC,CAAC;IACvF,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wCAAwC,EAAE,CAAC,CAAC;IACtG,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAC3B,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8DAA8D,EAAE,CAAC,CACnG;IACD,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,sCAAsC,EAAE,CAAC,CAAC;CACxG,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2CAA2C,EAAE,CAAC;IACrF,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wCAAwC,EAAE,CAAC,CAAC;IACvG,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,6CAA6C,EAAE,CAAC,CAAC;IAC3G,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,4BAA4B,EAAE,CAAC,CAAC;IAC5F,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,sCAAsC,EAAE,CAAC,CAAC;CACxG,CAAC,CAAC;AAEH,8EAA8E;AAC9E,gFAAgF;AAChF,wEAAwE;AACxE,8EAA8E;AAE9E,MAAM,qBAAqB,GAAgC;IACzD,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,KAAK;CACrB,CAAC;AAEF,MAAM,iBAAiB,GAAgC;IACrD,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;CACrB,CAAC;AAEF,MAAM,kBAAkB,GAAgC;IACtD,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACrB,CAAC;AAEF,8EAA8E;AAC9E,yCAAyC;AACzC,8EAA8E;AAE9E,sFAAsF;AACtF,SAAS,iBAAiB,CAAC,GAAiB,EAAE,OAAe;IAC3D,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACtD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,uBAAuB,IAAI,oCAAoC,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC,uBAAuB,IAAI,mCAAmC,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6FAA6F;AAC7F,SAAS,mBAAmB,CAAC,GAAiB,EAAE,OAAgB;IAC9D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED,sGAAsG;AACtG,SAAS,WAAW,CAAC,GAAiB,EAAE,MAA8B;IACpE,yFAAyF;IACzF,0EAA0E;IAC1E,MAAM,MAAM,GACV,GAAG,CAAC,SAAS,KAAK,SAAS;QACzB,CAAC,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,SAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3E,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzB,OAAO;QACL,MAAM;QACN,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;QAC1B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;QAClC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;QAC1B,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,SAAS,aAAa,CAAC,GAAiB,EAAE,IAAU;;IAClD,MAAM,KAAK,GAA+B,MAAA,MAAA,GAAG,CAAC,MAAM,0CAAE,GAAG,CAAC,IAAI,CAAC,mCAAI,GAAG,CAAC,YAAY,CAAC;IACpF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,uDAAuD,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED,8FAA8F;AAC9F,SAAS,gBAAgB,CACvB,KAAgB,EAChB,IAAU,EACV,QAAkB,EAClB,MAAc;;IAEd,yEAAyE;IACzE,yEAAyE;IACzE,MAAM,KAAK,GAA2C,CAAC,MAAA,KAAK,CAAC,KAAK,mCAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBACtF,IAAI,EAAE,IAAI,CAAC,IAAI,EACf,MAAM,EAAE,IAAI,CAAC,MAAM,IAChB,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACzE,CAAC,CAAC;IACJ,OAAO,iBAAiB;SACrB,OAAO,CAAC;QACP,EAAE,EAAE,MAAM;QACV,QAAQ;QACR,IAAI;QACJ,IAAI,EAAE,MAAA,KAAK,CAAC,IAAI,mCAAI,EAAE;QACtB,KAAK;QACL,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,GAAG,EAAE,CAAC;QACN,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;KAChC,CAAC;SACD,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iCAAiC,GAAG,EAAE,CAAC;SAChE,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,uFAAuF;AACvF,SAAS,YAAY,CACnB,GAAiB,EACjB,KAAgB;IAEhB,OAAO,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAC9D,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3C,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QACxC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,0CAA0C,IAAI,oBAAoB,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAC/E,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CACpC,CAAC;IACJ,CAAC,CAAC,CACH,CACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CACnB,MAA0C,EAC1C,OAA+B,EAC/B,QAAkB;IAElB,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACzE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,iFAAiF;AACjF,+EAA+E;AAC/E,yDAAyD;AACzD,EAAE;AACF,kFAAkF;AAClF,kFAAkF;AAClF,oFAAoF;AACpF,oFAAoF;AACpF,8EAA8E;AAC9E,qFAAqF;AACrF,2EAA2E;AAC3E,kEAAkE;AAClE,8EAA8E;AAE9E,SAAS,cAAc,CAAC,GAAiB;IACvC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,2EAA2E;gBAC3E,gEAAgE;YAClE,gBAAgB,EAAE,WAAW;YAC7B,WAAW,EAAE,iBAAiB;SAC/B;QACD,OAAO,EAAE,KAAK,EAAE,IAAa,EAA4B,EAAE,CACzD,WAAW;aACR,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,oCAAoC,GAAG,EAAE,CAAC;aACnE,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;aAC9C,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE;QAClD,wEAAwE;QACxE,qEAAqE;QACrE,2EAA2E;QAC3E,uEAAuE;QACvE,6CAA6C;QAC7C,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CACnE,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CACpD,OAAO,CAAqB;YAC1B,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;YAClD,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE;YACzB,QAAQ;YACR,IAAI;SACL,CAAC,CACH,CACF,CACF;KACN,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,GAAiB;IACtC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,oDAAoD;YACjE,gBAAgB,EAAE,UAAU;YAC5B,WAAW,EAAE,qBAAqB;SACnC;QACD,OAAO,EAAE,KAAK,EAAE,IAAa,EAA4B,EAAE,CACzD,UAAU;aACP,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mCAAmC,GAAG,EAAE,CAAC;aAClE,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAC9F,CACF;aACA,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAC1C,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CACzD,MAAM,KAAK,SAAS;YAClB,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC3B,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAC7D,CACF;KACN,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAiB;IACxC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,eAAe;YACrB,WAAW,EAAE,yEAAyE;YACtF,gBAAgB,EAAE,YAAY;YAC9B,WAAW,EAAE,qBAAqB;SACnC;QACD,OAAO,EAAE,KAAK,EAAE,IAAa,EAA4B,EAAE,CACzD,YAAY;aACT,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,qCAAqC,GAAG,EAAE,CAAC;aACpE,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACtD,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAChF,CACF;aACA,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE;YAC5C,MAAM,KAAK,+DACN,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GACpC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAClC,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAClE,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7D,CAAC;YACF,OAAO,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CACjE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACrF,CAAC;QACJ,CAAC,CAAC;KACP,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAiB;IACzC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,gBAAgB;YACtB,WAAW,EACT,wGAAwG;YAC1G,gBAAgB,EAAE,aAAa;YAC/B,WAAW,EAAE,qBAAqB;SACnC;QACD,OAAO,EAAE,KAAK,EAAE,IAAa,EAA4B,EAAE,CACzD,aAAa;aACV,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,sCAAsC,GAAG,EAAE,CAAC;aACrE,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,OAAO,CAAC,QAAQ;aACb,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;aACnB,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAClB,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACtD,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CACtF,CACF,CACJ;aACA,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE;YAClD,MAAM,KAAK,6DACT,UAAU,EAAE,IAAI,IACb,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GACpC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAClC,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GACtD,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7D,CAAC;YACF,OAAO,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CACjE,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACjG,CAAC;QACJ,CAAC,CAAC;KACP,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAiB;IACxC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,eAAe;YACrB,WAAW,EAAE,iFAAiF;YAC9F,gBAAgB,EAAE,YAAY;YAC9B,WAAW,EAAE,kBAAkB;SAChC;QACD,OAAO,EAAE,KAAK,EAAE,IAAa,EAA4B,EAAE,CACzD,YAAY;aACT,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,qCAAqC,GAAG,EAAE,CAAC;aACpE,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAC9F,CACF;aACA,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAC1C,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CACxD,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CACF;KACN,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,iEAAiE;AACjE,MAAM,aAAa,GAGd;IACH,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE;IAC/C,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7C,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE;IACjD,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,EAAE;IACnD,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE;CAClD,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAgC;;IAChE,MAAM,GAAG,GAAiB;QACxB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;IACF,MAAM,QAAQ,GAAgC,IAAI,GAAG,CAAiB,MAAA,MAAM,CAAC,KAAK,mCAAI,oBAAoB,CAAC,CAAC;IAC5G,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5G,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport { JsonSchema } from '@fgv/ts-json-base';\nimport { AiAssist } from '@fgv/ts-extras';\nimport { Convert, EntityId, IIdentityCodec, IMemoryRecord, Kind, MemoryId, Tag } from '../types';\nimport { IBodyConverterRegistry, envelopeConverter } from '../converters';\nimport { IMemoryStore } from '../store';\nimport { IMemoryQuery, IMemoryRetriever } from '../retrieve';\n\n/**\n * The names of the five proof-set memory tools. A caller selects a subset via\n * {@link ICreateMemoryToolsParams.tools | tools}.\n * @public\n */\nexport type MemoryToolName =\n  | 'memory_write'\n  | 'memory_read'\n  | 'memory_search'\n  | 'memory_context'\n  | 'memory_delete';\n\n/**\n * The default tool subset when {@link ICreateMemoryToolsParams.tools | tools} is\n * omitted: the read-only set. Mutating tools (`memory_write` / `memory_delete`)\n * are **off by default** and must be named explicitly — writes stay\n * curation-mediated unless the host opts in.\n * @public\n */\nexport const DEFAULT_MEMORY_TOOLS: ReadonlyArray<MemoryToolName> = ['memory_search', 'memory_context'];\n\n/**\n * Discriminates the outcome of a {@link createMemoryTools | memory_write} call so\n * the agent can reason about what its write actually did.\n *\n * @remarks\n * - `written` — a new record was persisted, or an existing entity was updated.\n * - `deduped` — the content already existed (content-hash dedup no-op); the\n *   store returned the existing record unchanged.\n *\n * The store's public `put` return does not surface cap-cull evictions, so a\n * `culled` outcome is not distinguishable at this layer without an L1 change or\n * observer wiring (both out of scope for L2). The writer's own record is always\n * `written` even when the write triggers a cull of older siblings.\n * @public\n */\nexport type MemoryWriteOutcome = 'written' | 'deduped';\n\n/**\n * The success value returned by `memory_write.execute`.\n * @public\n */\nexport interface IMemoryWriteResult {\n  /** What the write did — see {@link MemoryWriteOutcome}. */\n  readonly outcome: MemoryWriteOutcome;\n  /** The stored record's {@link MemoryId}. */\n  readonly id: MemoryId;\n  /** The domain {@link EntityId} the write targeted. */\n  readonly entityId: EntityId;\n  /** The record's {@link Kind}. */\n  readonly kind: Kind;\n}\n\n/**\n * A single agent-visible search / context result item. The agent-facing key is\n * {@link IMemoryToolResultItem.handle | handle}: the host mnemonic when a\n * {@link ICreateMemoryToolsParams.handleFor | handleFor} hook is supplied, else\n * the raw {@link MemoryId}.\n * @public\n */\nexport interface IMemoryToolResultItem {\n  /** The agent-visible key (host handle when supplied, raw {@link MemoryId} otherwise). */\n  readonly handle: string;\n  /** The record's {@link Kind}. */\n  readonly kind: Kind;\n  /** The record's domain {@link EntityId}. */\n  readonly entityId: EntityId;\n  /** The record's tags. */\n  readonly tags: ReadonlyArray<string>;\n  /** The record body (a markdown string in B1). */\n  readonly body: unknown;\n}\n\n/**\n * Parameters for {@link createMemoryTools}.\n *\n * @remarks\n * **Scope isolation is constructor-fixed.** The {@link\n * ICreateMemoryToolsParams.store | store} is the sole scope authority — it is the\n * actor's own, pre-scoped memory root. No tool's `parametersSchema` declares a\n * `scope` (or any scope-widening) property, so an LLM cannot steer a tool at\n * another actor's memory.\n * @public\n */\nexport interface ICreateMemoryToolsParams {\n  /**\n   * The pre-scoped memory store (the actor's own memory root). Sole scope\n   * authority — backs `memory_write` / `memory_read` / `memory_delete`.\n   */\n  readonly store: IMemoryStore;\n  /** Retriever backing `memory_search` (and `memory_context` via link traversal). */\n  readonly retriever: IMemoryRetriever;\n  /** Body converter registry — gates the toolable kinds via `has(kind)`. */\n  readonly registry: IBodyConverterRegistry;\n  /**\n   * The per-tool enable subset. Defaults to {@link DEFAULT_MEMORY_TOOLS} (the\n   * read-only set). Name `memory_write` / `memory_delete` here to opt into the\n   * mutating tools.\n   */\n  readonly tools?: ReadonlyArray<MemoryToolName>;\n  /**\n   * Optional whitelist of toolable kinds. When present, a tool `kind` argument\n   * outside this set is rejected. When absent, {@link\n   * IBodyConverterRegistry.has | registry.has} is the sole kind gate.\n   */\n  readonly kinds?: ReadonlyArray<Kind>;\n  /**\n   * Per-kind identity codecs, used by `memory_write` to map the domain\n   * {@link EntityId} to the record's storage id (the store resolves codecs\n   * internally for `get` / `delete`, so read / delete do not need them). Absent\n   * → `memory_write` uses {@link ICreateMemoryToolsParams.defaultCodec |\n   * defaultCodec}, and fails loudly for a kind with no resolvable codec. The\n   * read-only default tool set needs no codecs.\n   */\n  readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;\n  /** Default identity codec for kinds without an explicit {@link ICreateMemoryToolsParams.codecs | codecs} entry. */\n  readonly defaultCodec?: IIdentityCodec;\n  /**\n   * Optional host hook mapping a record to its agent-visible handle (an evocative\n   * mnemonic tag). When supplied, `memory_search` / `memory_context` results use\n   * the returned handle as the agent-visible key; when absent the raw\n   * {@link MemoryId} is used.\n   */\n  readonly handleFor?: (record: IMemoryRecord<unknown>) => string;\n}\n\n/** The resolved factory context threaded into each tool's `execute`. */\ninterface IToolContext {\n  readonly store: IMemoryStore;\n  readonly retriever: IMemoryRetriever;\n  readonly registry: IBodyConverterRegistry;\n  readonly kinds?: ReadonlyArray<Kind>;\n  readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;\n  readonly defaultCodec?: IIdentityCodec;\n  readonly handleFor?: (record: IMemoryRecord<unknown>) => string;\n}\n\n// ---------------------------------------------------------------------------\n// Parameter schemas — authored once via JsonSchema.object(...); the schema IS\n// both the wire schema (.toJson()) and the runtime validator (.convert()).\n// NONE of these declare a `scope` (or scope-widening) property — the adoption\n// gate is enforced structurally and asserted in the tests.\n// ---------------------------------------------------------------------------\n\n/** A single attributed link edge as authored by the agent on a write. */\n// eslint-disable-next-line @rushstack/typedef-var\nconst linkEdgeSchema = JsonSchema.object({\n  type: JsonSchema.string({ description: 'The relation type of the link.' }),\n  target: JsonSchema.string({ description: 'The MemoryId this edge points at.' }),\n  confidence: JsonSchema.optional(JsonSchema.number({ description: 'Optional confidence in [0, 1].' }))\n});\n\n// eslint-disable-next-line @rushstack/typedef-var\nconst writeSchema = JsonSchema.object({\n  kind: JsonSchema.string({ description: 'The record kind (must be an enabled, registered kind).' }),\n  entityId: JsonSchema.string({\n    description:\n      'The domain entity id. For composite (e.g. medium-term) kinds this is the full composite key.'\n  }),\n  body: JsonSchema.string({ description: \"The serialized record body; validated by the kind's converter.\" }),\n  tags: JsonSchema.optional(JsonSchema.array(JsonSchema.string({ description: 'A tag label.' }))),\n  links: JsonSchema.optional(JsonSchema.array(linkEdgeSchema))\n});\ntype WriteArgs = JsonSchema.Static<typeof writeSchema>;\n\n// eslint-disable-next-line @rushstack/typedef-var\nconst readSchema = JsonSchema.object({\n  kind: JsonSchema.string({ description: 'The record kind.' }),\n  entityId: JsonSchema.string({ description: 'The domain entity id to read.' })\n});\n\n// eslint-disable-next-line @rushstack/typedef-var\nconst deleteSchema = JsonSchema.object({\n  kind: JsonSchema.string({ description: 'The record kind.' }),\n  entityId: JsonSchema.string({ description: 'The domain entity id to delete.' })\n});\n\n// eslint-disable-next-line @rushstack/typedef-var\nconst searchSchema = JsonSchema.object({\n  kind: JsonSchema.optional(JsonSchema.string({ description: 'Restrict to this kind.' })),\n  tag: JsonSchema.optional(JsonSchema.string({ description: 'Restrict to records carrying this tag.' })),\n  semantic: JsonSchema.optional(\n    JsonSchema.string({ description: 'Semantic query text (requires a semantic-capable retriever).' })\n  ),\n  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))\n});\n\n// eslint-disable-next-line @rushstack/typedef-var\nconst contextSchema = JsonSchema.object({\n  from: JsonSchema.string({ description: 'The seed MemoryId to traverse links from.' }),\n  kind: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records to this kind.' })),\n  tag: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records carrying this tag.' })),\n  hops: JsonSchema.optional(JsonSchema.integer({ description: 'BFS hop count (default 1).' })),\n  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))\n});\n\n// ---------------------------------------------------------------------------\n// Behavior annotations (Component 4) — host-advisory hints; never serialized to\n// the model. openWorldHint is false throughout (a closed, local store).\n// ---------------------------------------------------------------------------\n\nconst READ_ONLY_ANNOTATIONS: AiAssist.IAiToolAnnotations = {\n  readOnlyHint: true,\n  openWorldHint: false\n};\n\nconst WRITE_ANNOTATIONS: AiAssist.IAiToolAnnotations = {\n  destructiveHint: false,\n  idempotentHint: false,\n  openWorldHint: false\n};\n\nconst DELETE_ANNOTATIONS: AiAssist.IAiToolAnnotations = {\n  destructiveHint: true,\n  idempotentHint: true,\n  openWorldHint: false\n};\n\n// ---------------------------------------------------------------------------\n// Shared validation / projection helpers\n// ---------------------------------------------------------------------------\n\n/** Validate a `kind` string and assert it is an enabled, registered toolable kind. */\nfunction assertKindEnabled(ctx: IToolContext, kindStr: string): Result<Kind> {\n  return Convert.kind.convert(kindStr).onSuccess((kind) => {\n    if (!ctx.registry.has(kind)) {\n      return fail(`memory tools: kind '${kind}' has no registered body converter`);\n    }\n    if (ctx.kinds !== undefined && !ctx.kinds.includes(kind)) {\n      return fail(`memory tools: kind '${kind}' is not enabled for memory tools`);\n    }\n    return succeed(kind);\n  });\n}\n\n/** Validate an optional `kind` string (enabled when present; `undefined` passes through). */\nfunction resolveOptionalKind(ctx: IToolContext, kindStr?: string): Result<Kind | undefined> {\n  if (kindStr === undefined) {\n    return succeed(undefined);\n  }\n  return assertKindEnabled(ctx, kindStr);\n}\n\n/** Project a record into an agent-visible result item, applying the host handle hook when present. */\nfunction projectItem(ctx: IToolContext, record: IMemoryRecord<unknown>): IMemoryToolResultItem {\n  // `handleFor` is a host callback; guard it so a throw degrades to the raw id rather than\n  // escaping the Result chain (and crashing the whole search/context call).\n  const handle =\n    ctx.handleFor !== undefined\n      ? captureResult(() => ctx.handleFor!(record)).orDefault(record.envelope.id)\n      : record.envelope.id;\n  return {\n    handle,\n    kind: record.envelope.kind,\n    entityId: record.envelope.entityId,\n    tags: record.envelope.tags,\n    body: record.body\n  };\n}\n\n/** Resolve the identity codec used by `memory_write` to derive the storage id. */\nfunction codecForWrite(ctx: IToolContext, kind: Kind): Result<IIdentityCodec> {\n  const codec: IIdentityCodec | undefined = ctx.codecs?.get(kind) ?? ctx.defaultCodec;\n  if (codec === undefined) {\n    return fail(`memory_write: no identity codec available for kind '${kind}'`);\n  }\n  return succeed(codec);\n}\n\n/** Build the record to persist from validated write args (store stamps txn-time metadata). */\nfunction buildWriteRecord(\n  typed: WriteArgs,\n  kind: Kind,\n  entityId: EntityId,\n  idStem: string\n): Result<IMemoryRecord<unknown>> {\n  // Plain shapes handed to `envelopeConverter`, which validates each field\n  // (type → LinkType, target → MemoryId) and produces the branded IEdge[].\n  const links: ReadonlyArray<Record<string, unknown>> = (typed.links ?? []).map((link) => ({\n    type: link.type,\n    target: link.target,\n    ...(link.confidence !== undefined ? { confidence: link.confidence } : {})\n  }));\n  return envelopeConverter\n    .convert({\n      id: idStem,\n      entityId,\n      kind,\n      tags: typed.tags ?? [],\n      links,\n      created: 0,\n      updated: 0,\n      seq: 0,\n      contentHash: '',\n      provenance: { source: 'agent' }\n    })\n    .withErrorFormat((msg) => `memory_write: invalid record: ${msg}`)\n    .onSuccess((envelope) => succeed({ envelope, body: typed.body }));\n}\n\n/** Resolve the validated write args into the storage id + record (all synchronous). */\nfunction prepareWrite(\n  ctx: IToolContext,\n  typed: WriteArgs\n): Result<{ readonly kind: Kind; readonly entityId: EntityId; readonly record: IMemoryRecord<unknown> }> {\n  return assertKindEnabled(ctx, typed.kind).onSuccess((kind) =>\n    Convert.entityId.convert(typed.entityId).onSuccess((entityId) =>\n      codecForWrite(ctx, kind).onSuccess((codec) =>\n        codec.encode(entityId).onSuccess((addr) => {\n          if (addr.isVersioned) {\n            return fail(`memory_write: versioned/temporal kind '${kind}' is not supported`);\n          }\n          return buildWriteRecord(typed, kind, entityId, addr.idStem).onSuccess((record) =>\n            succeed({ kind, entityId, record })\n          );\n        })\n      )\n    )\n  );\n}\n\n/**\n * Discriminate the write outcome from a pre-put snapshot and the returned record.\n * A dedup no-op returns either a different entity (content-scope dedup) or the\n * same-id record with an unchanged `seq` (entity-scope re-put); a fresh write or\n * update advances `seq`.\n */\nfunction writeOutcome(\n  before: IMemoryRecord<unknown> | undefined,\n  written: IMemoryRecord<unknown>,\n  entityId: EntityId\n): MemoryWriteOutcome {\n  if (written.envelope.entityId !== entityId) {\n    return 'deduped';\n  }\n  if (before !== undefined && written.envelope.seq === before.envelope.seq) {\n    return 'deduped';\n  }\n  return 'written';\n}\n\n// ---------------------------------------------------------------------------\n// Tool builders — config with a JsonSchema.object(...) parametersSchema; execute\n// validates/narrows → delegates to store/retriever → returns the Result (never\n// swallowed), following the ts-extras-mcp adapter shape.\n//\n// Each `execute` re-runs its own `parametersSchema.convert(args)` even though the\n// `executeClientToolTurn` harness already validates against the same schema. This\n// is deliberate: the factory returns a heterogeneous `ReadonlyArray<IAiClientTool>`\n// (TParams erased to `unknown`, since the members carry different param shapes), so\n// `execute` receives `unknown` and must narrow it back to the typed args. The\n// re-validation is also the narrowing step exercised by the direct-call tests (which\n// invoke `execute` with raw args, bypassing the harness). Re-validating an\n// already-conforming shape is a cheap, side-effect-free identity.\n// ---------------------------------------------------------------------------\n\nfunction buildWriteTool(ctx: IToolContext): AiAssist.IAiClientTool {\n  return {\n    config: {\n      type: 'client_tool',\n      name: 'memory_write',\n      description:\n        'Store a new memory record or update an existing one by (kind, entityId). ' +\n        'Identical content is a no-op that returns the existing record.',\n      parametersSchema: writeSchema,\n      annotations: WRITE_ANNOTATIONS\n    },\n    execute: async (args: unknown): Promise<Result<unknown>> =>\n      writeSchema\n        .convert(args)\n        .withErrorFormat((msg) => `memory_write: invalid arguments: ${msg}`)\n        .onSuccess((typed) => prepareWrite(ctx, typed))\n        .thenOnSuccess(async ({ kind, entityId, record }) =>\n          // Read the prior record to discriminate written-vs-deduped. A `Failure`\n          // here (corrupt file, I/O error, codec round-trip failure) is a real\n          // condition distinct from the \"not found\" success (`undefined`); propagate\n          // it rather than defaulting it away, so a genuine store fault surfaces\n          // instead of being masked as a normal write.\n          (await ctx.store.get(kind, entityId)).thenOnSuccess(async (before) =>\n            (await ctx.store.put(record)).onSuccess((persisted) =>\n              succeed<IMemoryWriteResult>({\n                outcome: writeOutcome(before, persisted, entityId),\n                id: persisted.envelope.id,\n                entityId,\n                kind\n              })\n            )\n          )\n        )\n  };\n}\n\nfunction buildReadTool(ctx: IToolContext): AiAssist.IAiClientTool {\n  return {\n    config: {\n      type: 'client_tool',\n      name: 'memory_read',\n      description: 'Read a specific memory record by (kind, entityId).',\n      parametersSchema: readSchema,\n      annotations: READ_ONLY_ANNOTATIONS\n    },\n    execute: async (args: unknown): Promise<Result<unknown>> =>\n      readSchema\n        .convert(args)\n        .withErrorFormat((msg) => `memory_read: invalid arguments: ${msg}`)\n        .onSuccess((typed) =>\n          assertKindEnabled(ctx, typed.kind).onSuccess((kind) =>\n            Convert.entityId.convert(typed.entityId).onSuccess((entityId) => succeed({ kind, entityId }))\n          )\n        )\n        .thenOnSuccess(async ({ kind, entityId }) =>\n          (await ctx.store.get(kind, entityId)).onSuccess((record) =>\n            record === undefined\n              ? succeed({ found: false })\n              : succeed({ found: true, item: projectItem(ctx, record) })\n          )\n        )\n  };\n}\n\nfunction buildSearchTool(ctx: IToolContext): AiAssist.IAiClientTool {\n  return {\n    config: {\n      type: 'client_tool',\n      name: 'memory_search',\n      description: 'Search memories by tag, kind, or semantic text. Returns ranked results.',\n      parametersSchema: searchSchema,\n      annotations: READ_ONLY_ANNOTATIONS\n    },\n    execute: async (args: unknown): Promise<Result<unknown>> =>\n      searchSchema\n        .convert(args)\n        .withErrorFormat((msg) => `memory_search: invalid arguments: ${msg}`)\n        .onSuccess((typed) =>\n          resolveOptionalKind(ctx, typed.kind).onSuccess((kind) =>\n            resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, kind, tag }))\n          )\n        )\n        .thenOnSuccess(async ({ typed, kind, tag }) => {\n          const query: IMemoryQuery = {\n            ...(kind !== undefined ? { kind } : {}),\n            ...(tag !== undefined ? { tag } : {}),\n            ...(typed.semantic !== undefined ? { semantic: typed.semantic } : {}),\n            ...(typed.limit !== undefined ? { limit: typed.limit } : {})\n          };\n          return (await ctx.retriever.retrieve(query)).onSuccess((records) =>\n            succeed({ count: records.length, results: records.map((r) => projectItem(ctx, r)) })\n          );\n        })\n  };\n}\n\nfunction buildContextTool(ctx: IToolContext): AiAssist.IAiClientTool {\n  return {\n    config: {\n      type: 'client_tool',\n      name: 'memory_context',\n      description:\n        'Build a context graph from a seed memory: returns the records linked from the seed, up to `hops` hops.',\n      parametersSchema: contextSchema,\n      annotations: READ_ONLY_ANNOTATIONS\n    },\n    execute: async (args: unknown): Promise<Result<unknown>> =>\n      contextSchema\n        .convert(args)\n        .withErrorFormat((msg) => `memory_context: invalid arguments: ${msg}`)\n        .onSuccess((typed) =>\n          Convert.memoryId\n            .convert(typed.from)\n            .onSuccess((from) =>\n              resolveOptionalKind(ctx, typed.kind).onSuccess((kind) =>\n                resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, from, kind, tag }))\n              )\n            )\n        )\n        .thenOnSuccess(async ({ typed, from, kind, tag }) => {\n          const query: IMemoryQuery = {\n            linkedFrom: from,\n            ...(kind !== undefined ? { kind } : {}),\n            ...(tag !== undefined ? { tag } : {}),\n            ...(typed.hops !== undefined ? { hops: typed.hops } : {}),\n            ...(typed.limit !== undefined ? { limit: typed.limit } : {})\n          };\n          return (await ctx.retriever.retrieve(query)).onSuccess((records) =>\n            succeed({ seed: from, count: records.length, results: records.map((r) => projectItem(ctx, r)) })\n          );\n        })\n  };\n}\n\nfunction buildDeleteTool(ctx: IToolContext): AiAssist.IAiClientTool {\n  return {\n    config: {\n      type: 'client_tool',\n      name: 'memory_delete',\n      description: 'Delete a memory record by (kind, entityId). Destructive for non-temporal kinds.',\n      parametersSchema: deleteSchema,\n      annotations: DELETE_ANNOTATIONS\n    },\n    execute: async (args: unknown): Promise<Result<unknown>> =>\n      deleteSchema\n        .convert(args)\n        .withErrorFormat((msg) => `memory_delete: invalid arguments: ${msg}`)\n        .onSuccess((typed) =>\n          assertKindEnabled(ctx, typed.kind).onSuccess((kind) =>\n            Convert.entityId.convert(typed.entityId).onSuccess((entityId) => succeed({ kind, entityId }))\n          )\n        )\n        .thenOnSuccess(async ({ kind, entityId }) =>\n          (await ctx.store.delete(kind, entityId)).onSuccess((id) =>\n            succeed({ deleted: true, id, entityId, kind })\n          )\n        )\n  };\n}\n\n/** Validate an optional `tag` string (`undefined` passes through). */\nfunction resolveOptionalTag(tagStr?: string): Result<Tag | undefined> {\n  if (tagStr === undefined) {\n    return succeed(undefined);\n  }\n  return Convert.tag.convert(tagStr);\n}\n\n/** Ordered registry of the five tool builders, keyed by name. */\nconst TOOL_BUILDERS: ReadonlyArray<{\n  readonly name: MemoryToolName;\n  readonly build: (ctx: IToolContext) => AiAssist.IAiClientTool;\n}> = [\n  { name: 'memory_write', build: buildWriteTool },\n  { name: 'memory_read', build: buildReadTool },\n  { name: 'memory_search', build: buildSearchTool },\n  { name: 'memory_context', build: buildContextTool },\n  { name: 'memory_delete', build: buildDeleteTool }\n];\n\n/**\n * Build the selected suite of memory `AiAssist.IAiClientTool`s over a\n * pre-scoped store — ready to hand to `AiAssist.executeClientToolTurn` (and, via\n * the shared `JsonSchema.object(...)` schemas, `@fgv/ts-extras-mcp`).\n *\n * @remarks\n * **Scope isolation is make-or-break.** The returned tools close over the\n * pre-scoped {@link ICreateMemoryToolsParams.store | store}; no tool's\n * `parametersSchema` declares a `scope` (or any scope-widening) property, so an\n * LLM cannot steer a tool at another actor's memory. The store instance is the\n * sole scope authority.\n *\n * The default selection is {@link DEFAULT_MEMORY_TOOLS} (the read-only set) —\n * `memory_write` / `memory_delete` are included only when named in\n * {@link ICreateMemoryToolsParams.tools | tools}.\n * @public\n */\nexport function createMemoryTools(params: ICreateMemoryToolsParams): ReadonlyArray<AiAssist.IAiClientTool> {\n  const ctx: IToolContext = {\n    store: params.store,\n    retriever: params.retriever,\n    registry: params.registry,\n    kinds: params.kinds,\n    codecs: params.codecs,\n    defaultCodec: params.defaultCodec,\n    handleFor: params.handleFor\n  };\n  const selected: ReadonlySet<MemoryToolName> = new Set<MemoryToolName>(params.tools ?? DEFAULT_MEMORY_TOOLS);\n  return TOOL_BUILDERS.filter((builder) => selected.has(builder.name)).map((builder) => builder.build(ctx));\n}\n"]}

package/dist/packlets/types/identityCodec.js

@@ -6,6 +6,121 @@ import { fail, succeed } from '@fgv/ts-utils';
 import { Convert } from './ids';
 import { assertPortableFilenameStem } from './filenameSafety';
 /**
+ * Narrow an {@link IIdentityCodec} to {@link ITemporalIdentityCodec} by probing
+ * for the versioned methods. Used by the store when an `encode` result reports
+ * `isVersioned: true`.
+ * @public
+ */
+export function isTemporalIdentityCodec(codec) {
+    const candidate = codec;
+    return typeof candidate.encodeVersion === 'function' && typeof candidate.decodeVersion === 'function';
+}
+/**
+ * Identity codec for a versioned (temporal) kind family, resolving OQ-11 to the
+ * subtree-per-entity layout: every version of an entity is a distinct file under
+ * a per-entity subtree.
+ *
+ * @remarks
+ * - `encode`: scope = `<baseScope>/entities/<entityId>`, idStem = `<entityId>`,
+ *   `isVersioned = true`. The idStem is the stable entity prefix; the store forms
+ *   each version's filename via {@link TemporalIdentityCodec.encodeVersion}.
+ * - `encodeVersion`: version stem = `<entityId>-v<seq>`.
+ * - `decode` / `decodeVersion`: recover `entityId` (and `seq`) from a
+ *   `(subtree scope, version stem)` pair; the scope is authoritative for the
+ *   `entityId`.
+ * - Escaping: `baseScope` and `entityId` must each match the POSIX portable
+ *   filename set (they become path segments); `seq` is a non-negative integer.
+ * - Layout: `vault/<baseScope>/entities/<entityId>/<entityId>-v<seq>.md`.
+ * @public
+ */
+export class TemporalIdentityCodec {
+    constructor(baseScope) {
+        this.baseScope = baseScope;
+    }
+    /**
+     * Family-convention factory. Validates that `baseScope` is a single portable
+     * filename segment (it becomes the top-level path component).
+     */
+    static create(baseScope) {
+        return assertPortableFilenameStem(baseScope)
+            .withErrorFormat((msg) => `temporal codec: baseScope '${baseScope}': ${msg}`)
+            .onSuccess(() => succeed(new TemporalIdentityCodec(baseScope)));
+    }
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId) {
+        return assertPortableFilenameStem(entityId)
+            .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+            .onSuccess((stem) => succeed({
+            scope: `${this.baseScope}/${TemporalIdentityCodec.entitiesSegment}/${stem}`,
+            idStem: stem,
+            isVersioned: true
+        }));
+    }
+    /** {@inheritDoc ITemporalIdentityCodec.encodeVersion} */
+    encodeVersion(entityId, seq) {
+        return assertPortableFilenameStem(entityId)
+            .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+            .onSuccess((stem) => {
+            if (!Number.isInteger(seq) || seq < 0) {
+                return fail(`temporal codec: version seq '${seq}' must be a non-negative integer`);
+            }
+            return succeed(`${stem}${TemporalIdentityCodec.versionInfix}${seq}`);
+        });
+    }
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope, encodedStem) {
+        return this.decodeVersion(scope, encodedStem).onSuccess((addr) => Convert.entityId.convert(addr.entityId));
+    }
+    /** {@inheritDoc ITemporalIdentityCodec.decodeVersion} */
+    decodeVersion(scope, stem) {
+        return this._entityIdFromScope(scope).onSuccess((entityId) => {
+            const prefix = `${entityId}${TemporalIdentityCodec.versionInfix}`;
+            if (!stem.startsWith(prefix)) {
+                return fail(`temporal codec: version stem '${stem}' must begin with '${prefix}' (from scope '${scope}')`);
+            }
+            const seqText = stem.slice(prefix.length);
+            if (!TemporalIdentityCodec._versionSeqRe.test(seqText)) {
+                return fail(`temporal codec: version stem '${stem}' has a non-integer version suffix '${seqText}'`);
+            }
+            // The regex admits digit strings of unbounded length; `parseInt` would silently
+            // lose precision past MAX_SAFE_INTEGER, decoding a corrupt/tampered filename to a
+            // plausible-but-wrong `seq` that drives version ordering. Reject rather than corrupt.
+            const seq = Number.parseInt(seqText, 10);
+            if (!Number.isSafeInteger(seq)) {
+                return fail(`temporal codec: version stem '${stem}' has a version suffix '${seqText}' outside the safe integer range`);
+            }
+            return Convert.entityId.convert(entityId).onSuccess((branded) => succeed({ entityId: branded, seq }));
+        });
+    }
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope, stem) {
+        return this.decodeVersion(scope, stem).onSuccess((addr) => this.encode(addr.entityId).onSuccess((encoded) => this.encodeVersion(addr.entityId, addr.seq).onSuccess((reStem) => {
+            if (encoded.scope !== scope || reStem !== stem) {
+                return fail(`temporal codec: round-trip mismatch for scope '${scope}' stem '${stem}' (re-encoded to scope '${encoded.scope}' stem '${reStem}')`);
+            }
+            return succeed(true);
+        })));
+    }
+    /** Validate and extract the `entityId` from a `<baseScope>/entities/<entityId>` scope. */
+    _entityIdFromScope(scope) {
+        const segments = scope.split('/');
+        if (segments.length !== 3 ||
+            segments[0] !== this.baseScope ||
+            segments[1] !== TemporalIdentityCodec.entitiesSegment) {
+            return fail(`temporal codec: scope '${scope}' must be '${this.baseScope}/${TemporalIdentityCodec.entitiesSegment}/<entityId>'`);
+        }
+        const entityId = segments[2];
+        return assertPortableFilenameStem(entityId)
+            .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+            .onSuccess(() => succeed(entityId));
+    }
+}
+/** The fixed subtree segment separating an entity's versions from its scope. */
+TemporalIdentityCodec.entitiesSegment = 'entities';
+/** The version-stem infix: `<entityId>` + this + `<seq>`. */
+TemporalIdentityCodec.versionInfix = '-v';
+/** A non-negative integer string (the version seq). */
+TemporalIdentityCodec._versionSeqRe = /^\d+$/;
 /**
  * Identity codec for the knowledge kind family. A knowledge entity is keyed
  * by its consumer-supplied `docId`, which is used verbatim as the filename