@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/context/operation-supervision-evidence.d.ts

@@ -0,0 +1,37 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import { type RoleCallFrame, type RoleCallLedgerHead, type RoleCapabilityExecution, type RoleOperationSupervisionNotice } from "../orchestration/role-calls/index.js";
+import { type CapabilityAdapterResult } from "../orchestration/capability-adapters/result.js";
+import { type AcceptedCapabilityAction } from "./accepted-capability-action.js";
+export declare const OPERATION_SUPERVISION_EVIDENCE_MESSAGE_KIND: "runtime_operation_supervision_evidence_v1";
+export type OperationSupervisionEvidenceReceipt = Readonly<{
+    executionId: string;
+    callId: string;
+    invocationAttempt: number;
+    capabilityId: string;
+    declaredEffect: RoleCapabilityExecution["declaredEffect"];
+    outcome: Exclude<RoleCapabilityExecution["outcome"], null>;
+    observedEffect: Exclude<RoleCapabilityExecution["observedEffect"], null>;
+    summary: string;
+    referenceData?: string;
+    references?: RoleCapabilityExecution["references"];
+}>;
+export type OperationSupervisionEvidenceAcceptedAction = AcceptedCapabilityAction;
+export type OperationSupervisionEvidenceEntry = Readonly<{
+    originExecutionId: string;
+    notice: RoleOperationSupervisionNotice;
+    evidence: Readonly<{
+        kind: "existing_exact_capability_result_lane";
+        executionId: string;
+    }> | Readonly<{
+        kind: "embedded_cross_call_exact_result";
+        acceptedAction: OperationSupervisionEvidenceAcceptedAction;
+        receipt: OperationSupervisionEvidenceReceipt;
+        adapterResult: CapabilityAdapterResult;
+    }>;
+}>;
+/**
+ * Resolves exact canonical evidence only for supervision notices created for
+ * this activation. The capsule is derived on demand and never changes result
+ * ownership or request-wide result projection.
+ */
+export declare function buildImmediateOperationSupervisionEvidenceMessage(head: RoleCallLedgerHead, call: RoleCallFrame): ChatMessage | undefined;

package/dist/src/runtime/context/operation-supervision-evidence.js

@@ -0,0 +1,90 @@
+import { projectImmediateRoleOperationSupervisionNotices, } from "../orchestration/role-calls/index.js";
+import { normalizeCapabilityAdapterResult, } from "../orchestration/capability-adapters/result.js";
+import { projectAcceptedCapabilityAction, } from "./accepted-capability-action.js";
+export const OPERATION_SUPERVISION_EVIDENCE_MESSAGE_KIND = "runtime_operation_supervision_evidence_v1";
+/**
+ * Resolves exact canonical evidence only for supervision notices created for
+ * this activation. The capsule is derived on demand and never changes result
+ * ownership or request-wide result projection.
+ */
+export function buildImmediateOperationSupervisionEvidenceMessage(head, call) {
+    const notices = projectImmediateRoleOperationSupervisionNotices(head, call);
+    if (notices.length === 0)
+        return undefined;
+    const entries = notices.map((notice) => projectLinkedEvidenceEntry(head, call, notice));
+    return Object.freeze({
+        role: "user",
+        content: JSON.stringify({
+            kind: OPERATION_SUPERVISION_EVIDENCE_MESSAGE_KIND,
+            authority: "canonical_role_call_ledger",
+            purpose: "supply_exact_immediate_operation_supervision_evidence",
+            applicability: "bound_activation_decision_or_its_immediate_presentation_handoff",
+            presenceEffect: "passive_evidence_not_user_intent_action_authority_or_new_execution",
+            sourceRevision: head.revision,
+            binding: {
+                callId: call.callId,
+                invocationAttempt: call.activationCount,
+                consumers: ["activation_decision", "immediate_presentation_handoff"],
+            },
+            coverage: "complete_for_immediate_operation_supervision_notices",
+            entries,
+        }),
+    });
+}
+function projectLinkedEvidenceEntry(head, call, notice) {
+    const execution = head.state.capabilityExecutions.find(({ executionId }) => executionId === notice.originExecutionId);
+    if (!isLinkedSettledExecution(execution, notice)) {
+        throw new Error("operation_supervision_evidence_origin_invalid");
+    }
+    const exactResult = normalizeCapabilityAdapterResult(execution.exactResult);
+    if (!exactResult.ok) {
+        throw new Error("operation_supervision_evidence_result_invalid");
+    }
+    const entry = {
+        originExecutionId: notice.originExecutionId,
+        notice,
+    };
+    if (execution.callId === call.callId) {
+        return Object.freeze({
+            ...entry,
+            evidence: Object.freeze({
+                kind: "existing_exact_capability_result_lane",
+                executionId: execution.executionId,
+            }),
+        });
+    }
+    return Object.freeze({
+        ...entry,
+        evidence: Object.freeze({
+            kind: "embedded_cross_call_exact_result",
+            acceptedAction: projectAcceptedCapabilityAction(head, execution),
+            receipt: Object.freeze({
+                executionId: execution.executionId,
+                callId: execution.callId,
+                invocationAttempt: execution.invocationAttempt,
+                capabilityId: execution.capabilityId,
+                declaredEffect: execution.declaredEffect,
+                outcome: execution.outcome,
+                observedEffect: execution.observedEffect,
+                summary: execution.summary,
+                ...(execution.referenceData
+                    ? { referenceData: execution.referenceData }
+                    : {}),
+                ...(execution.references
+                    ? { references: Object.freeze([...execution.references]) }
+                    : {}),
+            }),
+            adapterResult: exactResult.value,
+        }),
+    });
+}
+function isLinkedSettledExecution(execution, notice) {
+    return (execution !== undefined &&
+        execution.status === "settled" &&
+        execution.executionId === notice.originExecutionId &&
+        execution.actionFingerprint === notice.actionFingerprint &&
+        execution.outcome === notice.priorOutcome &&
+        execution.outcomeFingerprint === notice.outcomeFingerprint &&
+        execution.observedEffect !== null &&
+        execution.summary !== null);
+}

