@purista/harness 1.0.0 → 1.2.0

package/dist/ports/memory/facade.js

@@ -0,0 +1,123 @@
+import { ModelCapabilityError, ValidationError } from '../../errors/index.js';
+import { createMetrics } from '../../telemetry/index.js';
+import { attachContent, baseAttrs, errorType, hashKey, normalizeMemoryError, resultAttributes, shouldCaptureContent } from './telemetry.js';
+import { assertCapability, normalizeListOptions, normalizeSearchQuery, validateOperationInput } from './validation.js';
+/** Creates scoped memory helpers for a concrete session/run context. */
+export function createMemoryFacade(opts) {
+    const base = (scope) => createSessionMemory(opts, normalizeScope(opts, scope));
+    return {
+        session: base({ kind: 'session', sessionId: opts.sessionId }),
+        run: base({ kind: 'run', sessionId: opts.sessionId, runId: requireRunId(opts) }),
+        ...(opts.agentId ? { agent: base(definedScope({ kind: 'agent', sessionId: opts.sessionId, runId: opts.runId, agentId: opts.agentId, workflowId: opts.workflowId })) } : {}),
+        user(userId) {
+            return base(definedScope({ kind: 'user', sessionId: opts.sessionId, runId: opts.runId, agentId: opts.agentId, workflowId: opts.workflowId, userId: userId ?? metadataString(opts.metadata, 'userId') }));
+        },
+        tenant(tenantId) {
+            return base(definedScope({ kind: 'tenant', sessionId: opts.sessionId, runId: opts.runId, agentId: opts.agentId, workflowId: opts.workflowId, tenantId: tenantId ?? metadataString(opts.metadata, 'tenantId') }));
+        },
+        scope(scope) {
+            return base(scope);
+        }
+    };
+}
+/** Creates a key/value memory facade bound to one normalized scope. */
+export function createSessionMemory(opts, scope) {
+    const normalized = normalizeScope(opts, scope);
+    return {
+        read: (key) => runMemoryOperation(opts, normalized, 'get', key, undefined, async (store, ctx) => store.get(key, ctx)),
+        write: (key, value, writeOpts) => runMemoryOperation(opts, normalized, 'set', key, { value, ...(writeOpts ? { writeOpts } : {}) }, async (store, ctx) => store.set(key, value, { ...ctx, ...(writeOpts ? { opts: writeOpts } : {}) })),
+        delete: (key) => runMemoryOperation(opts, normalized, 'delete', key, undefined, async (store, ctx) => store.delete(key, ctx)),
+        list: async (listOpts) => {
+            const entries = await runMemoryOperation(opts, normalized, 'list', undefined, listOpts ? { listOpts } : undefined, async (store, ctx) => store.list({ ...ctx, opts: normalizeListOptions(listOpts) }));
+            return entries.map((entry) => entry.key).sort();
+        },
+        search: (query) => runMemoryOperation(opts, normalized, 'search', undefined, { query }, async (store, ctx) => {
+            assertCapability(opts.adapter, 'memory.search', 'search');
+            if (!store.search) {
+                throw new ModelCapabilityError('Memory search is not available for this adapter.', { alias: opts.adapter.info.id, method: 'memory.search', reason: 'method_missing' });
+            }
+            return store.search(normalizeSearchQuery(query), ctx);
+        })
+    };
+}
+async function runMemoryOperation(opts, scope, operation, key, content, fn) {
+    validateOperationInput(opts.adapter, scope, operation, key, content);
+    const metrics = createMetrics(opts.telemetry, baseAttrs(opts, scope, operation));
+    const started = Date.now();
+    let durationAttrs = {};
+    const attrs = {
+        ...baseAttrs(opts, scope, operation),
+        ...(key ? { 'harness.memory.key_hash': hashKey(key) } : {}),
+        'harness.memory.content_captured': shouldCaptureContent(opts.contentCaptureMode)
+    };
+    const context = {
+        logger: opts.logger,
+        telemetry: opts.telemetry,
+        metrics,
+        contentCaptureMode: opts.contentCaptureMode,
+        signal: opts.signal,
+        ...(opts.sandbox ? { sandbox: opts.sandbox } : {})
+    };
+    const execute = async (span) => {
+        if (shouldCaptureContent(opts.contentCaptureMode))
+            attachContent(span, opts.contentCaptureMode, operation, key, content);
+        try {
+            opts.signal.throwIfAborted();
+            const store = await opts.adapter.open(scope, context);
+            const result = await fn(store, { ...context, scope, operation });
+            const resultAttrs = resultAttributes(operation, result);
+            durationAttrs = resultAttrs;
+            span.setAttributes(resultAttrs);
+            metrics.counter('harness.memory.operations', 1, resultAttrs);
+            if (operation === 'search' && Array.isArray(result)) {
+                metrics.histogram('harness.memory.search.results', result.length);
+            }
+            return result;
+        }
+        catch (error) {
+            const normalized = normalizeMemoryError(opts.adapter, operation, error);
+            const errorAttrs = { 'error.type': errorType(normalized) };
+            durationAttrs = errorAttrs;
+            metrics.counter('harness.memory.operations', 1, errorAttrs);
+            throw normalized;
+        }
+        finally {
+            metrics.histogram('harness.memory.operation.duration', (Date.now() - started) / 1000, durationAttrs);
+        }
+    };
+    return opts.telemetry.span(`harness.memory.${operation}`, attrs, execute);
+}
+function normalizeScope(opts, scope) {
+    return {
+        sessionId: opts.sessionId,
+        ...(opts.runId ? { runId: opts.runId } : {}),
+        ...(opts.workflowId ? { workflowId: opts.workflowId } : {}),
+        ...(opts.agentId ? { agentId: opts.agentId } : {}),
+        ...scope
+    };
+}
+function definedScope(scope) {
+    const out = { kind: scope.kind };
+    if (scope.sessionId !== undefined)
+        out.sessionId = scope.sessionId;
+    if (scope.runId !== undefined)
+        out.runId = scope.runId;
+    if (scope.agentId !== undefined)
+        out.agentId = scope.agentId;
+    if (scope.workflowId !== undefined)
+        out.workflowId = scope.workflowId;
+    if (scope.userId !== undefined)
+        out.userId = scope.userId;
+    if (scope.tenantId !== undefined)
+        out.tenantId = scope.tenantId;
+    return out;
+}
+function requireRunId(opts) {
+    if (opts.runId)
+        return opts.runId;
+    throw new ValidationError('Run memory is only available inside a run.', { where: 'memory_scope', issues: { reason: 'missing_scope_identifier', field: 'runId', scope: 'run' } });
+}
+function metadataString(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/ports/memory/telemetry.d.ts

@@ -0,0 +1,16 @@
+import type { Span } from '@opentelemetry/api';
+import type { JsonValue } from '../../models/json.js';
+import type { SpanAttrs } from '../../telemetry/index.js';
+import type { CreateMemoryFacadeOptions, MemoryOperation, MemoryScope, MemorySearchQuery, MemoryWriteOptions } from './types.js';
+export declare const CONTENT_ATTR_LIMIT = 8192;
+export declare function baseAttrs(opts: CreateMemoryFacadeOptions, scope: MemoryScope, operation: MemoryOperation): SpanAttrs;
+export declare function resultAttributes(operation: MemoryOperation, result: unknown): SpanAttrs;
+export declare function hashKey(key: string): string;
+export declare function shouldCaptureContent(mode: CreateMemoryFacadeOptions['contentCaptureMode']): boolean;
+export declare function attachContent(span: Span, mode: CreateMemoryFacadeOptions['contentCaptureMode'], operation: MemoryOperation, key: string | undefined, content: {
+    value?: JsonValue;
+    writeOpts?: MemoryWriteOptions;
+    query?: MemorySearchQuery;
+} | undefined): void;
+export declare function normalizeMemoryError(adapter: CreateMemoryFacadeOptions['adapter'], operation: MemoryOperation, error: unknown): unknown;
+export declare function errorType(error: unknown): string;

package/dist/ports/memory/telemetry.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { OperationCancelledError, StateError } from '../../errors/index.js';
+import { scopeCapability } from './validation.js';
+export const CONTENT_ATTR_LIMIT = 8192;
+export function baseAttrs(opts, scope, operation) {
+    return {
+        'harness.name': opts.harnessName,
+        'harness.memory.provider': opts.adapter.info.id,
+        'harness.memory.operation': operation,
+        'harness.memory.scope': scope.kind,
+        'harness.memory.capability': operation === 'search' ? 'memory.search' : scopeCapability[scope.kind],
+        'harness.session.id': scope.sessionId,
+        'harness.run.id': scope.runId,
+        'harness.agent.id': scope.agentId,
+        'harness.workflow.id': scope.workflowId
+    };
+}
+export function resultAttributes(operation, result) {
+    if (operation === 'get')
+        return { 'harness.memory.hit': result !== undefined };
+    if (Array.isArray(result) && (operation === 'list' || operation === 'search'))
+        return { 'harness.memory.result_count': result.length };
+    return {};
+}
+export function hashKey(key) {
+    return createHash('sha256').update(key).digest('hex');
+}
+export function shouldCaptureContent(mode) {
+    return mode !== 'NO_CONTENT';
+}
+export function attachContent(span, mode, operation, key, content) {
+    const attrs = {
+        ...(key ? { 'harness.memory.key': key } : {}),
+        ...(content?.value !== undefined ? { 'harness.memory.value': limitedJson(content.value) } : {}),
+        ...(content?.query ? { 'harness.memory.query': content.query.text } : {})
+    };
+    if (mode === 'SPAN_ONLY' || mode === 'SPAN_AND_EVENT') {
+        span.setAttributes(attrs);
+    }
+    if (mode === 'EVENT_ONLY' || mode === 'SPAN_AND_EVENT') {
+        span.addEvent('harness.memory.content', cleanAttrs({ ...attrs, 'harness.memory.operation': operation }));
+    }
+}
+export function normalizeMemoryError(adapter, operation, error) {
+    if (error instanceof OperationCancelledError)
+        return error;
+    if (isAbortError(error))
+        return new OperationCancelledError('Memory operation was cancelled.', { scope: 'memory' }, error);
+    if (isHarnessError(error))
+        return error;
+    return new StateError('Memory adapter operation failed.', { op: `memory.${operation}`, adapter: 'memory', memory_provider: adapter.info.id }, error);
+}
+export function errorType(error) {
+    return isHarnessError(error) ? error.code : error instanceof Error ? error.name : 'Error';
+}
+function limitedJson(value) {
+    try {
+        return JSON.stringify(value).slice(0, CONTENT_ATTR_LIMIT);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function isHarnessError(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && 'category' in error);
+}
+function cleanAttrs(attrs) {
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}

package/dist/ports/memory/types.d.ts

@@ -0,0 +1,204 @@
+import type { Logger } from '../../logger/index.js';
+import type { ContentCaptureMode } from '../../harness/defineHarness.js';
+import type { JsonValue } from '../../models/json.js';
+import type { SandboxSession } from '../../sandbox/index.js';
+import type { Metrics, TelemetryShim } from '../../telemetry/index.js';
+import type { AdapterCapability, AdapterCapabilities } from '../capabilities.js';
+import type { HarnessContextConfigurable } from '../harness-context.js';
+/** Logical memory scope kinds supported by the harness facade. */
+export type MemoryScopeKind = 'run' | 'session' | 'agent' | 'user' | 'tenant';
+/**
+ * Concrete scope used to namespace memory entries.
+ *
+ * @example
+ * ```ts
+ * await ctx.memory.scope({ kind: 'user', userId: 'u_123' }).write('locale', 'de-DE')
+ * ```
+ */
+export interface MemoryScope {
+    /** Scope discriminator. */
+    kind: MemoryScopeKind;
+    /** Harness session id for session-local and run-local memory. */
+    sessionId?: string;
+    /** Harness run id for run-local memory. */
+    runId?: string;
+    /** Agent id for agent-scoped memory. */
+    agentId?: string;
+    /** Workflow id attached for observability when memory is used inside a workflow. */
+    workflowId?: string;
+    /** Application-owned user id for user-scoped memory. */
+    userId?: string;
+    /** Application-owned tenant id for tenant-scoped memory. */
+    tenantId?: string;
+}
+/** Adapter capabilities are normal harness adapter capabilities with memory-specific names. */
+export type MemoryCapability = Extract<AdapterCapability, `memory.${string}`>;
+/** Data-only adapter descriptor used for validation, inspection, and `.requires(...)`. */
+export interface MemoryAdapterInfo {
+    /** Stable adapter id, for example `sandbox_memory` or `redis_memory`. */
+    id: string;
+    /** Package that provides the adapter factory. */
+    packageName: string;
+    /** Optional adapter package version for diagnostics. */
+    version?: string;
+    /** Memory capabilities implemented by this adapter. */
+    capabilities: readonly MemoryCapability[];
+}
+/** Per-open context passed to memory adapters. Core owns the standard telemetry wrapper. */
+export interface MemoryOpenContext {
+    /** Harness logger inherited by the adapter. */
+    readonly logger: Logger;
+    /** Harness telemetry shim for adapter-specific nested spans. */
+    readonly telemetry: TelemetryShim;
+    /** Harness metrics helper for adapter-specific metrics. */
+    readonly metrics: Metrics;
+    /** Content capture policy; adapters must respect this for custom telemetry/logs. */
+    readonly contentCaptureMode: ContentCaptureMode;
+    /** Cancellation signal for the memory operation. */
+    readonly signal: AbortSignal;
+    /** Present for the core `sandboxMemory()` adapter and adapters that intentionally compose with the sandbox. */
+    readonly sandbox?: SandboxSession;
+}
+/** Operation names emitted as memory span/metric attributes. */
+export type MemoryOperation = 'get' | 'set' | 'delete' | 'list' | 'search';
+/** Per-operation context passed to memory stores. */
+export interface MemoryOperationContext extends MemoryOpenContext {
+    /** Concrete scope for this operation. */
+    readonly scope: MemoryScope;
+    /** Operation currently being executed. */
+    readonly operation: MemoryOperation;
+}
+/** Optional write behavior for adapters that support tags, metadata, or TTL. */
+export interface MemoryWriteOptions {
+    /** Positive expiry duration in milliseconds. Requires `memory.ttl`. */
+    ttlMs?: number;
+    /** Optional index/filter tags. */
+    tags?: readonly string[];
+    /** Optional JSON metadata stored beside the value. */
+    metadata?: Record<string, JsonValue>;
+}
+/** Listing options supported by the facade. */
+export interface MemoryListOptions {
+    /** Return keys with this prefix only. */
+    prefix?: string;
+    /** Maximum entries to return. Defaults to `100`, maximum `1000`. */
+    limit?: number;
+    /** Adapter-defined cursor; the built-in adapter treats this as the last key. */
+    cursor?: string;
+}
+/** Metadata-only memory entry returned from `list`. */
+export interface MemoryEntry {
+    /** Memory key without backend-specific path or extension. */
+    key: string;
+    /** ISO creation timestamp when the adapter tracks it. */
+    createdAt?: string;
+    /** ISO update timestamp when the adapter tracks it. */
+    updatedAt?: string;
+    /** ISO expiry timestamp when the adapter tracks TTL. */
+    expiresAt?: string;
+    /** Optional index/filter tags. */
+    tags?: readonly string[];
+    /** Optional JSON metadata. */
+    metadata?: Record<string, JsonValue>;
+}
+/** Text search query used by adapters with `memory.search`. */
+export interface MemorySearchQuery {
+    /** Search text. Empty strings are rejected before adapter I/O. */
+    text: string;
+    /** Maximum results. Defaults to `100`, maximum `1000`. */
+    limit?: number;
+    /** Optional tag filter. */
+    tags?: readonly string[];
+    /** Optional metadata filter. */
+    metadata?: Record<string, JsonValue>;
+}
+/** Search result returned by adapters with `memory.search`. */
+export interface MemorySearchResult {
+    /** Memory key for the matched entry. */
+    key: string;
+    /** Adapter-defined relevance score. */
+    score?: number;
+    /** Optional value payload. Treat as content for telemetry/logging. */
+    value?: JsonValue;
+    /** Optional JSON metadata. */
+    metadata?: Record<string, JsonValue>;
+}
+/** Backend store opened for one concrete memory scope. */
+export interface MemoryStore {
+    /** Reads a JSON value by key. */
+    get<T = JsonValue>(key: string, ctx: MemoryOperationContext): Promise<T | undefined>;
+    /** Writes a JSON value by key. */
+    set(key: string, value: JsonValue, ctx: MemoryOperationContext & {
+        opts?: MemoryWriteOptions;
+    }): Promise<void>;
+    /** Deletes a key if it exists. */
+    delete(key: string, ctx: MemoryOperationContext): Promise<void>;
+    /** Lists memory entries in the opened scope. */
+    list(ctx: MemoryOperationContext & {
+        opts?: MemoryListOptions;
+    }): Promise<MemoryEntry[]>;
+    /** Searches memory when the adapter advertises `memory.search`. */
+    search?(query: MemorySearchQuery, ctx: MemoryOperationContext): Promise<MemorySearchResult[]>;
+}
+/** Pluggable memory backend. External implementations belong in `@purista/harness-memory-*` packages. */
+export interface MemoryAdapter extends HarnessContextConfigurable, AdapterCapabilities {
+    /** Static adapter metadata used for validation and inspection. */
+    readonly info: MemoryAdapterInfo;
+    /** Adapter capability list mirrored from `info.capabilities`. */
+    readonly capabilities: readonly MemoryCapability[];
+    /** Opens a backend store for one scope. */
+    open(scope: MemoryScope, ctx: MemoryOpenContext): Promise<MemoryStore>;
+    /** Releases adapter-owned resources. */
+    close?(): Promise<void>;
+}
+/** Session-scoped public key/value facade. */
+export interface SessionMemory {
+    /** Reads a JSON value by key. Returns `undefined` when absent. */
+    read<T = JsonValue>(key: string): Promise<T | undefined>;
+    /** Writes a JSON-serializable value by key. */
+    write(key: string, value: JsonValue, opts?: MemoryWriteOptions): Promise<void>;
+    /** Deletes a key if it exists. */
+    delete(key: string): Promise<void>;
+    /** Lists keys in this scope. */
+    list(opts?: MemoryListOptions): Promise<string[]>;
+    /** Searches memory, or throws `ModelCapabilityError` when the adapter does not support `memory.search`. */
+    search(query: MemorySearchQuery): Promise<MemorySearchResult[]>;
+}
+/**
+ * Scoped memory helper exposed to workflows, agents, and TypeScript tools.
+ *
+ * @example
+ * ```ts
+ * await ctx.memory.session.write('last_topic', { value: 'pricing' })
+ * const prior = await ctx.memory.user().read<{ value: string }>('preference')
+ * ```
+ */
+export interface MemoryFacade {
+    /** Session-scoped memory for the current conversation thread. */
+    session: SessionMemory;
+    /** Run-scoped memory for the current agent or workflow run. */
+    run: SessionMemory;
+    /** Agent-scoped memory, present in agent and tool contexts. */
+    agent?: SessionMemory;
+    /** User-scoped memory using the explicit id or `metadata.userId`. */
+    user(userId?: string): SessionMemory;
+    /** Tenant-scoped memory using the explicit id or `metadata.tenantId`. */
+    tenant(tenantId?: string): SessionMemory;
+    /** Creates a memory handle for an explicit scope. */
+    scope(scope: MemoryScope): SessionMemory;
+}
+/** Internal options for creating a scoped memory facade. */
+export interface CreateMemoryFacadeOptions {
+    adapter: MemoryAdapter;
+    logger: Logger;
+    telemetry: TelemetryShim;
+    contentCaptureMode: ContentCaptureMode;
+    signal: AbortSignal;
+    sandbox?: SandboxSession;
+    harnessName: string;
+    sessionId: string;
+    runId?: string;
+    agentId?: string;
+    workflowId?: string;
+    metadata?: Readonly<Record<string, JsonValue>>;
+}

package/dist/ports/memory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/memory/validation.d.ts

@@ -0,0 +1,19 @@
+import type { JsonValue } from '../../models/json.js';
+import type { MemoryAdapter, MemoryCapability, MemoryListOptions, MemoryOperation, MemoryScope, MemoryScopeKind, MemorySearchQuery, MemoryWriteOptions } from './types.js';
+export declare const MEMORY_KEY_PATTERN: RegExp;
+export declare const scopeCapability: Record<MemoryScopeKind, MemoryCapability>;
+/** Validates static adapter metadata before the adapter is used. */
+export declare function validateMemoryAdapter(adapter: MemoryAdapter): void;
+export declare function validateOperationInput(adapter: MemoryAdapter, scope: MemoryScope, operation: MemoryOperation, key: string | undefined, content: {
+    value?: JsonValue;
+    writeOpts?: MemoryWriteOptions;
+    listOpts?: MemoryListOptions;
+    query?: MemorySearchQuery;
+} | undefined): void;
+export declare function validateWriteOptions(adapter: MemoryAdapter, opts: MemoryWriteOptions | undefined): void;
+export declare function normalizeListOptions(opts: MemoryListOptions | undefined): MemoryListOptions;
+export declare function normalizeSearchQuery(query: MemorySearchQuery | undefined): MemorySearchQuery;
+export declare function validateJsonSerializable(value: unknown, where: 'memory_value' | 'memory_write_options' | 'memory_search_query'): void;
+export declare function validateMemoryKey(key: string): void;
+export declare function assertScope(adapter: MemoryAdapter, scope: MemoryScope): void;
+export declare function assertCapability(adapter: MemoryAdapter, capability: MemoryCapability, method: string): void;

package/dist/ports/memory/validation.js

@@ -0,0 +1,160 @@
+import { HarnessConfigError, ModelCapabilityError, ValidationError } from '../../errors/index.js';
+export const MEMORY_KEY_PATTERN = /^[A-Za-z0-9_.\-:]{1,256}$/;
+const MEMORY_TAG_PATTERN = /^[A-Za-z0-9_.\-:]{1,64}$/;
+const MEMORY_ADAPTER_ID_PATTERN = /^[a-z][a-z0-9_.-]{1,63}$/;
+const MAX_LIMIT = 1000;
+const DEFAULT_LIMIT = 100;
+export const scopeCapability = {
+    run: 'memory.run',
+    session: 'memory.session',
+    agent: 'memory.agent',
+    user: 'memory.user',
+    tenant: 'memory.tenant'
+};
+/** Validates static adapter metadata before the adapter is used. */
+export function validateMemoryAdapter(adapter) {
+    if (!MEMORY_ADAPTER_ID_PATTERN.test(adapter.info.id)) {
+        throw new HarnessConfigError('Invalid memory adapter id.', { reason: 'invalid_memory_adapter', path: 'memory.info.id', id: adapter.info.id });
+    }
+    if (!adapter.info.packageName) {
+        throw new HarnessConfigError('Invalid memory adapter package name.', { reason: 'invalid_memory_adapter', path: 'memory.info.packageName', id: adapter.info.id });
+    }
+    if (!adapter.info.capabilities.includes('memory.kv')) {
+        throw new HarnessConfigError('Memory adapter must support memory.kv.', { reason: 'invalid_memory_adapter', path: 'memory.info.capabilities', id: adapter.info.id });
+    }
+    if (adapter.capabilities.length !== adapter.info.capabilities.length || adapter.capabilities.some((capability) => !adapter.info.capabilities.includes(capability))) {
+        throw new HarnessConfigError('Memory adapter capabilities must match info.capabilities.', { reason: 'invalid_memory_adapter', path: 'memory.capabilities', id: adapter.info.id });
+    }
+}
+export function validateOperationInput(adapter, scope, operation, key, content) {
+    assertScope(adapter, scope);
+    if (key !== undefined)
+        validateMemoryKey(key);
+    if (operation === 'set') {
+        validateJsonSerializable(content?.value, 'memory_value');
+        validateWriteOptions(adapter, content?.writeOpts);
+    }
+    if (operation === 'list')
+        normalizeListOptions(content?.listOpts);
+    if (operation === 'search') {
+        assertCapability(adapter, 'memory.search', 'search');
+        normalizeSearchQuery(content?.query);
+    }
+}
+export function validateWriteOptions(adapter, opts) {
+    if (!opts)
+        return;
+    if (opts.ttlMs !== undefined) {
+        if (!Number.isInteger(opts.ttlMs) || opts.ttlMs <= 0) {
+            throw new ValidationError('Memory ttlMs must be a positive integer.', { where: 'memory_write_options', issues: { ttlMs: opts.ttlMs } });
+        }
+        if (!adapter.info.capabilities.includes('memory.ttl')) {
+            throw new ValidationError('Memory adapter does not support ttlMs.', { where: 'memory_write_options', issues: { reason: 'ttl_unsupported' } });
+        }
+    }
+    for (const tag of opts.tags ?? []) {
+        if (!MEMORY_TAG_PATTERN.test(tag)) {
+            throw new ValidationError('Invalid memory tag.', { where: 'memory_write_options', issues: { tag } });
+        }
+    }
+    if (opts.metadata !== undefined)
+        validateJsonSerializable(opts.metadata, 'memory_write_options');
+}
+export function normalizeListOptions(opts) {
+    const limit = opts?.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIMIT) {
+        throw new ValidationError('Invalid memory list limit.', { where: 'memory_list_options', issues: { limit } });
+    }
+    return { ...opts, limit };
+}
+export function normalizeSearchQuery(query) {
+    const text = query?.text?.trim() ?? '';
+    const limit = query?.limit ?? DEFAULT_LIMIT;
+    if (text.length === 0 || text.length > 8000) {
+        throw new ValidationError('Invalid memory search text.', { where: 'memory_search_query', issues: { textLength: text.length } });
+    }
+    if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIMIT) {
+        throw new ValidationError('Invalid memory search limit.', { where: 'memory_search_query', issues: { limit } });
+    }
+    for (const tag of query?.tags ?? []) {
+        if (!MEMORY_TAG_PATTERN.test(tag)) {
+            throw new ValidationError('Invalid memory search tag.', { where: 'memory_search_query', issues: { tag } });
+        }
+    }
+    if (query?.metadata !== undefined)
+        validateJsonSerializable(query.metadata, 'memory_search_query');
+    return { ...query, text, limit };
+}
+export function validateJsonSerializable(value, where) {
+    const seen = new WeakSet();
+    const invalid = findInvalidJsonValue(value, seen);
+    if (invalid) {
+        throw new ValidationError('Memory value must be JSON-serializable.', { where, issues: invalid });
+    }
+    try {
+        JSON.stringify(value);
+    }
+    catch (error) {
+        throw new ValidationError('Memory value must be JSON-serializable.', { where, issues: {} }, error);
+    }
+}
+function findInvalidJsonValue(value, seen, path = '$') {
+    if (value === undefined)
+        return { path, reason: 'undefined' };
+    const valueType = typeof value;
+    if (valueType === 'function' || valueType === 'symbol' || valueType === 'bigint') {
+        return { path, reason: valueType };
+    }
+    if (value === null || valueType !== 'object')
+        return undefined;
+    if (seen.has(value))
+        return { path, reason: 'circular' };
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const invalid = findInvalidJsonValue(value[index], seen, `${path}[${index}]`);
+            if (invalid)
+                return invalid;
+        }
+        seen.delete(value);
+        return undefined;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        const invalid = findInvalidJsonValue(item, seen, `${path}.${key}`);
+        if (invalid)
+            return invalid;
+    }
+    seen.delete(value);
+    return undefined;
+}
+export function validateMemoryKey(key) {
+    if (!MEMORY_KEY_PATTERN.test(key)) {
+        throw new ValidationError('Invalid session memory key.', { where: 'memory_key', issues: { key } });
+    }
+}
+export function assertScope(adapter, scope) {
+    const capability = scopeCapability[scope.kind];
+    assertCapability(adapter, capability, scope.kind);
+    const missing = scope.kind === 'session' && !scope.sessionId
+        ? 'sessionId'
+        : scope.kind === 'run' && !scope.runId
+            ? 'runId'
+            : scope.kind === 'agent' && !scope.agentId
+                ? 'agentId'
+                : scope.kind === 'user' && !scope.userId
+                    ? 'userId'
+                    : scope.kind === 'tenant' && !scope.tenantId
+                        ? 'tenantId'
+                        : undefined;
+    if (missing) {
+        throw new ValidationError('Missing memory scope identifier.', { where: 'memory_scope', issues: { reason: 'missing_scope_identifier', field: missing, scope: scope.kind } });
+    }
+}
+export function assertCapability(adapter, capability, method) {
+    if (adapter.info.capabilities.includes(capability))
+        return;
+    if (capability === 'memory.search') {
+        throw new ModelCapabilityError('Memory search is not available for this adapter.', { alias: adapter.info.id, method: 'memory.search', reason: 'missing_capability' });
+    }
+    throw new ValidationError('Memory adapter does not support the requested scope or option.', { where: 'memory_scope', issues: { reason: 'scope_unsupported', capability, method } });
+}

package/dist/ports/memory.d.ts

@@ -0,0 +1,3 @@
+export * from './memory/types.js';
+export { validateMemoryAdapter } from './memory/validation.js';
+export { createMemoryFacade, createSessionMemory } from './memory/facade.js';

package/dist/ports/memory.js

@@ -0,0 +1,3 @@
+export * from './memory/types.js';
+export { validateMemoryAdapter } from './memory/validation.js';
+export { createMemoryFacade, createSessionMemory } from './memory/facade.js';