package/dist/src/runtime/context/request-tool-results.d.ts

@@ -3,6 +3,7 @@ import type { ModelStep } from "../../shared/model-steps.js";
 import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCapabilityDeclaredEffect, type RoleCapabilityExecutionOutcome, type RoleCapabilityObservedEffect, type RoleCapabilityResultReference } from "../orchestration/role-calls/index.js";
 import { type CapabilityAdapterResult } from "../orchestration/capability-adapters/result.js";
 import { type SemanticCompactionCheckpoint } from "./semantic-compaction/index.js";
+import { type AcceptedCapabilityAction } from "./accepted-capability-action.js";
 export declare const REQUEST_TOOL_RESULTS_MESSAGE_KIND: "runtime_request_tool_results_v1";
 export type RequestToolResult = Readonly<{
     executionId: string;
@@ -15,6 +16,8 @@ export type RequestToolResult = Readonly<{
     summary: string;
     referenceData?: string;
     references?: readonly RoleCapabilityResultReference[];
+    /** Exact accepted action, projected only to the call that produced it. */
+    acceptedAction?: AcceptedCapabilityAction;
     /** Exact canonical evidence, projected only to the call that produced it. */
     adapterResult?: CapabilityAdapterResult;
     summaryProjection?: "superseded_target_evidence";

package/dist/src/runtime/context/request-tool-results.js

@@ -2,6 +2,7 @@ import { isRoleCapabilityId, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAP
 import { traceDebug } from "../observability/debug-logger.js";
 import { normalizeCapabilityAdapterResult, } from "../orchestration/capability-adapters/result.js";
 import { createSemanticCompactionSha256Fingerprint, } from "./semantic-compaction/index.js";
+import { projectAcceptedCapabilityAction, } from "./accepted-capability-action.js";
 export const REQUEST_TOOL_RESULTS_MESSAGE_KIND = "runtime_request_tool_results_v1";
 const REQUEST_TOOL_RESULTS_LOG_SCOPE = "runtime.request_tool_results";
 /**
@@ -59,11 +60,16 @@ export function projectRequestToolResults(params) {
                 ...(execution.references
                     ? { references: Object.freeze([...execution.references]) }
                     : {}),
+                ...(execution.actionFingerprint
+                    ? {
+                        acceptedAction: projectAcceptedCapabilityAction(params.head, execution),
+                    }
+                    : {}),
                 adapterResult: exactResult.value,
             });
             sourceProjected.push(sourceResult);
             if (execution.callId !== params.callId) {
-                const { referenceData: _referenceData, adapterResult: _adapterResult, ...summaryOnlyResult } = sourceResult;
+                const { referenceData: _referenceData, adapterResult: _adapterResult, acceptedAction: _acceptedAction, ...summaryOnlyResult } = sourceResult;
                 projected.push(Object.freeze(summaryOnlyResult));
             }
             else {
@@ -271,10 +277,13 @@ export function projectCurrentRequestToolResults(results) {
     return projected;
 }
 function equivalentObservationKey(result, targets) {
+    const acceptedAction = result.acceptedAction;
     return JSON.stringify([
         result.capabilityId,
         [...targets].sort(),
-        result.summary,
+        ...(acceptedAction
+            ? [acceptedAction.controls, acceptedAction.workingDirectory]
+            : [result.summary]),
     ]);
 }
 function isDeclaredEffect(value) {

package/dist/src/runtime/default-adapters.d.ts

@@ -1,6 +1,7 @@
 import { type RuntimeAttachmentStore } from "./attachments/store.js";
 import type { ConversationContextProvider, EventSink, EventSinkFactory, ModelGatewayClient, RuntimeConfig, RuntimeHost, SessionStore, SkillProvider, ToolRegistry, WorkspaceProvider } from "./ports.js";
 import type { RuntimeEnvironmentServices, RuntimeRequestHandler } from "./composition.js";
+import { type LongTermMemoryService } from "./long-term-memory/index.js";
 export declare function createDefaultRuntimeHost(config?: RuntimeConfig, defaults?: DefaultRuntimeHostBindings): RuntimeHost;
 export type DefaultRuntimeHostBindings = Readonly<{
     runtimeId?: string;
@@ -11,6 +12,7 @@ export type DefaultRuntimeHostBindings = Readonly<{
     sessionStore?: SessionStore;
     attachmentStore?: RuntimeAttachmentStore;
     toolRegistry?: ToolRegistry;
+    longTermMemoryService?: LongTermMemoryService;
     services?: RuntimeEnvironmentServices;
     requestHandler?: RuntimeRequestHandler;
     requestHandlerFactory?: (services: RuntimeEnvironmentServices) => RuntimeRequestHandler;
@@ -25,5 +27,6 @@ export declare function createDefaultSkillProvider(config?: RuntimeConfig, optio
 }): SkillProvider;
 export declare function createDefaultWorkspaceProvider(config?: RuntimeConfig): WorkspaceProvider;
 export declare function createDefaultModelGatewayClient(config?: RuntimeConfig): ModelGatewayClient;
+export declare function createDefaultLongTermMemoryService(config: RuntimeConfig | undefined, models: ModelGatewayClient): LongTermMemoryService;
 export declare function createDefaultEventSinkFactory(config?: RuntimeConfig): EventSinkFactory;
 export declare function createNoopEventSink(): EventSink;

package/dist/src/runtime/default-adapters.js

@@ -1,6 +1,8 @@
+import { join } from "node:path";
 import { startAgentBridge } from "../bridge/start-agent-bridge.js";
 import { buildContextBuckets, buildContextWindow } from "../sessions/index.js";
-import { createModelGatewayClient, invokeModelGateway, invokeRawModelGateway, } from "../model-gateway/client.js";
+import { createModelGatewayClient, embedModelGateway, invokeModelGateway, invokeRawModelGateway, } from "../model-gateway/client.js";
+import { MAX_MODEL_GATEWAY_EMBEDDING_BATCH_SIZE } from "../model-gateway/embeddings/constants.js";
 import { createBundledPluginSkillProvider, createConfiguredSkillProvider, } from "./adapters/configured-skill-provider.js";
 import { createFileSessionStore } from "./adapters/file-session-store.js";
 import { createFileAttachmentStore, } from "./attachments/store.js";
@@ -11,6 +13,9 @@ import { createConfiguredToolRegistry } from "./capabilities/configured-tool-reg
 import { loadBundledRuntimePlugins, loadConfiguredRuntimePlugins, runtimePluginsToToolModules, } from "./plugins/loader.js";
 import { handleRunRequest } from "./request/handler.js";
 import { createModelSessionMemoryCompactor } from "./context/session-memory/index.js";
+import { createFileLongTermMemoryRepository } from "./adapters/long-term-memory/file-repository.js";
+import { createInMemoryLongTermMemoryRepository } from "./adapters/long-term-memory/in-memory-repository.js";
+import { createLongTermMemoryService, } from "./long-term-memory/index.js";
 export function createDefaultRuntimeHost(config, defaults = {}) {
     return {
         start(options = {}) {
@@ -90,13 +95,19 @@ function resolveRuntimeHostEnvironmentServices(params) {
         (mayUseLegacyDefaults ? params.defaults.eventSinkFactory : undefined) ??
         createDefaultEventSinkFactory(runtimeConfig);
     const sessionMemoryCompactor = bound?.sessionMemoryCompactor ?? createModelSessionMemoryCompactor();
-    if (mayReuseBound &&
+    const mayReuseBoundLongTermMemory = mayReuseBound && models === bound?.models;
+    const longTermMemory = params.options.longTermMemoryService ??
+        (mayReuseBoundLongTermMemory ? bound?.longTermMemory : undefined) ??
+        createDefaultLongTermMemoryService(runtimeConfig, models);
+    const reusesAllBoundServices = mayReuseBound &&
         sessions === bound.sessions &&
         attachments === bound.attachments &&
         tools === bound.tools &&
         models === bound.models &&
         events === bound.events &&
-        sessionMemoryCompactor === bound.sessionMemoryCompactor) {
+        sessionMemoryCompactor === bound.sessionMemoryCompactor &&
+        longTermMemory === bound.longTermMemory;
+    if (reusesAllBoundServices) {
         return bound;
     }
     return Object.freeze({
@@ -107,6 +118,7 @@ function resolveRuntimeHostEnvironmentServices(params) {
         models,
         events,
         sessionMemoryCompactor,
+        longTermMemory,
     });
 }
 function resolveRuntimeHostRequestHandler(services, defaults) {
@@ -124,6 +136,7 @@ export function createBoundRuntimeRequestHandler(services) {
         attachmentStore: services.attachments,
         toolRegistry: services.tools,
         sessionMemoryCompactor: services.sessionMemoryCompactor,
+        longTermMemory: services.longTermMemory,
     };
     return Object.freeze({
         handle(ws, message, requestOptions = {}) {
@@ -171,6 +184,7 @@ export function createDefaultModelGatewayClient(config) {
         return {
             invoke: invokeModelGateway,
             invokeRaw: invokeRawModelGateway,
+            embed: embedModelGateway,
         };
     }
     return createModelGatewayClient({
@@ -179,6 +193,53 @@ export function createDefaultModelGatewayClient(config) {
         ...(config.models ? { modelPolicy: config.models } : {}),
     });
 }
+export function createDefaultLongTermMemoryService(config, models) {
+    const memoryConfig = config?.longTermMemory ?? {
+        enabled: false,
+        emitClientEvents: false,
+    };
+    const repository = config
+        ? createFileLongTermMemoryRepository(join(config.paths.runtimeDir, "long-term-memory"))
+        : createInMemoryLongTermMemoryRepository();
+    const embeddings = memoryConfig.enabled && config
+        ? createLongTermMemoryEmbeddingClient({ config, models })
+        : undefined;
+    return createLongTermMemoryService({
+        repository,
+        enabled: memoryConfig.enabled,
+        emitClientEvents: memoryConfig.emitClientEvents,
+        ...(embeddings ? { embeddings } : {}),
+    });
+}
+function createLongTermMemoryEmbeddingClient(params) {
+    const profileId = params.config.longTermMemory?.embeddingProfileId;
+    if (!profileId) {
+        throw new Error("long_term_memory_embedding_profile_required");
+    }
+    if (!params.models.embed) {
+        throw new Error("long_term_memory_embedding_gateway_unavailable");
+    }
+    const embed = params.models.embed;
+    return Object.freeze({
+        maxBatchSize: MAX_MODEL_GATEWAY_EMBEDDING_BATCH_SIZE,
+        async embed(input) {
+            const result = await embed({
+                profileId,
+                texts: input.texts,
+                modelPolicy: params.config.models,
+                abortSignal: input.abortSignal,
+                ...(input.debugRequestId
+                    ? { debugRequestId: input.debugRequestId }
+                    : {}),
+            });
+            return Object.freeze({
+                modelFingerprint: result.modelFingerprint,
+                dimensions: result.dimensions,
+                vectors: result.vectors,
+            });
+        },
+    });
+}
 export function createDefaultEventSinkFactory(config) {
     if (config) {
         configureDebugLogger({

package/dist/src/runtime/index.d.ts

@@ -9,4 +9,5 @@ export * from "./adapters/in-memory-session-store.js";
 export * from "./adapters/multi-workspace-provider.js";
 export * from "./adapters/source-workspace-provider.js";
 export * from "./attachments/store.js";
+export * from "./long-term-memory/index.js";
 export * from "./observability/debug-logger.js";

package/dist/src/runtime/index.js

@@ -9,4 +9,5 @@ export * from "./adapters/in-memory-session-store.js";
 export * from "./adapters/multi-workspace-provider.js";
 export * from "./adapters/source-workspace-provider.js";
 export * from "./attachments/store.js";
+export * from "./long-term-memory/index.js";
 export * from "./observability/debug-logger.js";

package/dist/src/runtime/lifecycle/request-finalizer.d.ts

@@ -4,6 +4,7 @@ import type { EventSink } from "../ports.js";
 import { RequestLifecycle } from "../orchestration/lifecycle/request-lifecycle.js";
 import type { RequestObservation, RequestOutputTextMode } from "../request/result.js";
 import type { RequestSessionStore } from "../request/session-store.js";
+import type { LongTermMemoryService, MemoryCandidate } from "../long-term-memory/contracts.js";
 type RequestFinalizationResult = {
     status: "completed";
     output: string;
@@ -26,5 +27,7 @@ export declare function finalizeRequest(params: {
     agentMode: AgentMode;
     thinkingTrace?: SessionThinkingTraceEntry[];
     finalObservation?: RequestObservation;
+    memoryCandidates?: readonly MemoryCandidate[];
+    longTermMemory?: LongTermMemoryService;
 }): Promise<RequestFinalizationResult>;
 export {};

package/dist/src/runtime/lifecycle/request-finalizer.js

@@ -1,4 +1,5 @@
 import { finalizeResponse } from "../orchestration/final-response/finalization.js";
+import { scheduleFinalResponseMemory } from "../long-term-memory/finalization.js";
 export function failRequest(params) {
     params.events.event("thinking.completed");
     params.events.failed(params.error, params.details);
@@ -37,6 +38,13 @@ export async function finalizeRequest(params) {
                 observationContent: params.finalObservation.observationContent,
             }
             : {}),
+        afterPersist: () => scheduleFinalResponseMemory({
+            service: params.longTermMemory,
+            candidates: params.memoryCandidates,
+            requestId: params.requestId,
+            sessionId: params.sessionId,
+            onEvent: params.events.event.bind(params.events),
+        }),
     });
     return { status: "completed", output };
 }

package/dist/src/runtime/long-term-memory/background-save-queue.d.ts

@@ -0,0 +1,17 @@
+import type { LongTermMemoryRequestContext, MemoryCandidate, MemoryCandidateProcessingResult } from "./contracts.js";
+export type BackgroundMemorySave = Readonly<{
+    candidates: readonly MemoryCandidate[];
+    requestId: string;
+    sessionId: string;
+}>;
+export type LongTermMemorySaveQueue = Readonly<{
+    enqueue(save: BackgroundMemorySave): void;
+    drain(): Promise<void>;
+}>;
+export declare function createLongTermMemorySaveQueue(params: {
+    process(input: Readonly<{
+        candidates: readonly MemoryCandidate[];
+        context: LongTermMemoryRequestContext;
+    }>): Promise<MemoryCandidateProcessingResult>;
+    timeoutMs?: number;
+}): LongTermMemorySaveQueue;

package/dist/src/runtime/long-term-memory/background-save-queue.js

@@ -0,0 +1,66 @@
+import { classifyMemoryFailure } from "./diagnostics.js";
+import { traceDebug } from "../observability/debug-logger.js";
+const DEFAULT_BACKGROUND_SAVE_TIMEOUT_MS = 60_000;
+export function createLongTermMemorySaveQueue(params) {
+    const timeoutMs = resolveTimeout(params.timeoutMs);
+    let pending = Promise.resolve();
+    return Object.freeze({
+        enqueue(save) {
+            const detached = detachSave(save);
+            pending = pending.then(() => runSave(params.process, detached, timeoutMs));
+        },
+        drain: () => pending,
+    });
+}
+async function runSave(process, save, timeoutMs) {
+    const controller = new AbortController();
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            const error = new Error("long_term_memory_background_save_timeout");
+            controller.abort(error);
+            reject(error);
+        }, timeoutMs);
+    });
+    try {
+        await Promise.race([
+            process({
+                candidates: save.candidates,
+                context: {
+                    requestId: save.requestId,
+                    sessionId: save.sessionId,
+                    abortSignal: controller.signal,
+                },
+            }),
+            deadline,
+        ]);
+    }
+    catch (error) {
+        traceDebug("runtime.long_term_memory", "save.background_failed", {
+            requestId: save.requestId,
+            reason: classifyMemoryFailure(error),
+            candidateCount: save.candidates.length,
+        });
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function detachSave(save) {
+    return Object.freeze({
+        candidates: Object.freeze(save.candidates.map((candidate) => Object.freeze({
+            content: candidate.content,
+            tags: Object.freeze([...candidate.tags]),
+        }))),
+        requestId: save.requestId,
+        sessionId: save.sessionId,
+    });
+}
+function resolveTimeout(configured) {
+    if (configured !== undefined &&
+        (!Number.isSafeInteger(configured) || configured <= 0)) {
+        throw new TypeError("long_term_memory_background_save_timeout_invalid");
+    }
+    return configured ?? DEFAULT_BACKGROUND_SAVE_TIMEOUT_MS;
+}

package/dist/src/runtime/long-term-memory/candidate-persistence.d.ts

@@ -0,0 +1,16 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, LongTermMemoryRequestContext, MemoryCandidate } from "./contracts.js";
+type EmbeddingBatch = Awaited<ReturnType<LongTermMemoryEmbeddingClient["embed"]>>;
+export type MemoryCandidatePersistenceResult = Readonly<{
+    acceptedCount: number;
+    duplicateCount: number;
+}>;
+export declare function persistMemoryCandidates(params: {
+    repository: LongTermMemoryRepository;
+    preparedCandidates: readonly MemoryCandidate[];
+    freshCandidates: readonly MemoryCandidate[];
+    embedded?: EmbeddingBatch;
+    context: LongTermMemoryRequestContext;
+    now?: () => Date;
+    createId?: () => string;
+}): Promise<MemoryCandidatePersistenceResult>;
+export {};

package/dist/src/runtime/long-term-memory/candidate-persistence.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { mergeMemoryTags, normalizeMemoryIdentifier, normalizeMemoryText, } from "./policies/normalization.js";
+import { reconcileMemoryCandidate } from "./policies/reconciliation.js";
+export async function persistMemoryCandidates(params) {
+    const vectorByContent = buildVectorMap(params.freshCandidates, params.embedded);
+    const now = (params.now ?? (() => new Date()))().toISOString();
+    const createId = params.createId ?? randomUUID;
+    let result;
+    await params.repository.update((current) => {
+        params.context.abortSignal.throwIfAborted();
+        const records = [...current.records];
+        const vectors = [...current.vectors];
+        let acceptedCount = 0;
+        let duplicateCount = 0;
+        for (const candidate of params.preparedCandidates) {
+            const existingIndex = findRecordIndex(records, candidate);
+            if (existingIndex >= 0) {
+                duplicateCount += 1;
+                records[existingIndex] = mergeDuplicateRecord(records[existingIndex], candidate, now);
+                continue;
+            }
+            const vector = vectorByContent.get(normalizeMemoryText(candidate.content));
+            if (!vector || !params.embedded) {
+                throw new Error("long_term_memory_candidate_embedding_missing");
+            }
+            const id = createAvailableMemoryId(createId, records, vectors);
+            const record = createMemoryRecord({
+                candidate,
+                context: params.context,
+                now,
+                id,
+            });
+            reconcileMemoryCandidate({
+                candidate,
+                vector,
+                existingVectors: compatibleVectors(vectors, params.embedded),
+            });
+            records.push(record);
+            acceptedCount += 1;
+            vectors.push(Object.freeze({
+                memoryId: record.id,
+                modelFingerprint: params.embedded.modelFingerprint,
+                dimensions: params.embedded.dimensions,
+                vector,
+            }));
+        }
+        result = Object.freeze({ acceptedCount, duplicateCount });
+        return { records: Object.freeze(records), vectors: Object.freeze(vectors) };
+    });
+    if (!result) {
+        throw new Error("long_term_memory_candidate_persistence_outcome_missing");
+    }
+    return result;
+}
+function createAvailableMemoryId(createId, records, vectors) {
+    const id = normalizeMemoryIdentifier(createId());
+    if (!id) {
+        throw new Error("long_term_memory_candidate_id_invalid");
+    }
+    const idInUse = records.some((record) => record.id === id) ||
+        vectors.some((entry) => entry.memoryId === id);
+    if (idInUse) {
+        throw new Error("long_term_memory_candidate_id_conflict");
+    }
+    return id;
+}
+function buildVectorMap(candidates, embedded) {
+    const validCount = embedded?.vectors.length === candidates.length;
+    if (!validCount && candidates.length > 0) {
+        throw new Error("long_term_memory_embedding_vector_count_invalid");
+    }
+    if (!embedded) {
+        return new Map();
+    }
+    return new Map(candidates.map((candidate, index) => [
+        normalizeMemoryText(candidate.content),
+        embedded.vectors[index],
+    ]));
+}
+function findRecordIndex(records, candidate) {
+    const candidateKey = normalizeMemoryText(candidate.content);
+    return records.findIndex((record) => normalizeMemoryText(record.content) === candidateKey);
+}
+function compatibleVectors(vectors, embedded) {
+    return vectors
+        .filter((entry) => entry.modelFingerprint === embedded.modelFingerprint &&
+        entry.dimensions === embedded.dimensions)
+        .map((entry) => ({ memoryId: entry.memoryId, vector: entry.vector }));
+}
+function mergeDuplicateRecord(record, candidate, updatedAt) {
+    const tags = mergeMemoryTags(record.tags, candidate.tags);
+    return tags.length === record.tags.length
+        ? record
+        : Object.freeze({ ...record, tags, updatedAt });
+}
+function createMemoryRecord(params) {
+    return Object.freeze({
+        id: params.id,
+        content: params.candidate.content,
+        tags: params.candidate.tags,
+        provenance: Object.freeze({
+            kind: "passive_response",
+            sourceSessionId: params.context.sessionId,
+            sourceRequestId: params.context.requestId,
+        }),
+        createdAt: params.now,
+        updatedAt: params.now,
+    });
+}

package/dist/src/runtime/long-term-memory/candidate-preparation.d.ts

@@ -0,0 +1,8 @@
+import type { LongTermMemoryRecord, MemoryCandidate } from "./contracts.js";
+export type PreparedMemoryCandidates = Readonly<{
+    candidates: readonly MemoryCandidate[];
+    rejectedCount: number;
+    duplicateCount: number;
+}>;
+export declare function prepareMemoryCandidates(candidates: readonly MemoryCandidate[]): PreparedMemoryCandidates;
+export declare function indexMemoryRecordsByContent(records: readonly LongTermMemoryRecord[]): ReadonlyMap<string, LongTermMemoryRecord>;

package/dist/src/runtime/long-term-memory/candidate-preparation.js

@@ -0,0 +1,36 @@
+import { mergeMemoryTags, normalizeMemoryCandidate, normalizeMemoryText, } from "./policies/normalization.js";
+import { containsSensitiveMemoryCandidateData } from "./policies/sensitive-data.js";
+export function prepareMemoryCandidates(candidates) {
+    const byContent = new Map();
+    let rejectedCount = 0;
+    let duplicateCount = 0;
+    for (const rawCandidate of candidates) {
+        const candidate = normalizeMemoryCandidate(rawCandidate);
+        if (shouldRejectCandidate(candidate)) {
+            rejectedCount += 1;
+            continue;
+        }
+        const key = normalizeMemoryText(candidate.content);
+        const duplicate = byContent.get(key);
+        if (!duplicate) {
+            byContent.set(key, candidate);
+            continue;
+        }
+        duplicateCount += 1;
+        byContent.set(key, Object.freeze({
+            content: duplicate.content,
+            tags: mergeMemoryTags(duplicate.tags, candidate.tags),
+        }));
+    }
+    return Object.freeze({
+        candidates: Object.freeze([...byContent.values()]),
+        rejectedCount,
+        duplicateCount,
+    });
+}
+export function indexMemoryRecordsByContent(records) {
+    return new Map(records.map((record) => [normalizeMemoryText(record.content), record]));
+}
+function shouldRejectCandidate(candidate) {
+    return !candidate || containsSensitiveMemoryCandidateData(candidate);
+}

package/dist/src/runtime/long-term-memory/candidate-processing.d.ts

@@ -0,0 +1,9 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository, LongTermMemoryRequestContext, MemoryCandidate, MemoryCandidateProcessingResult } from "./contracts.js";
+export declare function processMemoryCandidates(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    candidates: readonly MemoryCandidate[];
+    context: LongTermMemoryRequestContext;
+    now?: () => Date;
+    createId?: () => string;
+}): Promise<MemoryCandidateProcessingResult>;