@ai-agent-forge/plugin-memory 0.85.0

package/dist/capability.js

@@ -0,0 +1,2565 @@
+/**
+ * First-party builtin memory capability (统一修复轮 A, 方案系统设计 §6.1 + §11,
+ * 方案实施计划 §11 A 路) — the model-facing write/recall/list/forget surface
+ * over the M5 Memory Foundation.
+ *
+ * Every operation is suite-scoped by construction: the suiteId comes from the
+ * session's suite binding entry (SUITE_SESSION_ENTRY_TYPE, written by the sdk
+ * at session creation) and is NEVER a tool parameter, so the model cannot
+ * widen or switch its memory domain (防越权). Sessions without a binding fall
+ * back to the "legacy" domain with a diagnostic. Writes go through the
+ * scheduler facade (observation → candidate → committed) plus a durable JSONL
+ * ledger append (src/memory/ledger.ts, the store's persistent replica); recall
+ * runs through the memory-recall-agent with the suiteId passthrough filter and
+ * the egress gate; forget goes through the canonical purge gate
+ * (user-immediate) and journal, physically rewriting the ledger (forget 后真
+ * 物理删除).
+ *
+ * Domain resolution is LAZY, per tool call (统一修复轮 B1 复审修复): the sdk
+ * appends the suite binding entry only after `new AgentSession` returns (the
+ * constructor's synchronous runtime build already runs this factory), so a
+ * factory-time resolution always saw an empty branch and every new session
+ * fell back to the legacy domain. Instead, each tool handler resolves the
+ * domain at call time — the binding entry is on the branch by then (creation
+ * appends it; resumed sessions carry it in their history) — and the per-domain
+ * ledger is created, loaded, and replayed into the store on the first call in
+ * that domain (Map<domain, ledger> cache, no memoization of the domain
+ * itself). The store stays one per-capability-instance singleton across
+ * domains: the atom `suiteId` field carries the read boundary; the ledger is
+ * only the per-domain durable replica.
+ *
+ * Concurrency envelope (统一修复轮 H1, #7 深度修复; WP-F 关洞修复): ledger
+ * appends AND the forget path's full-file rewrite serialize competing
+ * processes through the ledger's `.lock` sibling file (exclusive create +
+ * poll, 5 s timeout, stale-lock stealing — src/memory/ledger.ts), and both
+ * write paths run open → write → fsync → close, so a hard crash cannot lose
+ * a write that returned to its caller. A lock timeout or IO/fsync failure
+ * throws out of the tool handler, so the model sees the error instead of a
+ * silently lost write. Remaining boundaries: the lock is atomic only on
+ * local filesystems; a rewrite publishes the calling process's in-memory
+ * view without merging rows another process appended after its last load
+ * (the forget caller owns that reconciliation); fsync does not cover
+ * directory entries, so a crash before rewrite's rename leaves the previous
+ * file intact; an append whose fsync failed stays unacknowledged though it
+ * may already be readable — the loader's duplicate tolerance covers an
+ * unacknowledged retry.
+ *
+ * Global mode gate (2.4d6 S1, 记忆系统语义化重设计 §3): `memory.mode` is
+ * `"off"` (default) | `"light"` | `"full"`; off means the whole memory family
+ * is NOT registered (resolveBuiltinCapabilities skips the plugin; the factory
+ * itself returns zero registrations for direct callers). light/full run an
+ * enabling state machine (local checks → model load/download → smoke →
+ * ready; failure → failed with a four-option action list and the effective
+ * mode falls back to off for this instance).
+ *
+ * Semantic recall (2.4d6 S2, 设计 §4): memory_recall has exactly one
+ * retrieval path — embed → KNN depth50 + FTS depth50 → RRF k=60 top20 →
+ * cross-encoder rerank → store lookup (owner/suite/scope/expiry). The legacy
+ * tag-wordform bridge (query-token → tag-facet anchors, recency fallback
+ * page) is retired as a retrieval semantic; tags still ride the FTS body and
+ * the memory_list management face. Degradation ladder (never thrown at the
+ * model): rerank failure → RRF order; vector failure → FTS-only with
+ * recency ordering; FTS/index failure → KNN-only; both channels down →
+ * recency enumeration over the domain; total failure → degraded packet.
+ * `memoryIdEquals`-style primary-key lookup survives as the exact-id fast
+ * path (reference semantics, not retrieval).
+ *
+ * Semantic write merge (2.4d6 S3, 设计 §5 + 实施计划 S3 标定定版): in mode
+ * "full" every memory_write probes the projection BEFORE the canonical commit
+ * (embed + same-owner KNN top-5) because atoms are immutable — the outcome's
+ * relations must ride the atom's one commit. Merge condition (calibrated on
+ * bge-m3): cos ≥ 0.72, or 0.55 ≤ cos < 0.72 with a case-insensitive tag
+ * overlap. A merge commits the NEW atom with a one-way `supersedes` relation
+ * to the neighbor (the old entry keeps its memoryId and stays addressable via
+ * primary-key lookup) while the projection upserts the new row and removes the
+ * superseded one; startup reconciliation never re-adds superseded rows.
+ * 0.55 ≤ cos < 0.72 without a tag overlap is the conflict band: both entries
+ * stay, and the new atom carries one-way `conflict` relations. Below that (or
+ * no neighbor): a plain new entry. bge-small-zh similarity distributions
+ * overlap (标定: 余弦不可用作去重信号) → light mode never probes and stays
+ * byte-identical to the pre-S3 behavior. Recall filters superseded entries
+ * after the store lookup (only while their successor is among the candidates,
+ * so forgetting the successor revives the old entry). The Foundation
+ * (owner, observationId) idempotency is untouched: replays never consume a
+ * probe outcome.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { statfs } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { EXPERIMENTAL_PUBLIC_API_VERSION, MEMORY_RECALL_TOOL_NAME, } from "@agent-forge/plugin-sdk";
+import { Type } from "typebox";
+import { purgeZeroByteCacheArtifacts } from "./memory/model-cache-hygiene.js";
+// 记忆公共契约的权威定义处已是 plugin-sdk（D-075 S4-4 第一批迁入）；此处 re-export
+// 维持宿主历史导出面（宿主第二批收口后由宿主 re-export SDK）。
+export { MEMORY_RECALL_TOOL_NAME, } from "@agent-forge/plugin-sdk";
+import { loadAssistantPreferenceCard } from "./memory/assistant-card.js";
+import { createMemoryCandidateMachine } from "./memory/candidates.js";
+import { createMemoryEgressPolicy } from "./memory/egress-policy.js";
+import { buildMemoryAtomV1, } from "./memory/foundation.js";
+import { createDurableMemoryLedger } from "./memory/ledger.js";
+import { createMemoryLifecycleManager } from "./memory/lifecycle.js";
+import { createMemoryNetwork, createRelationDiffusionAdapter, } from "./memory/memory-network.js";
+import { createPreferenceDisambiguator } from "./memory/preference-disambiguator.js";
+import { promotePreferenceToUserDefault } from "./memory/preference-promotion.js";
+import { createPreferenceResolver, } from "./memory/preference-resolver.js";
+import { createMemoryPurgeGate, createMemoryReplicaRegistry } from "./memory/purge.js";
+import { createMemoryPurgeJournal } from "./memory/purge-journal.js";
+import { createMemoryRecallAgent } from "./memory/recall-agent.js";
+import { createMemoryRecallIndex } from "./memory/recall-index.js";
+import { createMemoryScheduler } from "./memory/scheduler.js";
+import { createMemorySchedulerApi } from "./memory/scheduler-api.js";
+import { createFirstPartyRetentionRegistry, createMemoryStore } from "./memory/store.js";
+import { forgetDomainMemory, listDomainMemories, suiteMemoryDomainName, } from "./memory/suite-memory.js";
+import { MEMORY_CONTRACT_VERSION_V2 } from "./memory/transfer.js";
+// ---------------------------------------------------------------------------
+// Host lifecycle catalog references (D-075 S4-4 第一批迁包改写): the embedded
+// capability imported the event definitions from the host's lifecycle catalog
+// and re-defined them idempotently. The plugin now subscribes through the
+// plain `{id, version}` reference form (observability.ts 同构先例): the host's
+// bootstrap lifecycle plugin owns the definitions, and a host that has not
+// defined the event rejects the registration structurally (plugin-load
+// failure under D-028, never a session failure). The data shapes below are
+// structural narrowings of the catalog payloads — only the fields the bash
+// error-lesson capture reads.
+// ---------------------------------------------------------------------------
+/** `tool.execution.start@1` (host lifecycle catalog). */
+const TOOL_EXECUTION_START_EVENT_ID = "tool.execution.start";
+const TOOL_EXECUTION_START_EVENT_VERSION = 1;
+/** `tool.result@1` (host lifecycle catalog). */
+const TOOL_RESULT_EVENT_ID = "tool.result";
+const TOOL_RESULT_EVENT_VERSION = 1;
+export const capabilityManifest = {
+    id: "agent-forge.builtin.memory",
+    version: "0.1.0",
+    apiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,
+    requiredCapabilities: ["session", "events", "tools"],
+    provides: [{ id: "memory.scheduler", version: 1, kind: "service" }],
+};
+/**
+ * Marker text of the auto-recall injection message (B1 记忆自动注入, D-071 增补
+ * 裁决自 sdk 迁入; pinned by test/memory-sdk-e2e.test.ts).
+ */
+export const MEMORY_AUTO_RECALL_MARKER = "<auto_recalled_memory>";
+/**
+ * Upper bound on facts pulled into one auto-recall injection (B1 记忆自动注入).
+ * The injection rides every request of the turn, so it stays a compact hint —
+ * deep recall is what memory_recall is for.
+ */
+const MEMORY_AUTO_RECALL_LIMIT = 3;
+/**
+ * Auto-recall rerank floor (错误教训与召回质量护栏设计 §2.1): reranked
+ * candidates scoring below it are dropped from the auto-recall injection
+ * (`score < minScore`). bge-reranker outputs uncalibrated logits that are only
+ * order-preserving (见 embedding-reranker.ts 头注), so 0 ("positive logit =
+ * relevant direction") is the conservative initial gate — tunable with real
+ * model eval evidence (只改常量 + eval 证据).
+ */
+const MEMORY_AUTO_RECALL_MIN_RERANK_SCORE = 0;
+/**
+ * Tail line of every auto-recall injection block (错误教训与召回质量护栏设计
+ * §2.1): tells the model the block was recalled rather than written by the
+ * user and may be outdated. Pinned verbatim by test/memory-error-lessons.test.ts.
+ */
+export const MEMORY_AUTO_RECALL_DISCLAIMER = "(Recalled automatically from persistent memory for this request — not written by the user. Recalled items may be outdated; verify against current state before relying on them.)";
+/**
+ * Upper bound on the error message embedded in one memory auto-recall log
+ * line: provider/store errors can carry arbitrary payload text, and the log
+ * channel is for locating the failure, not for echoing it.
+ */
+const MEMORY_AUTO_RECALL_ERROR_MESSAGE_LIMIT = 200;
+// ---------------------------------------------------------------------------
+// bash 失败教训自动沉淀 (错误教训与召回质量护栏设计 §2.2): 确定性事实模板,
+// 无模型解读; 风暴由签名去重 + 每实例上限兜住; 7 天保留档到期失去召回资格。
+// ---------------------------------------------------------------------------
+/** 每实例教训写入上限 (§2.2 风暴闸门): 首个超限事件 warn 一次, 之后静默跳过。 */
+const MEMORY_LESSON_MAX_PER_SESSION = 10;
+/** 教训 excerpt 字符上限 (错误文本尾部, 按码点切分不劈代理对)。 */
+const MEMORY_LESSON_ERROR_EXCERPT_MAX_CHARS = 300;
+/** toolCallId→command 配对映射容量 (仅 bash, FIFO)。 */
+const MEMORY_LESSON_TOOLCALL_MAP_CAPACITY = 32;
+/** 教训开关环境变量 (context 显式值 > env > 默认 on; 非法值取默认并 warn)。 */
+const MEMORY_LESSONS_ENV = "AGENT_FORGE_MEMORY_LESSONS";
+/** 教训 tags (§2.2): 随 FTS body 可检索。 */
+const MEMORY_LESSON_TAGS = ["auto-lesson", "bash"];
+/** 教训提交的保留档 (first-party retention registry 既有 "short" = 7 天)。 */
+const MEMORY_LESSON_RETENTION_MODE_ID = "short";
+/**
+ * bash 失败退出码的既有后缀 (core/tools/bash.ts: 输出文本 + 该状态行); 解析
+ * 不到 (timeout/abort 等) 记 unknown, 仍沉淀。
+ */
+const MEMORY_LESSON_EXIT_CODE_PATTERN = /Command exited with code (\d+)\s*$/;
+/**
+ * Memory tools guide（记忆 runtime 注入面，原 system-prompt.ts MEMORY_TOOL_GUIDE，
+ * D-071 迁移）：the model-facing hint that the persistent memory tools exist.
+ * It rides memory_recall's promptGuidelines so the text lives with the plugin
+ * that owns the tools (宪法 §3) and renders whenever the tool face is active.
+ */
+export const MEMORY_TOOLS_GUIDE = "Memory: You have persistent memory tools (memory_write, memory_recall, memory_list, memory_forget). Use memory_recall to look up user preferences or project facts before answering. Use memory_write to save important decisions, preferences, or findings for future sessions.";
+/**
+ * Session protocol key of the suite binding entry (方案设计 §10.1). The value
+ * mirrors the authoritative `SUITE_SESSION_ENTRY_TYPE` in
+ * src/profiles/suite-loader.ts — pinned by a deterministic test in
+ * test/capabilities-builtin.test.ts. Declared locally so the capability module
+ * graph stays free of the assembler's bundled-loader dependency chain.
+ */
+const SUITE_SESSION_ENTRY_TYPE = "suite";
+/**
+ * Owner (isolation principal) of every atom this capability writes. The
+ * Foundation owner is the store/facade isolation identity; this product ships
+ * one local user per agentDir, so one stable owner id partitions the ledger
+ * directory `<agentDir>/memory/<owner>/ledger-<suiteId|"legacy">.jsonl`.
+ */
+export const BUILTIN_MEMORY_OWNER = "local-user";
+/** Contract version written by this capability (@2 atoms carry suiteId). */
+const MEMORY_CONTRACT_VERSION = MEMORY_CONTRACT_VERSION_V2;
+const TAG_FACET_NAMESPACE = "builtin.memory";
+const EVENT_TYPE = "memory.changed";
+const MAX_TAGS = 8;
+const DEFAULT_RECALL_LIMIT = 5;
+const DEFAULT_LIST_LIMIT = 20;
+/** Bounded supplementary relation references per recall (记忆网络接线). */
+const MAX_RELATED_REFS = 20;
+// ---------------------------------------------------------------------------
+// 语义写入合并 (2.4d6 S3, 实施计划 S3 阈值标定定版)。full 档独有: light 档
+// (bge-small-zh) 重复变体/同主题/无关三组余弦分布完全重叠, 余弦不可用作去重
+// 信号 → 不探测不合并 (行为与 S3 之前逐字节一致); off 档整体不注册。
+// ---------------------------------------------------------------------------
+/** 合并下限 (bge-m3 实测: 重复变体 0.664–0.833, 同主题 ≤0.652 → 0.72 零误合并)。 */
+const SEMANTIC_MERGE_T_HIGH = 0.72;
+/** 冲突带下限 (bge-m3 实测: 无关语句最高 0.450 → 0.55 以下零越界)。 */
+const SEMANTIC_MERGE_T_LOW = 0.55;
+/** 写入探测的同 owner KNN 近邻数 (标定定版: top-5)。 */
+const SEMANTIC_MERGE_KNN_LIMIT = 5;
+/** supersedes/conflict 关系的 capability 命名空间 (与 tag facet 同域)。 */
+const SEMANTIC_RELATION_NAMESPACE = "builtin.memory";
+// ---------------------------------------------------------------------------
+// 语义召回管线 (2.4d6 S2, 记忆系统语义化重设计 §4) 与全局档位 (S1, §3)。
+// 召回唯一路径: embed → KNN+FTS → RRF → 精排 → store 回查; tag 词面 bridge
+// 已退役 (tags 仅入 FTS body 与管理面)。off 档 = 整个 capability 不注册。
+// ---------------------------------------------------------------------------
+/** memory_write 内容长度契约 (POC 报告 §7): reranker 512-token 上下文足够。 */
+const MEMORY_CONTENT_MAX_LENGTH = 700;
+/** FTS / KNN 通道各自取回深度 (定版管线: depth 50)。 */
+const HYBRID_CHANNEL_DEPTH = 50;
+/** RRF 常数, 与 vector-index 组件 queryFts 打分口径一致。 */
+const HYBRID_RRF_K = 60;
+/** 融合候选池上限 (定版管线: top20 → 精排 → top limit)。 */
+const HYBRID_FUSION_POOL = 20;
+/** 单次启动对账 embed+upsert 上限, 超出留待下次启动继续。 */
+const RECONCILE_MAX_UPSERTS = 2000;
+/** 开启前磁盘余量下限 (设计 §3.2 checking): light ≥ 500MB, full ≥ 2GB。 */
+const DISK_HEADROOM_MIN_BYTES = {
+    light: 500 * 1024 * 1024,
+    full: 2 * 1024 * 1024 * 1024,
+};
+/**
+ * 模型文件大小下限 (防截断/空文件的 sanity 下限, 非精确体积): 高档 embedding
+ * (bge-m3 q8) 数百 MB → 下限 256MB, 精排器 (bge-reranker-base q8) ~280MB →
+ * 下限 64MB, 低档 (bge-small-zh q8) ~24MB → 下限 8MB。真实校验由加载冒烟承担。
+ */
+const MODEL_MIN_WEIGHT_BYTES = {
+    light: 8 * 1024 * 1024,
+    full: 256 * 1024 * 1024,
+};
+const RERANKER_MIN_WEIGHT_BYTES = 64 * 1024 * 1024;
+/** 自定义镜像源环境变量 (失败行动清单第一项指向它)。 */
+const HF_MIRRORS_ENV = "AGENT_FORGE_HF_MIRRORS";
+/** enabling 加载/下载期间的周期性进度日志间隔。 */
+const ENABLING_PROGRESS_LOG_INTERVAL_MS = 15_000;
+const VECTOR_PRESET_LIGHT = {
+    embeddingModelId: "Xenova/bge-small-zh-v1.5",
+    dimensions: 512,
+    queryPrefix: "为这个句子生成表示以用于检索相关文章：",
+};
+const VECTOR_PRESET_FULL = {
+    embeddingModelId: "Xenova/bge-m3",
+    dimensions: 1024,
+    queryPrefix: "",
+};
+/** 两档共用精排模型 (POC 报告 §8: 官方 Xenova 转换版唯一实测可用)。 */
+const VECTOR_RERANKER_MODEL_ID = "Xenova/bge-reranker-base";
+const VECTOR_DB_DIRNAME = "vector";
+const VECTOR_MODEL_CACHE_DIRNAME = "model-cache";
+/** 镜像序列 (实施计划 §7): 直连 huggingface.co 超时时回落 hf-mirror.com。 */
+const VECTOR_REMOTE_HOSTS = ["https://huggingface.co", "https://hf-mirror.com"];
+const isMemoryModeV1 = (value) => value === "off" || value === "light" || value === "full";
+/**
+ * memory.mode 解析 (2.4d6 S1)。优先级: context 显式值 → 环境变量
+ * `AGENT_FORGE_MEMORY_MODE` → settings.json `memory.mode` (settingsMode 参, 持
+ * 久配置面) → 旧别名 `AGENT_FORGE_MEMORY_VECTOR` (兼容期) → 默认 off。env 是
+ * 临时覆盖、settings 是持久配置 (env > 文件, 沿用本仓 suite 解析先例)。任何
+ * 非法配置值 fail-closed 为 off 并在结果中携带原值供调用方告警一次, 绝不静默
+ * 改档或意外下载。
+ */
+export function resolveMemoryMode(explicitMode, env = process.env, settingsMode) {
+    if (explicitMode !== undefined) {
+        if (isMemoryModeV1(explicitMode))
+            return { mode: explicitMode };
+        return { mode: "off", invalidEnvValue: explicitMode };
+    }
+    const configured = env.AGENT_FORGE_MEMORY_MODE?.trim().toLowerCase();
+    if (configured !== undefined && configured !== "") {
+        if (isMemoryModeV1(configured))
+            return { mode: configured };
+        return { mode: "off", invalidEnvValue: configured };
+    }
+    // 持久配置面: settings.json memory.mode。设置但非法同样 fail-closed, 不再
+    // 回落旧别名 (与非法 env 的先例一致)。
+    const fromSettings = settingsMode?.trim().toLowerCase();
+    if (fromSettings !== undefined && fromSettings !== "") {
+        if (isMemoryModeV1(fromSettings))
+            return { mode: fromSettings };
+        return { mode: "off", invalidSettingsValue: fromSettings };
+    }
+    // 兼容期别名: AGENT_FORGE_MEMORY_VECTOR (混合检索工程化的旧开关), 语义并入
+    // AGENT_FORGE_MEMORY_MODE, 仅当新变量与 settings 均未定档时生效; 一个发布
+    // 周期后删除。
+    const legacy = env.AGENT_FORGE_MEMORY_VECTOR?.trim().toLowerCase();
+    if (legacy !== undefined && legacy !== "") {
+        if (isMemoryModeV1(legacy))
+            return { mode: legacy, legacyEnvUsed: true };
+        return { mode: "off", invalidEnvValue: legacy, legacyEnvUsed: true };
+    }
+    return { mode: "off" };
+}
+const isMemoryLessonsSettingV1 = (value) => value === "on" || value === "off";
+/**
+ * context.memory.lessons 解析 (§2.2, resolveMemoryMode 同构): 显式值 → 环境变量
+ * `AGENT_FORGE_MEMORY_LESSONS` → 默认 on。任何非法配置值回默认并在结果中携带
+ * 原值供调用方告警一次, 绝不静默改开关。
+ */
+export function resolveMemoryLessons(explicitLessons, env = process.env) {
+    if (explicitLessons !== undefined) {
+        if (isMemoryLessonsSettingV1(explicitLessons))
+            return { lessons: explicitLessons };
+        return { lessons: "on", invalidEnvValue: explicitLessons };
+    }
+    const configured = env[MEMORY_LESSONS_ENV]?.trim().toLowerCase();
+    if (configured !== undefined && configured !== "") {
+        if (isMemoryLessonsSettingV1(configured))
+            return { lessons: configured };
+        return { lessons: "on", invalidEnvValue: configured };
+    }
+    return { lessons: "on" };
+}
+const isVectorComponentsOverride = (override) => "embedProvider" in override && "vectorIndex" in override;
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 双约定工具输入读取（对齐 subagent-delegate 的 objectInput）：capability invoke
+ * 面单参约定下第一参即输入（第二参是宿主注入的 toolExecutionContext），legacy 5 参
+ * 约定（toolCallId 字符串打头）下输入在第二参。生产装配恒向 runtime invoke 面注入
+ * toolExecutionContext 作为 execute 第二参（公共契约），因此"第二参非 undefined 即
+ * 输入"的判定会把 context 误当输入（content/query 等读成 undefined）。改按形状判定：
+ * 第一参是普通对象即取第一参，否则看第二参；两者皆非对象时返回空记录，交由各工具
+ * 的字段断言报错。
+ */
+function memoryToolInput(first, second) {
+    const primary = isPlainRecord(first) ? first : second;
+    return isPlainRecord(primary) ? primary : {};
+}
+/** FNV-1a 32-bit — deterministic identity from the given value (code-memory 同构). */
+function identityHash(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Text of the branch's LAST user message — the auto-recall query and per-turn
+ * cache key (B1 记忆自动注入). Read from the persisted branch, not the
+ * request-time snapshot: request-time injections (the sdk's background
+ * delegation digest) ride the transformContext input as user-role blocks and
+ * would otherwise hijack the query, while the branch never sees them.
+ */
+function lastBranchUserText(api) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.type !== "message" || entry.message?.role !== "user")
+            continue;
+        const content = entry.message.content;
+        if (typeof content === "string")
+            return content;
+        if (!Array.isArray(content))
+            continue;
+        const parts = [];
+        for (const item of content) {
+            if (isPlainObject(item) && item.type === "text" && typeof item.text === "string")
+                parts.push(item.text);
+        }
+        return parts.join("\n");
+    }
+    return undefined;
+}
+/**
+ * Inserts the recall injection right after the last user message of the
+ * request snapshot (B1 记忆自动注入): the recalled context is turn-scoped, so
+ * it belongs at the head of the current turn, ahead of any assistant/
+ * toolResult round already in flight. Purely a request-time view — the
+ * persisted session history stays untouched.
+ */
+function injectAfterLastUserMessage(messages, injection) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index]?.role === "user") {
+            return [...messages.slice(0, index + 1), injection, ...messages.slice(index + 1)];
+        }
+    }
+    return messages;
+}
+/**
+ * Tail of `text` whose UTF-16 length never exceeds `limit`, cut on code-point
+ * boundaries so a surrogate pair never splits. The excerpt budget is measured
+ * in UTF-16 units (`String.length`, the same measure as the 700-char content
+ * contract), so counting code points here would let astral-plane tails double
+ * the rendered excerpt and break the cap.
+ */
+function tailWithinUtf16Budget(text, limit) {
+    if (limit <= 0)
+        return "";
+    if (text.length <= limit)
+        return text;
+    const codePoints = Array.from(text);
+    let units = 0;
+    let start = codePoints.length;
+    while (start > 0 && units + codePoints[start - 1].length <= limit) {
+        units += codePoints[start - 1].length;
+        start -= 1;
+    }
+    return codePoints.slice(start).join("");
+}
+/** bash 失败退出码解析 (core/tools/bash.ts 的既有后缀); 解析不到 (timeout/abort) = "unknown"。 */
+function lessonExitCodeOf(errorText) {
+    return MEMORY_LESSON_EXIT_CODE_PATTERN.exec(errorText)?.[1] ?? "unknown";
+}
+/** Concatenated text of a toolResult message's text blocks (images skipped). */
+function toolResultTextOf(content) {
+    const parts = [];
+    for (const block of content) {
+        if (block.type === "text")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+/**
+ * 教训内容 (§2.2 确定性事实模板, 无模型解读): `Command failed: \`<command>\`
+ * exited with code <N>. Output tail: <excerpt>`。excerpt 取错误文本尾部, 预算
+ * 按 UTF-16 单元计 ({@link MEMORY_LESSON_ERROR_EXCERPT_MAX_CHARS} 与 700 上限
+ * 同一口径); 超长只压缩 excerpt (excerpt 压到 0 仍超限的极端长命令再压 command
+ * 尾部, 保持模板可解析)。
+ */
+function buildLessonContent(command, exitCode, errorText) {
+    const render = (commandPart, excerpt) => `Command failed: \`${commandPart}\` exited with code ${exitCode}. Output tail: ${excerpt}`;
+    const excerptLimit = Math.min(MEMORY_LESSON_ERROR_EXCERPT_MAX_CHARS, MEMORY_CONTENT_MAX_LENGTH - render(command, "").length);
+    if (excerptLimit > 0)
+        return render(command, tailWithinUtf16Budget(errorText, excerptLimit));
+    const commandBudget = MEMORY_CONTENT_MAX_LENGTH - render("", "").length;
+    return render(command.slice(0, Math.max(0, commandBudget)), "");
+}
+/**
+ * Suite binding entry ids already warned about (统一修复轮终审 minor 3):
+ * resolveSessionDomain runs on EVERY memory tool call, so without this
+ * module-level set one malformed binding entry would repeat the warning on
+ * each call and flood the log.
+ */
+const malformedBindingWarned = new Set();
+/**
+ * Resolves the session's suite binding domain from the branch entries: the
+ * LAST suite entry wins (the sdk appends one at session creation). A binding
+ * with a malformed payload counts as unbound — the legacy fallback is
+ * fail-safe (its atoms are invisible to every real suite) and a diagnostic is
+ * logged when the logger capability is available. Called per tool call —
+ * never captured at factory time (统一修复轮 B1: the binding entry is appended
+ * after the session constructor ran this factory).
+ */
+function resolveSessionDomain(api) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== SUITE_SESSION_ENTRY_TYPE)
+            continue;
+        const data = entry.data;
+        const suiteId = isPlainObject(data) ? data.suiteId : undefined;
+        if (typeof suiteId === "string" && suiteId.trim() !== "") {
+            return { kind: "suite", suiteId };
+        }
+        if (!malformedBindingWarned.has(entry.id)) {
+            malformedBindingWarned.add(entry.id);
+            api.logger?.warn("suite binding entry has a malformed payload; falling back to the legacy memory domain", {
+                entryId: entry.id,
+            });
+        }
+        return { kind: "legacy" };
+    }
+    return { kind: "legacy" };
+}
+/** Recency-first payload projection: unwraps the `{ statement }` payload convention. */
+function statementOf(payload) {
+    if (isPlainObject(payload) && typeof payload.statement === "string")
+        return payload.statement;
+    return JSON.stringify(payload);
+}
+/** The egress gate re-derives statements as payload JSON; unwrap for the model face. */
+function unwrapEgressStatement(statement) {
+    try {
+        const parsed = JSON.parse(statement);
+        if (isPlainObject(parsed) && typeof parsed.statement === "string")
+            return parsed.statement;
+    }
+    catch {
+        // Not payload JSON — surface it verbatim.
+    }
+    return statement;
+}
+/**
+ * 三通道 RRF 融合 (定版管线): `score(id) += 1/(k + rank + 1)` 对各通道排名累加,
+ * 取 top {@link HYBRID_FUSION_POOL}。分数并列时以 memoryId 升序打破, 保证确定性。
+ */
+function rrfFuseRankings(rankings) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        for (const [rank, memoryId] of ranking.entries()) {
+            scores.set(memoryId, (scores.get(memoryId) ?? 0) + 1 / (HYBRID_RRF_K + rank + 1));
+        }
+    }
+    return [...scores.entries()]
+        .sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : 1))
+        .map(([memoryId]) => memoryId)
+        .slice(0, HYBRID_FUSION_POOL);
+}
+/** 嵌入向量已 L2 归一化 (provider 契约), 点积即余弦。 */
+function cosineSimilarity(left, right) {
+    let dot = 0;
+    for (const [axis, value] of left.entries())
+        dot += value * (right[axis] ?? 0);
+    return dot;
+}
+/** tags 重叠判定 (至少一个共同 tag, trim 后大小写不敏感)。 */
+function tagsOverlapIgnoreCase(left, right) {
+    if (left.length === 0 || right.length === 0)
+        return false;
+    const rightSet = new Set(right.map((tag) => tag.trim().toLowerCase()));
+    return left.some((tag) => rightSet.has(tag.trim().toLowerCase()));
+}
+/**
+ * 语义合并判定 (实施计划 S3 标定定版, 三分支):
+ * - 合并: cos ≥ 0.72, 或 0.55 ≤ cos < 0.72 且新 tags 与既有 tags 有重叠
+ *   (复合条件救回跨语言改写 — 余弦偏低但 tags 同源; 取首个满足条件的近邻);
+ * - 冲突带: 0.55 ≤ cos < 0.72 且无 tag 重叠 → 双存 + conflict 关系
+ *   (单向声明在新 atom 上; 正确性优先于存储省略, 宁可双存不错杀);
+ * - 低相似/无近邻: 普通新条目。
+ * 近邻按 KNN 序传入。
+ */
+function decideSemanticMergePlan(input) {
+    for (const neighbor of input.neighbors) {
+        const merged = neighbor.cosine >= SEMANTIC_MERGE_T_HIGH ||
+            (neighbor.cosine >= SEMANTIC_MERGE_T_LOW && tagsOverlapIgnoreCase(input.newTags, neighbor.tags));
+        if (merged)
+            return { kind: "merge", targetMemoryId: neighbor.memoryId };
+    }
+    const conflictMemoryIds = input.neighbors
+        .filter((neighbor) => neighbor.cosine >= SEMANTIC_MERGE_T_LOW)
+        .map((neighbor) => neighbor.memoryId);
+    return conflictMemoryIds.length > 0 ? { kind: "conflict", conflictMemoryIds } : { kind: "new" };
+}
+/**
+ * 判定结论 → 新 atom 的 relations (canonical 侧合并/冲突痕迹)。canonical
+ * atom 不可变且 Foundation 无"更新 payload"操作, 关系只在新 atom 上单向声明
+ * (可发现语义由此满足): supersedes 指向被合并的旧条目, conflict 指向冲突带
+ * 近邻。ids 由 (kind, target, content) 确定性派生。
+ */
+function semanticMergeRelations(plan, content) {
+    const relation = (kind, targetMemoryId) => {
+        const relationId = `rel-${identityHash(`${kind}\u0000${targetMemoryId}\u0000${content}`)}`;
+        return {
+            relationId,
+            namespace: SEMANTIC_RELATION_NAMESPACE,
+            schemaVersion: 1,
+            kind,
+            targetMemoryId,
+            relationRevision: `r-${identityHash(relationId)}`,
+        };
+    };
+    if (plan.kind === "merge")
+        return [relation("supersedes", plan.targetMemoryId)];
+    if (plan.kind === "conflict")
+        return plan.conflictMemoryIds.map((target) => relation("conflict", target));
+    return [];
+}
+/** 档位预设: mode → 模型组合。off 在进入装配前已被门控拦截。 */
+function vectorPresetForMode(mode) {
+    return mode === "light" ? VECTOR_PRESET_LIGHT : VECTOR_PRESET_FULL;
+}
+/**
+ * 自定义镜像源 (失败行动清单第一项): `AGENT_FORGE_HF_MIRRORS` 逗号分隔 host
+ * 列表, 排在默认镜像序列之前优先尝试。
+ */
+function remoteHostsForEnabling() {
+    const custom = process.env[HF_MIRRORS_ENV]
+        ?.split(",")
+        .map((host) => host.trim())
+        .filter((host) => host !== "");
+    return custom === undefined || custom.length === 0 ? VECTOR_REMOTE_HOSTS : [...custom, ...VECTOR_REMOTE_HOSTS];
+}
+/**
+ * 本地检查 1: native .node sidecar 可解析 (设计 §3.2 checking)。布局:
+ * onnxruntime-node/bin 下的 napi-vN/<platform>/<arch> 原生模块 — 缺失 = 安装
+ * 损坏。容错: 不钉死 napi 版本号, 逐目录扫描。
+ *
+ * 解析基点双通道: jiti（安装店加载缝）注入的 `require` 走宿主 alias 表
+ * （宿主 node_modules 副本, 店内无依赖树）; 纯 ESM（源码/工作区直载）下裸
+ * `require` 未定义（typeof 探测不抛 ReferenceError）, 回落原生 createRequire。
+ */
+function resolveOnnxRuntimeEntryPath() {
+    if (typeof require === "function") {
+        try {
+            return require.resolve("onnxruntime-node");
+        }
+        catch {
+            // jiti 解析失败（alias 未覆盖等）→ 继续走原生解析再报结构化错误。
+        }
+    }
+    return createRequire(import.meta.url).resolve("onnxruntime-node");
+}
+function nativeBinaryCheck(hostEntryPath) {
+    // 两种失败要区分 (D-075 安装店路径修复后前者成为真实可达路径):
+    // (a) 宿主未注入入口路径且插件位置自解析不到 — 不是安装损坏, 行动是宿主侧
+    //     安装重依赖后重启会话, 不是重装插件;
+    // (b) 路径存在但原生二进制缺失/损坏 — 保留损坏类文案。
+    let entryPath;
+    if (hostEntryPath === undefined) {
+        try {
+            entryPath = resolveOnnxRuntimeEntryPath();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return `onnxruntime-node is not provided by the host installation and could not be resolved from the plugin location (${detail}); to enable memory features, install onnxruntime-node in the host project (npm i onnxruntime-node) and restart the session`;
+        }
+    }
+    else {
+        entryPath = hostEntryPath;
+    }
+    try {
+        let packageDir = dirname(entryPath);
+        while (packageDir !== dirname(packageDir) && !existsSync(join(packageDir, "package.json"))) {
+            packageDir = dirname(packageDir);
+        }
+        const binDir = join(packageDir, "bin");
+        if (!existsSync(binDir))
+            return `onnxruntime native binary directory not found: ${binDir}`;
+        for (const napiEntry of readdirSync(binDir, { withFileTypes: true })) {
+            if (!napiEntry.isDirectory() || !napiEntry.name.startsWith("napi-v"))
+                continue;
+            const platformDir = join(binDir, napiEntry.name, process.platform, process.arch);
+            if (!existsSync(platformDir))
+                continue;
+            const binaries = readdirSync(platformDir).filter((file) => file.endsWith(".node"));
+            if (binaries.length > 0)
+                return undefined;
+        }
+        return `onnxruntime native binary for ${process.platform}/${process.arch} not found under ${binDir}`;
+    }
+    catch (error) {
+        return `onnxruntime native binary could not be resolved (${error instanceof Error ? error.message : String(error)}); the installation looks damaged — reinstall the package`;
+    }
+}
+/**
+ * 重依赖自解析默认实现 (missingHeavyDependencyModules 生产接线): 双通道与
+ * {@link resolveOnnxRuntimeEntryPath} 一致 — jiti（安装店加载缝）注入的
+ * `require` 走宿主 alias 表; 纯 ESM（源码/工作区直载）下回落原生 createRequire。
+ */
+function resolveHeavyDependencyEntryPath(specifier) {
+    if (typeof require === "function") {
+        try {
+            return require.resolve(specifier);
+        }
+        catch {
+            // jiti 解析失败（alias 未覆盖等）→ 继续走原生解析。
+        }
+    }
+    return createRequire(import.meta.url).resolve(specifier);
+}
+/**
+ * 本地检查 1b: 重依赖供给 (设计 §3.2 checking)。`@lancedb/lancedb` 与
+ * `@huggingface/transformers` 逐个判定 — entries 提供宿主入口路径 = 可用
+ * (不触自解析); 未提供时 resolveModule 自解析成功 = 可用, 抛错 = 计入缺失。
+ * 返回缺失 specifier 列表 (空 = 通过)。纯函数零 IO; 导出仅供测试 (与宿主侧
+ * buildHostDependencyAliases 同一模式), 生产接线传插件位置自解析 — 把加载步
+ * 的 "Cannot find module" 泛化包装前置成精准缺供文案, 省掉模型下载等前置工作。
+ */
+export function missingHeavyDependencyModules(entries, resolveModule) {
+    const missing = [];
+    const supplies = [
+        ["@lancedb/lancedb", entries.lancedb],
+        ["@huggingface/transformers", entries.transformers],
+    ];
+    for (const [specifier, entryPath] of supplies) {
+        if (entryPath !== undefined)
+            continue;
+        try {
+            resolveModule(specifier);
+        }
+        catch {
+            missing.push(specifier);
+        }
+    }
+    return missing;
+}
+/**
+ * transformers.js 缓存布局的容错存在性检查 (设计 §3.2 手动导入路径):
+ * `<cacheDir>/<modelId>/` 下需有非空 tokenizer 文件与 `onnx/` 权重文件。
+ * 返回 undefined = 检查通过; "missing" = 目录/文件缺失或仅剩 0 字节残骸
+ * (失败下载产物, 清理后进入下载阶段, 见 model-cache-hygiene); 其他字符串 =
+ * 文件存在但可疑 (截断/非空过小), 属失败。
+ */
+function modelFilesCheck(cacheDir, modelId, minWeightBytes) {
+    const modelDir = join(cacheDir, modelId);
+    if (!existsSync(modelDir))
+        return "missing";
+    // tokenizer 只剩 0 字节文件 = 失败下载残骸 (真 tokenizer.json 不可能为空):
+    // 清掉按缺失处理可重下; 非空文件不动 (手动导入布局不受影响)。
+    const tokenizerNames = ["tokenizer.json", "tokenizer.model"].filter((name) => existsSync(join(modelDir, name)));
+    const hasTokenizer = tokenizerNames.some((name) => statSync(join(modelDir, name)).size > 0);
+    if (!hasTokenizer) {
+        if (tokenizerNames.length > 0)
+            purgeZeroByteCacheArtifacts(modelDir);
+        return "missing";
+    }
+    const onnxDir = join(modelDir, "onnx");
+    if (!existsSync(onnxDir))
+        return `onnx weight directory missing under ${modelDir}`;
+    const weights = readdirSync(onnxDir).filter((name) => name.includes(".onnx"));
+    if (weights.length === 0)
+        return `no onnx weight file under ${onnxDir}`;
+    const largest = Math.max(...weights.map((name) => statSync(join(onnxDir, name)).size));
+    if (largest < minWeightBytes) {
+        return `largest onnx weight under ${onnxDir} is ${largest} bytes, below the expected minimum ${minWeightBytes} — the download looks truncated`;
+    }
+    return undefined;
+}
+/**
+ * 本地检查 3: 磁盘余量 (设计 §3.2 checking, node:fs statfs, 零新依赖)。
+ * 以 agentDir 所在卷为准 (cacheDir 同卷创建)。
+ */
+async function diskHeadroomCheck(agentDir, minimumBytes) {
+    let freeBytes;
+    try {
+        const stats = await statfs(agentDir);
+        freeBytes = stats.bfree * stats.bsize;
+    }
+    catch (error) {
+        return `disk free space could not be determined for ${agentDir} (${error instanceof Error ? error.message : String(error)})`;
+    }
+    if (freeBytes < minimumBytes) {
+        return `disk free space is ${freeBytes} bytes, below the required ${minimumBytes}`;
+    }
+    return undefined;
+}
+/** enabling 失败的五选一行动清单 (设计 §3.2 硬性要求)。 */
+function enablingActionList(modelCacheDir, currentMode) {
+    return [
+        `Switch to a reachable mirror: set ${HF_MIRRORS_ENV} to a comma-separated host list (tried before the defaults)`,
+        `Install the heavy dependencies in the host project (npm i onnxruntime-node @lancedb/lancedb @huggingface/transformers) so the host can supply them via hostDependencyPaths, then restart the session`,
+        `Download the models manually and place them under ${modelCacheDir} (layout: <modelId>/tokenizer.json + <modelId>/onnx/model*.onnx)`,
+        currentMode === "full"
+            ? 'Downgrade to memory.mode "light" (much smaller models)'
+            : 'Keep memory.mode "light" and retry with a reachable mirror',
+        'Give up: leave memory.mode "off" (the default) so the memory family stays unregistered',
+    ];
+}
+/**
+ * Parses the optional recall context (scenes/projects/tasks) into a preference
+ * resolution context. Returns undefined when absent so the no-context recall
+ * path stays byte-identical to the pre-disambiguation behavior.
+ */
+function parseRecallContext(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value))
+        throw new Error("context must be an object");
+    const stringArray = (field) => {
+        const entries = value[field];
+        if (entries === undefined)
+            return undefined;
+        if (!Array.isArray(entries))
+            throw new Error(`context.${field} must be an array of strings`);
+        for (const entry of entries) {
+            if (typeof entry !== "string")
+                throw new Error(`context.${field} entries must be strings`);
+        }
+        return entries;
+    };
+    const scenes = stringArray("scenes");
+    const projects = stringArray("projects");
+    const tasks = stringArray("tasks");
+    return {
+        ...(scenes === undefined ? {} : { scenes }),
+        ...(projects === undefined ? {} : { projects }),
+        ...(tasks === undefined ? {} : { tasks }),
+    };
+}
+/**
+ * Context-scoped preference post-processing over the recalled facts: preference
+ * atoms compete per (subject, key); the resolver drops out-of-scope preferences
+ * and deterministically ranks the rest, and an unconfirmed ranking goes through
+ * the scope-specificity disambiguator. Whatever remains unresolvable is
+ * returned as an explicit conflict block — the recall never silently picks
+ * between competing stored values. Non-preference facts pass through untouched.
+ */
+function applyPreferenceContext(input) {
+    const { facts, context, resolver, disambiguator, atomOf } = input;
+    const preferenceAtoms = [];
+    const atomsByGroup = new Map();
+    const preferenceMemoryIds = new Set();
+    for (const fact of facts) {
+        const atom = atomOf(fact.memoryId);
+        if (atom === undefined || atom.memoryKind !== "preference" || atom.preference === undefined)
+            continue;
+        preferenceMemoryIds.add(fact.memoryId);
+        preferenceAtoms.push(atom);
+        const groupKey = `${atom.preference.subject}\u0000${atom.preference.key}`;
+        const group = atomsByGroup.get(groupKey) ?? [];
+        group.push(atom);
+        atomsByGroup.set(groupKey, group);
+    }
+    if (preferenceMemoryIds.size === 0)
+        return { facts, conflicts: [] };
+    const keptMemoryIds = new Set();
+    const conflicts = [];
+    for (const decision of resolver.resolve(preferenceAtoms, context)) {
+        const groupAtoms = atomsByGroup.get(`${decision.subject}\u0000${decision.key}`) ?? [];
+        if (decision.status === "applied") {
+            if (decision.winnerMemoryId === undefined) {
+                throw new Error(`applied preference decision without a winnerMemoryId: ${JSON.stringify(decision)}`);
+            }
+            keptMemoryIds.add(decision.winnerMemoryId);
+            continue;
+        }
+        if (decision.status === "instruction_override") {
+            // No stored fact survives a current-instruction override (this slice has
+            // no input source for currentInstructions, so the branch stays inert).
+            continue;
+        }
+        if (decision.status === "conflict_unconfirmed") {
+            const outcome = disambiguator.disambiguate(groupAtoms.map((atom) => ({
+                memoryId: atom.memoryId,
+                preferredValue: atom.preference.preferredValue,
+                scope: atom.preference.scope,
+                evidenceClass: atom.preference.evidence.class,
+                applicabilityConfidence: atom.preference.applicabilityConfidence,
+            })), context);
+            if (outcome.status === "resolved") {
+                keptMemoryIds.add(outcome.winnerMemoryId);
+                continue;
+            }
+            conflicts.push({
+                subject: decision.subject,
+                key: decision.key,
+                candidates: groupAtoms.map((atom) => {
+                    const preference = atom.preference;
+                    return {
+                        memoryId: atom.memoryId,
+                        statement: unwrapEgressStatement(statementOf(atom.payload)),
+                        value: preference.preferredValue,
+                        evidenceClass: preference.evidence.class,
+                        confidence: preference.applicabilityConfidence,
+                    };
+                }),
+                explanation: [...outcome.explanation],
+            });
+            continue;
+        }
+        throw new Error(`unexpected preference decision status: ${JSON.stringify(decision)}`);
+    }
+    return {
+        facts: facts.filter((fact) => !preferenceMemoryIds.has(fact.memoryId) || keptMemoryIds.has(fact.memoryId)),
+        conflicts,
+    };
+}
+function tagFacetsOf(atom) {
+    return atom.facets
+        .filter((facet) => facet.namespace === TAG_FACET_NAMESPACE && facet.key === "tag")
+        .map((facet) => facet.value);
+}
+function entryToToolEntry(entry) {
+    return {
+        memoryId: entry.memoryId,
+        kind: entry.memoryKind,
+        statement: statementOf(entry.payload),
+        occurredAt: entry.occurredAt,
+        ...(entry.preference === undefined
+            ? {}
+            : {
+                preference: {
+                    subject: entry.preference.subject,
+                    key: entry.preference.key,
+                    scopeLevel: entry.preference.scopeLevel,
+                    crossSuiteVisible: entry.preference.crossSuiteVisible,
+                },
+            }),
+    };
+}
+const writeSchema = Type.Object({
+    content: Type.String({
+        description: "The memory content: one self-contained fact or preference statement",
+        maxLength: MEMORY_CONTENT_MAX_LENGTH,
+    }),
+    kind: Type.Union([Type.Literal("fact"), Type.Literal("preference")], {
+        description: "fact = a durable piece of information; preference = a user preference (requires subject)",
+    }),
+    subject: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("task"), Type.Literal("environment")], {
+        description: "Required when kind is preference: whose preference this is",
+    })),
+    tags: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+        description: "Optional short keywords; stored with the memory, full-text searchable and shown in memory_list; at most 8",
+        maxItems: MAX_TAGS,
+    })),
+});
+const recallSchema = Type.Object({
+    query: Type.String({
+        description: "Natural-language query; recall fuses semantic (vector) and full-text (BM25) matching and reranks the result. An exact memoryId retrieves that memory directly",
+    }),
+    limit: Type.Optional(Type.Integer({ description: "Maximum number of memories to return (1-100)", minimum: 1, maximum: 100 })),
+    context: Type.Optional(Type.Object({
+        scenes: Type.Optional(Type.Array(Type.String())),
+        projects: Type.Optional(Type.Array(Type.String())),
+        tasks: Type.Optional(Type.Array(Type.String())),
+    }, {
+        description: "Current scope context; when present, recalled preferences are resolved against it (out-of-scope preferences drop, competing values resolve by scope specificity or surface as explicit conflicts)",
+    })),
+});
+const listSchema = Type.Object({
+    limit: Type.Optional(Type.Integer({ description: "Maximum number of entries to list (1-100)", minimum: 1, maximum: 100 })),
+});
+const forgetSchema = Type.Object({
+    memoryId: Type.String({
+        description: "The memoryId of the memory to forget, as returned by memory_write or memory_list",
+    }),
+});
+/**
+ * Creates the builtin memory capability: four tools (memory_write,
+ * memory_recall, memory_list, memory_forget) over a per-session Foundation
+ * stack whose durable replica is the per-domain JSONL ledger under
+ * `<agentDir>/memory/<owner>/ledger-<domain>.jsonl`, resolved lazily at each
+ * tool call (统一修复轮 B1).
+ *
+ * `memory.mode` gates the whole family (2.4d6 S1): a resolved mode of "off"
+ * registers NOTHING (zero tools, zero commands, zero events) — the factory
+ * returns an empty registration list and logs the one-line disabled
+ * declaration. resolveBuiltinCapabilities intercepts earlier at the assembly
+ * level (设计 §3.2 "禁用 = 不注册").
+ *
+ * `override` is the test-only seam (deterministic mock AI 门禁): full vector
+ * components skip the real transformers/lancedb assembly entirely; enabling
+ * seams keep the real assembly but replace the transformers loader.
+ */
+export function createMemoryCapability(api, context, override) {
+    const harness = createMemoryCapabilityHarness(api, context, override);
+    return harness.registrations;
+}
+/**
+ * Test-only assembly variant: the capability with an injected override (full
+ * vector components skip real assembly; enabling seams redirect the model
+ * loader on the real path). Public tool names, schemas, and return shapes are
+ * identical to {@link createMemoryCapability}.
+ */
+export function createCapabilityWithVectorComponents(api, context, override) {
+    // Tool-face test stubs hand-write partial CapabilityAPIs that predate the
+    // D-071 auto-recall hook; default registerLoopHook to a no-op so those
+    // tests keep exercising just the tool face. Real CapabilityAPIs always
+    // carry the method (production path never hits this default) — the `in`
+    // check is runtime-only because the stubs bypass the declared type.
+    const apiWithHooks = "registerLoopHook" in api
+        ? api
+        : Object.assign(Object.create(null), api, {
+            registerLoopHook: () => ({
+                id: "test:noop-loop-hook",
+                kind: "loop-hook",
+                dispose() { },
+            }),
+        });
+    return createMemoryCapabilityHarness(apiWithHooks, context, override);
+}
+function createMemoryCapabilityHarness(api, context, override) {
+    assertNonEmptyString(context.agentDir, "MemoryCapabilityContext.agentDir");
+    const now = () => Date.now();
+    const sessionId = api.session?.getSessionId() ?? "no-session";
+    // 全局档位解析 (2.4d6 S1): context 显式 → env → settings.json → 默认 off。
+    // 非法 env/settings 值 fail-closed 回 off 并各告警一次; off = 家族整体不注册
+    // (零工具零命令零事件)。
+    const modeResolution = resolveMemoryMode(context.memory?.mode, undefined, context.memory?.settingsMode);
+    if (modeResolution.invalidEnvValue !== undefined) {
+        api.logger?.warn(`invalid AGENT_FORGE_MEMORY_MODE value "${modeResolution.invalidEnvValue}"; memory stays off (fail-closed)`);
+    }
+    if (modeResolution.invalidSettingsValue !== undefined) {
+        api.logger?.warn(`invalid memory.mode setting "${modeResolution.invalidSettingsValue}"; memory stays off (fail-closed)`);
+    }
+    if (modeResolution.mode === "off") {
+        api.logger?.info("memory disabled (mode=off)");
+        return {
+            registrations: [],
+            settleVectorWork: async () => { },
+            vectorState: () => "off",
+            enablingOutcome: async () => "ready",
+        };
+    }
+    const memoryMode = modeResolution.mode;
+    const vectorComponentsOverride = override ?? context.vectorComponents ?? context.storage?.vectorComponents;
+    const injectedComponents = vectorComponentsOverride !== undefined && isVectorComponentsOverride(vectorComponentsOverride)
+        ? vectorComponentsOverride
+        : undefined;
+    const enablingOverride = vectorComponentsOverride !== undefined && !isVectorComponentsOverride(vectorComponentsOverride)
+        ? vectorComponentsOverride
+        : undefined;
+    // Store: one per-capability-instance singleton. Atoms of every domain this
+    // session touches live here together — the atom `suiteId` field carries the
+    // read boundary (suite queries filter through it; the ledger is only the
+    // per-domain durable replica). The injected storeFactory (扩展位 A1) replaces
+    // the default store wholesale: the implementation owns retention semantics.
+    const retentionRegistry = createFirstPartyRetentionRegistry();
+    const store = context.storage?.storeFactory?.({
+        agentDir: context.agentDir,
+        owner: BUILTIN_MEMORY_OWNER,
+        now,
+    }) ?? createMemoryStore({ retentionRegistry, now });
+    // Durable replica per domain, created and loaded lazily on the first tool
+    // call in that domain (统一修复轮 B1 复审修复): the sdk appends the suite
+    // binding entry only after the session constructor ran this factory, so the
+    // domain (and with it the ledger to replay) is only known at call time.
+    // Write identity is deterministic: observationId `memory_write:<sessionId>:<n>`
+    // hashes into the memoryId. The counter is instance-local, so a resumed session
+    // re-derives its floor from the replayed ledger (resolveDomain): a persisted
+    // observationId of this session marks its sequence as taken — the store rejects
+    // a regenerated memoryId (canonical atoms are immutable), which would fail every
+    // replayed-sequence write after resume (write → dispose → resume → write).
+    const writeSequencePrefix = `memory_write:${sessionId}:`;
+    const writeSequenceOf = (observationId) => {
+        if (!observationId.startsWith(writeSequencePrefix))
+            return undefined;
+        const sequence = observationId.slice(writeSequencePrefix.length);
+        return /^\d+$/.test(sequence) ? Number(sequence) : undefined;
+    };
+    let writeSequence = 0;
+    const domainLedgers = new Map();
+    const resolveDomain = () => {
+        const domain = resolveSessionDomain(api);
+        const domainName = suiteMemoryDomainName(domain);
+        let ledger = domainLedgers.get(domainName);
+        if (ledger === undefined) {
+            ledger =
+                context.storage?.ledgerFactory?.({
+                    agentDir: context.agentDir,
+                    owner: BUILTIN_MEMORY_OWNER,
+                    domain: domainName,
+                    now,
+                }) ??
+                    createDurableMemoryLedger({
+                        path: join(context.agentDir, "memory", BUILTIN_MEMORY_OWNER, `ledger-${domainName}.jsonl`),
+                        now,
+                    });
+            if (domain.kind === "legacy") {
+                api.logger?.info("session has no suite binding; memory falls back to the legacy domain", {
+                    sessionId: api.session?.getSessionId() ?? "unknown",
+                });
+            }
+            // First load in this domain: replay the durable atoms into the store.
+            // Sequences persisted by earlier instances of this session raise the
+            // write-sequence floor before any new write can regenerate their ids.
+            const replay = ledger.load();
+            for (const atom of replay.atoms) {
+                const persistedSequence = writeSequenceOf(atom.observationId);
+                if (persistedSequence !== undefined && persistedSequence > writeSequence)
+                    writeSequence = persistedSequence;
+                try {
+                    store.commit(atom);
+                }
+                catch (error) {
+                    // A ledger atom the current store cannot accept (e.g. an unregistered
+                    // retention mode) must not fail the session — skip with a diagnostic.
+                    api.logger?.warn("memory ledger atom could not be replayed into the store", {
+                        memoryId: atom.memoryId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            if (replay.corruptedLines > 0 || replay.duplicateSkipped > 0 || replay.unreadable) {
+                api.logger?.warn("memory ledger loaded with diagnostics", {
+                    domain: domainName,
+                    corruptedLines: replay.corruptedLines,
+                    duplicateSkipped: replay.duplicateSkipped,
+                    unreadable: replay.unreadable,
+                });
+            }
+            domainLedgers.set(domainName, ledger);
+            // 启动对账: 首个域的 ledger 重放完成后一次性触发 (fire-and-forget,
+            // 不阻塞本工具调用; 失败只影响向量通道, 不影响锚点通道)。
+            vectorReconcileOnce();
+        }
+        return { domain, domainName, ledger };
+    };
+    const machine = createMemoryCandidateMachine({ store, now });
+    const lifecycle = createMemoryLifecycleManager({
+        policy: {
+            policyVersion: "lifecycle@1",
+            halfLifeMs: { session: 86_400_000, cycle: 604_800_000, "long-term": 2_592_000_000 },
+            staleAfterMs: { session: 172_800_000, cycle: 1_209_600_000, "long-term": 5_184_000_000 },
+            archiveAfterMs: { session: 604_800_000, cycle: 5_184_000_000, "long-term": 15_552_000_000 },
+            baselineAttention: 0.5,
+        },
+        now,
+    });
+    const scheduler = createMemoryScheduler({ now });
+    scheduler.acquireForInstance({ instanceId: sessionId, owner: BUILTIN_MEMORY_OWNER });
+    // 非工具召回路径设施 (2.4d6 S4 家族收口取证结论): 生产工具召回 (memory_recall
+    // 工具与 auto-recall 钩子, 后者直连同一 recallExecute, D-071 自 sdk 迁入)
+    // 只走 recallSemantically 语义管线; index → recallAgent →
+    // schedulerApi.recall 这条链在本 capability 内不再被工具面调用 (schedulerApi
+    // 的生产使用仅剩写入路径的 submitObservation/submitCandidate)。保留原因:
+    // MemorySchedulerApiV1 facade 契约 (recall + egress 门)、recall-agent 与
+    // recall-index 是公共 API (src/index.ts 导出) 和 memory-testkit 之上的测试
+    // 设施 (scheduler-api / memory-suite-scope / coverage-branch-memory-recall
+    // 等测试的直接消费者) — 有存续消费者, 非死代码。
+    const index = createMemoryRecallIndex({ store });
+    const recallAgent = createMemoryRecallAgent({
+        scheduler,
+        index,
+        policyDefaults: {
+            candidateBudget: 1000,
+            modelInspectionLimit: 20,
+            finalResultLimit: 20,
+            maxRelationHops: 2,
+            maxModelCalls: 3,
+            maxOutputTokens: 4000,
+            maxOutputBytes: 16_000,
+            maxRounds: 3,
+        },
+        hostLimits: {
+            candidateBudget: 5000,
+            modelInspectionLimit: 100,
+            finalResultLimit: 100,
+            maxRelationHops: 5,
+            maxModelCalls: 10,
+            maxOutputTokens: 100_000,
+            maxOutputBytes: 1_000_000,
+            maxRounds: 10,
+        },
+        now,
+    });
+    const replicaRegistry = createMemoryReplicaRegistry();
+    replicaRegistry.register({
+        replicaId: "memory-ledger",
+        kind: "canonical",
+        ownerScope: BUILTIN_MEMORY_OWNER,
+        contractVersion: MEMORY_CONTRACT_VERSION,
+        healthy: true,
+    });
+    // 向量投影副本 (混合检索工程化, D-035): 恒注册 — purge 批次以向量索引确认为
+    // 副本契约的一部分; 通道 off/disabled 时 index 分派为 no-op (索引不存在,
+    // 无行可清), 行为见 vectorPurgeMemories。
+    replicaRegistry.register({
+        replicaId: "memory-vector-index",
+        kind: "index",
+        contractVersion: MEMORY_CONTRACT_VERSION,
+        ownerScope: BUILTIN_MEMORY_OWNER,
+        healthy: true,
+    });
+    const purgeGate = createMemoryPurgeGate({ registry: replicaRegistry, now });
+    const purgeJournal = createMemoryPurgeJournal();
+    const egressPolicy = createMemoryEgressPolicy({
+        policyVersion: "egress@1",
+        allowedSourceKinds: ["tool", "entry"],
+        redactedPayloadFields: [],
+    });
+    // schedulerApi.recall 在生产工具面无调用点 (角色见上方"非工具召回路径设施"
+    // 注释); 本 capability 的生产使用仅 submitObservation/submitCandidate (写入)。
+    const schedulerApi = createMemorySchedulerApi({
+        recallAgent,
+        machine,
+        lifecycle,
+        purgeGate,
+        egressPolicy,
+        factInfoLookup: (memoryId) => {
+            const record = store.get(memoryId, { owner: BUILTIN_MEMORY_OWNER });
+            if (!record)
+                return undefined;
+            return {
+                sourceRefs: record.atom.sourceRefs,
+                payload: record.atom.payload,
+            };
+        },
+    });
+    // Preference resolution/disambiguation over context-scoped recalls (2.4c/2.4d2):
+    // stateless and deterministic — one instance per capability suffices.
+    const preferenceResolver = createPreferenceResolver();
+    const preferenceDisambiguator = createPreferenceDisambiguator();
+    // Relation diffusion over the recall seeds (记忆网络接线, 2.4d4): a factory-
+    // scoped deterministic network with one enabled one-hop adapter; disabled
+    // adapters yield an explicit `disabled` result instead of silent degradation.
+    const memoryNetwork = createMemoryNetwork({
+        adapters: [createRelationDiffusionAdapter({ maxHops: 1 })],
+    });
+    // ---- 语义召回通道 (2.4d6 S1/S2; 召回唯一检索路径) ----
+    // 状态机 (设计 §3.2): enabling = 检查/加载进行中 (惰性触发: 首次向量操作
+    // 时真正执行); ready = 可用; degraded = ready 后运行期故障 (可自愈回
+    // ready); failed = enabling 失败, 本实例内终态 (mode 回退 off, 记忆工具
+    // 返回携带行动清单的不可用 packet, 不再重试)。所有写侧操作经 vectorQueue
+    // 串行化, 避免 reconcile 与写入埋点在 LanceDB 建表上竞态; recall 等待
+    // enabling 单飞完成, 不与后台对账并发读索引。transformers/lancedb 的动态
+    // import 只出现在 vectorEnsure 的装配分支里 (type-position 引类型), 未
+    // 触发时不加载任何重依赖。
+    let vectorState = "enabling";
+    let vectorChannel;
+    let enablingFailure;
+    let enablingSettled;
+    const enablingSettledPromise = new Promise((resolve) => {
+        enablingSettled = () => resolve(enablingFailure ?? "ready");
+    });
+    if (injectedComponents !== undefined) {
+        // 测试注入: 直接 ready, 跳过真实装配与档位解析。
+        vectorState = "ready";
+        vectorChannel = {
+            embed: injectedComponents.embedProvider,
+            reranker: injectedComponents.reranker,
+            index: injectedComponents.vectorIndex,
+            queryPrefix: injectedComponents.queryPrefix ?? "",
+            embeddingModelId: injectedComponents.embedProvider.modelId,
+        };
+        enablingSettled?.();
+    }
+    const vectorEnabled = () => vectorState !== "failed";
+    let vectorInitPromise;
+    let vectorQueue = Promise.resolve();
+    /** 精排组件失败标记: reranker 加载/调用失败后本实例内跳过精排 (RRF 序)。 */
+    let vectorRerankerUnavailable = false;
+    /** 投影写/清失败的一次性降级告警标记 (重复失败由启动对账修复, 不刷屏)。 */
+    let vectorDegradedWarned = false;
+    const vectorEnqueue = (operation) => {
+        const next = vectorQueue.then(operation, operation);
+        // 队尾永不满仓 reject: 前序失败不阻断后续操作, 错误由操作自己消化。
+        vectorQueue = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    /**
+     * 开启状态机 (设计 §3.2, 惰性单飞): 本地检查 (native .node 可解析 → 重依赖
+     * 供给 (lancedb/transformers: 宿主入口路径或插件位置自解析) → 模型文件存在
+     * 与大小 → 磁盘余量) → transformers 加载 (自带下载, 进度周期性
+     * 落一行日志) → 冒烟 (embed 一条 + getStoredModelId 与档位比对) → ready。
+     * 任一步失败 → failed (原因 + 五选一行动清单), mode 记录回退 off, 本实例
+     * 不再重试。
+     */
+    const vectorEnsure = () => {
+        if (vectorState === "ready" || vectorState === "degraded")
+            return Promise.resolve(vectorChannel);
+        if (vectorState === "failed")
+            return Promise.resolve(undefined);
+        if (vectorInitPromise !== undefined)
+            return vectorInitPromise;
+        vectorInitPromise = (async () => {
+            const preset = vectorPresetForMode(memoryMode);
+            const modelCacheDir = join(context.agentDir, "memory", VECTOR_MODEL_CACHE_DIRNAME);
+            const failEnabling = (reason) => {
+                vectorState = "failed";
+                enablingFailure = { reason, actions: enablingActionList(modelCacheDir, memoryMode) };
+                vectorInitPromise = undefined;
+                api.logger?.warn(`memory enabling failed: ${reason} — actions: ${enablingFailure.actions.join(" | ")}`, {
+                    mode: memoryMode,
+                });
+                enablingSettled?.();
+                return undefined;
+            };
+            api.logger?.info(`memory enabling started (mode=${memoryMode}, embedding=${preset.embeddingModelId})`);
+            // 检查 1: native .node sidecar (纯本地, 零网络)。宿主注入路径优先
+            // (安装店副本自解析不可达, 见 MemoryCapabilityContext.hostOnnxRuntimeEntryPath)。
+            const nativeProblem = nativeBinaryCheck(context.hostOnnxRuntimeEntryPath);
+            if (nativeProblem !== undefined)
+                return failEnabling(nativeProblem);
+            // 检查 1b: 重依赖供给。宿主入口路径优先; 未提供时插件位置自解析,
+            // 两者都不可达 = 原本要到加载步才以 "Cannot find module" 泛化包装
+            // 失败的根因, 前置到模型下载之前以 onnx 缺供分支同构的精准文案报告。
+            // 路径已提供但包损坏的真实失败仍走加载步, 由泛化包装保留原始错误。
+            const missingHeavyDependencies = missingHeavyDependencyModules({ lancedb: context.hostLancedbEntryPath, transformers: context.hostTransformersEntryPath }, resolveHeavyDependencyEntryPath);
+            if (missingHeavyDependencies.length > 0) {
+                return failEnabling(`${missingHeavyDependencies.join(", ")} are not provided by the host installation and could not be resolved from the plugin location; to enable memory features, install them in the host project (npm i ${missingHeavyDependencies.join(" ")}) and restart the session`);
+            }
+            // 检查 2: 模型文件 (缺失 = 进入下载; 存在但截断 = 失败提示手动导入)。
+            const embeddingProblem = modelFilesCheck(modelCacheDir, preset.embeddingModelId, MODEL_MIN_WEIGHT_BYTES[memoryMode]);
+            const rerankerProblem = modelFilesCheck(modelCacheDir, VECTOR_RERANKER_MODEL_ID, RERANKER_MIN_WEIGHT_BYTES);
+            const modelsMissing = embeddingProblem === "missing" || rerankerProblem === "missing"
+                ? `${preset.embeddingModelId}${rerankerProblem === "missing" ? ` + ${VECTOR_RERANKER_MODEL_ID}` : ""}`
+                : undefined;
+            if (embeddingProblem !== undefined && embeddingProblem !== "missing")
+                return failEnabling(embeddingProblem);
+            if (rerankerProblem !== undefined && rerankerProblem !== "missing")
+                return failEnabling(rerankerProblem);
+            if (modelsMissing !== undefined) {
+                api.logger?.info(`memory enabling: model files missing (${modelsMissing}); downloading via configured mirrors`);
+            }
+            // 检查 3: 磁盘余量 (light ≥ 500MB / full ≥ 2GB)。
+            const diskProblem = await diskHeadroomCheck(context.agentDir, DISK_HEADROOM_MIN_BYTES[memoryMode]);
+            if (diskProblem !== undefined)
+                return failEnabling(diskProblem);
+            // 加载: transformers/lancedb 的动态 import 都在这些模块内部, 这里只做
+            // 模块级懒加载, 保持未触发会话零重依赖。进度周期性落一行 (下载可达
+            // 数百 MB), 完成后清除。
+            const progressTimer = setInterval(() => {
+                api.logger?.info("memory enabling still in progress (downloading/loading models)");
+            }, ENABLING_PROGRESS_LOG_INTERVAL_MS);
+            if (typeof progressTimer === "object" && "unref" in progressTimer)
+                progressTimer.unref();
+            try {
+                const [vectorIndexModule, embeddingModule, rerankerModule] = await Promise.all([
+                    import("./memory/vector-index.js"),
+                    import("./memory/embedding-provider.js"),
+                    import("./memory/embedding-reranker.js"),
+                ]);
+                const index = await vectorIndexModule.createMemoryVectorIndex({
+                    dbPath: join(context.agentDir, "memory", VECTOR_DB_DIRNAME),
+                    dimensions: preset.dimensions,
+                    ...(context.hostLancedbEntryPath === undefined ? {} : { moduleEntryPath: context.hostLancedbEntryPath }),
+                });
+                const remoteHosts = remoteHostsForEnabling();
+                const channel = {
+                    embed: embeddingModule.createTransformersEmbeddingProvider({
+                        modelId: preset.embeddingModelId,
+                        dimensions: preset.dimensions,
+                        cacheDir: modelCacheDir,
+                        remoteHosts,
+                        ...(context.hostTransformersEntryPath === undefined
+                            ? {}
+                            : { moduleEntryPath: context.hostTransformersEntryPath }),
+                        ...(enablingOverride?.embeddingLoadImpl === undefined
+                            ? {}
+                            : { loadImpl: enablingOverride.embeddingLoadImpl }),
+                    }),
+                    reranker: rerankerModule.createTransformersReranker({
+                        modelId: VECTOR_RERANKER_MODEL_ID,
+                        cacheDir: modelCacheDir,
+                        remoteHosts,
+                        ...(context.hostTransformersEntryPath === undefined
+                            ? {}
+                            : { moduleEntryPath: context.hostTransformersEntryPath }),
+                        ...(enablingOverride?.rerankerLoadImpl === undefined
+                            ? {}
+                            : { loadImpl: enablingOverride.rerankerLoadImpl }),
+                    }),
+                    index,
+                    queryPrefix: preset.queryPrefix,
+                    embeddingModelId: preset.embeddingModelId,
+                };
+                // 冒烟: embed 一条 (同时完成模型加载) + 投影档位比对。
+                await channel.embed.embed(["memory enabling smoke test"]);
+                if (channel.embed.modelId !== preset.embeddingModelId) {
+                    return failEnabling(`smoke check failed: embedding modelId ${channel.embed.modelId} does not match the ${memoryMode} preset ${preset.embeddingModelId}`);
+                }
+                const storedModelId = await channel.index.getStoredModelId();
+                if (storedModelId !== undefined && storedModelId !== preset.embeddingModelId) {
+                    api.logger?.warn(`memory projection was built for ${storedModelId}, preset is ${preset.embeddingModelId}; startup reconciliation will rebuild it`);
+                }
+                vectorChannel = channel;
+                vectorState = "ready";
+                api.logger?.info(`memory ready (mode=${memoryMode}, embedding=${preset.embeddingModelId})`);
+                enablingSettled?.();
+                return channel;
+            }
+            catch (error) {
+                return failEnabling(`model load or smoke check failed (${error instanceof Error ? error.message : String(error)})`);
+            }
+            finally {
+                clearInterval(progressTimer);
+            }
+        })();
+        return vectorInitPromise;
+    };
+    /**
+     * 写入埋点 (canonical 已提交后): fire-and-forget, 不阻塞工具返回、不抛出。
+     * embed/upsert 失败记一次 degraded, 该条由启动对账补齐 — canonical 与工具
+     * 返回不受影响 (向量投影只是 index 副本)。full 档语义合并 (S3) 时携带探测
+     * 产物: 复用探测已算出的新 statement 向量; 合并命中在 upsert 新行后移除被
+     * supersedes 的旧行 (upsert 新 id 是插入而非覆盖, 旧行必须显式移除, 失败走
+     * 同一 degraded 告警 — 残行由召回侧 superseded 过滤 + 对账跳过回填兜底)。
+     */
+    const vectorUpsertAtom = (atom, mergeOutcome) => {
+        if (!vectorEnabled())
+            return;
+        void vectorEnqueue(async () => {
+            const channel = await vectorEnsure();
+            if (channel === undefined)
+                return;
+            try {
+                const statement = statementOf(atom.payload);
+                const [vector] = mergeOutcome === undefined ? await channel.embed.embed([statement]) : [mergeOutcome.vector];
+                await channel.index.upsert([
+                    {
+                        memoryId: atom.memoryId,
+                        owner: BUILTIN_MEMORY_OWNER,
+                        modelId: channel.embed.modelId,
+                        statement,
+                        tags: tagFacetsOf(atom),
+                        vector,
+                    },
+                ]);
+                if (mergeOutcome?.plan.kind === "merge") {
+                    await channel.index.remove([mergeOutcome.plan.targetMemoryId]);
+                }
+            }
+            catch (error) {
+                if (!vectorDegradedWarned) {
+                    vectorDegradedWarned = true;
+                    api.logger?.warn("memory vector projection write failed; the entry is rebuilt by startup reconciliation", {
+                        memoryId: atom.memoryId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+    };
+    /**
+     * 当前 store 内被 supersedes 关系指向的 memoryId 集 (S3): 写入探测跳过已
+     * 继任的近邻 (其继任条目才是当前事实), 启动对账跳过回填 (投影只维护未继任
+     * 条目)。O(n) 扫描, 与 recall 关系扩散建图同量级。
+     */
+    const supersededMemoryIds = () => {
+        const superseded = new Set();
+        for (const record of store.list({ owner: BUILTIN_MEMORY_OWNER })) {
+            for (const relation of record.atom.relations) {
+                if (relation.kind === "supersedes" && relation.targetMemoryId !== undefined) {
+                    superseded.add(relation.targetMemoryId);
+                }
+            }
+        }
+        return superseded;
+    };
+    /** 语义合并探测失败的一次性降级告警标记 (失败按普通新条目写入, 不刷屏)。 */
+    let semanticMergeProbeWarned = false;
+    /**
+     * 写入语义合并探测 (S3, full 档独有; 在 canonical 提交前执行 — supersedes/
+     * conflict 关系必须随新 atom 一次性提交, atom 不可变)。同一 vectorQueue 串
+     * 行域内: embed(statement) → 同 owner KNN top-5 → canonical 回查 (同域可见、
+     * 未被继任) → 重嵌各近邻的 canonical statement 计算余弦 (阈值作用在 canonical
+     * 文本的向量上, 不依赖可能陈旧的投影 body) → 三分支判定。时序保证"排除自身
+     * observationId 条目": 新 atom 尚未提交, 其 memoryId 不可能在投影中;
+     * observationId 重放 (deduped) 消费不到探测产物, 幂等零副作用。探测失败不
+     * 阻塞写入 (降级为普通新条目并告警一次); enabling 未落定/failed 不等待 —
+     * 写入不得被模型加载阻塞。
+     */
+    const semanticMergeProbe = (input) => {
+        if (vectorState === "enabling" || vectorState === "failed")
+            return Promise.resolve(undefined);
+        return vectorEnqueue(async () => {
+            const channel = await vectorEnsure();
+            if (channel === undefined)
+                return undefined;
+            try {
+                const [vector] = await channel.embed.embed([input.statement]);
+                const hits = await channel.index.queryKnn(vector, {
+                    owner: BUILTIN_MEMORY_OWNER,
+                    limit: SEMANTIC_MERGE_KNN_LIMIT,
+                });
+                if (hits.length === 0)
+                    return { plan: { kind: "new" }, vector };
+                const superseded = supersededMemoryIds();
+                const neighborAtoms = [];
+                for (const hit of hits) {
+                    const record = store.get(hit.memoryId, {
+                        owner: BUILTIN_MEMORY_OWNER,
+                        ...(input.domain.kind === "suite" ? { suiteId: input.domain.suiteId } : {}),
+                    });
+                    if (record === undefined)
+                        continue;
+                    // 域隔离: 合并只发生在同域条目之间 (suite 写入不得 supersedes 跨
+                    // suite/跨域条目 — 那会移除别域召回所需的投影行; promoted 的跨
+                    // suite 可见偏好 canonical 归属其原 suite, 同样不作为合并目标)。
+                    if (input.domain.kind === "suite"
+                        ? record.atom.suiteId !== input.domain.suiteId
+                        : record.atom.suiteId !== undefined) {
+                        continue;
+                    }
+                    if (superseded.has(record.atom.memoryId))
+                        continue;
+                    neighborAtoms.push(record.atom);
+                }
+                if (neighborAtoms.length === 0)
+                    return { plan: { kind: "new" }, vector };
+                const neighborVectors = await channel.embed.embed(neighborAtoms.map((atom) => statementOf(atom.payload)));
+                const neighbors = neighborAtoms.map((atom, position) => ({
+                    memoryId: atom.memoryId,
+                    tags: tagFacetsOf(atom),
+                    cosine: cosineSimilarity(vector, neighborVectors[position] ?? []),
+                }));
+                return { plan: decideSemanticMergePlan({ newTags: input.newTags, neighbors }), vector };
+            }
+            catch (error) {
+                if (!semanticMergeProbeWarned) {
+                    semanticMergeProbeWarned = true;
+                    api.logger?.warn("memory semantic merge probe failed; the entry is written as a new memory", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                return undefined;
+            }
+        });
+    };
+    /**
+     * purge 的 index 副本分派: 通道非 ready/degraded 时 no-op 且不报错 (enabling
+     * 未完成/failed = 索引无本会话写入的行, 残行由 store 回查兜底不可出线)。
+     * remove 异步且失败只记 degraded: 残行永远过不了 recall 的 store 回查, 不构
+     * 成出线泄漏。
+     */
+    const vectorPurgeMemories = (memoryIds) => {
+        if (vectorState !== "ready" && vectorState !== "degraded")
+            return;
+        void vectorEnqueue(async () => {
+            const channel = vectorChannel;
+            if (channel === undefined)
+                return;
+            try {
+                await channel.index.remove(memoryIds);
+            }
+            catch (error) {
+                if (!vectorDegradedWarned) {
+                    vectorDegradedWarned = true;
+                    api.logger?.warn("memory vector projection purge failed; stale rows stay unreachable via the store lookup", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+    };
+    /**
+     * 启动对账 (一次性, capability 初始化语义内; fire-and-forget 不阻塞首工具):
+     * 1) 投影 modelId 与预设不一致 (含 undefined 且表非空) → 清空向量表;
+     * 2) diff store 全量 memoryId vs 投影, 缺失的分批 embed+upsert, 单次上限
+     * {@link RECONCILE_MAX_UPSERTS}, 超出记 degraded 下次启动继续。对账失败不
+     * 阻塞 capability 启动, 状态转 degraded (运行期故障, 可自愈: 后续向量操作
+     * 重新触发补齐语义, canonical 面不受影响)。
+     */
+    let vectorReconcileStarted = false;
+    const vectorReconcileOnce = () => {
+        if (!vectorEnabled() || vectorReconcileStarted)
+            return;
+        vectorReconcileStarted = true;
+        void vectorEnqueue(async () => {
+            const channel = await vectorEnsure();
+            if (channel === undefined)
+                return;
+            try {
+                const storedModelId = await channel.index.getStoredModelId();
+                if (storedModelId !== channel.embeddingModelId) {
+                    const stale = await channel.index.listMemoryIds();
+                    if (stale.size > 0)
+                        await channel.index.remove([...stale]);
+                }
+                const indexed = await channel.index.listMemoryIds();
+                // 被继任的旧条目不回填投影 (S3): 合并已移除其行, 对账的重放/重建
+                // 不得复活 (召回可见性由继任条目承担, canonical 侧保留可直查)。
+                const superseded = supersededMemoryIds();
+                const missing = [];
+                for (const record of store.list({ owner: BUILTIN_MEMORY_OWNER })) {
+                    if (superseded.has(record.atom.memoryId))
+                        continue;
+                    if (!indexed.has(record.atom.memoryId))
+                        missing.push(record.atom);
+                }
+                if (missing.length > RECONCILE_MAX_UPSERTS) {
+                    api.logger?.warn("memory vector reconciliation capped; remaining entries rebuild on the next startup", {
+                        total: missing.length,
+                        cap: RECONCILE_MAX_UPSERTS,
+                    });
+                }
+                const batch = missing.slice(0, RECONCILE_MAX_UPSERTS);
+                if (batch.length === 0)
+                    return;
+                const statements = batch.map((atom) => statementOf(atom.payload));
+                const vectors = await channel.embed.embed(statements);
+                await channel.index.upsert(batch.map((atom, position) => ({
+                    memoryId: atom.memoryId,
+                    owner: BUILTIN_MEMORY_OWNER,
+                    modelId: channel.embed.modelId,
+                    statement: statements[position],
+                    tags: tagFacetsOf(atom),
+                    vector: vectors[position],
+                })));
+            }
+            catch (error) {
+                vectorState = "degraded";
+                api.logger?.warn("memory vector reconciliation failed; the channel is degraded (canonical recall degrades, self-heals on the next successful channel op)", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+    };
+    const buildWriteAtom = (input) => {
+        writeSequence += 1;
+        const observationId = `memory_write:${sessionId}:${writeSequence}`;
+        const memoryId = `mem-${identityHash(`${BUILTIN_MEMORY_OWNER}\u0000${observationId}`)}`;
+        const occurredAt = new Date(now()).toISOString();
+        const sourceRef = { kind: "tool", id: `memory_write:${observationId}` };
+        const tags = (input.tags ?? []).map((tag) => tag.trim()).filter((tag) => tag !== "");
+        const facets = tags.map((tag) => ({
+            namespace: TAG_FACET_NAMESPACE,
+            schemaVersion: 1,
+            key: "tag",
+            value: tag,
+        }));
+        const preferenceEnvelope = input.kind === "preference"
+            ? {
+                subject: input.subject,
+                key: "statement",
+                preferredValue: input.content,
+                scope: { level: "profile-private" },
+                evidence: { class: "explicit", sourceRefs: [sourceRef], confidence: 1 },
+                applicabilityConfidence: 1,
+            }
+            : undefined;
+        return buildMemoryAtomV1({
+            memoryId,
+            contractVersion: MEMORY_CONTRACT_VERSION,
+            schemaVersion: 1,
+            scope: "long-term",
+            retentionMode: "long",
+            owner: BUILTIN_MEMORY_OWNER,
+            profileId: capabilityManifest.id,
+            ...(input.domain.kind === "suite" ? { suiteId: input.domain.suiteId } : {}),
+            retentionPolicyVersion: "retention@1",
+            memoryKind: input.kind === "preference" ? "preference" : "fact",
+            payload: { statement: input.content },
+            ...(preferenceEnvelope === undefined ? {} : { preference: preferenceEnvelope }),
+            occurredAt,
+            recordedAt: occurredAt,
+            sourceRefs: [sourceRef],
+            observationId,
+            sessionRefs: [sessionId],
+            agentInstanceRefs: [],
+            projectRefs: [],
+            subjectRefs: [],
+            facets,
+            relations: input.relations ?? [],
+            confidence: 1,
+            importance: 0.5,
+            evidenceClass: "explicit",
+            contentRevision: `c-${identityHash(input.content)}`,
+            writeReason: input.writeReason ?? `${capabilityManifest.id}/memory_write`,
+        });
+    };
+    const writeTool = api.registerTool({
+        name: "memory_write",
+        label: "Write memory",
+        description: "Persist one durable memory (a fact or a user preference) scoped to the current suite; it stays recallable across sessions until forgotten",
+        parameters: writeSchema,
+        execute: async (first, second) => {
+            const input = memoryToolInput(first, second);
+            assertNonEmptyString(input.content, "content");
+            // 长度契约 (混合检索工程化 §5): 超长显式拒绝并提示拆分, 而非静默截断。
+            if (input.content.length > MEMORY_CONTENT_MAX_LENGTH) {
+                throw new Error(`content is ${input.content.length} characters; the memory content limit is ${MEMORY_CONTENT_MAX_LENGTH} — split it into multiple self-contained memories`);
+            }
+            if (input.kind !== "fact" && input.kind !== "preference")
+                throw new Error('kind must be "fact" or "preference"');
+            if (input.kind === "preference") {
+                assertNonEmptyString(input.subject, 'subject (required when kind is "preference")');
+            }
+            if (input.subject !== undefined)
+                assertNonEmptyString(input.subject, "subject");
+            if (input.tags !== undefined) {
+                if (!Array.isArray(input.tags) || input.tags.length > MAX_TAGS) {
+                    throw new Error(`tags must be an array of at most ${MAX_TAGS} strings`);
+                }
+                for (const tag of input.tags)
+                    assertNonEmptyString(tag, "tags entry");
+            }
+            const { domain, domainName, ledger } = resolveDomain();
+            // 语义合并探测 (2.4d6 S3, full 档独有): light 档完全跳过 (写向量投影
+            // 不查近邻, 行为与现状一致)。探测在 canonical 提交前执行, 判定决定新
+            // atom 的 supersedes/conflict relations (atom 不可变, 随提交一次写入);
+            // 探测失败降级为普通新条目 (告警一次, 不阻塞写入)。
+            const mergeOutcome = memoryMode === "full"
+                ? await semanticMergeProbe({
+                    statement: input.content,
+                    newTags: input.tags ?? [],
+                    domain,
+                })
+                : undefined;
+            const atom = buildWriteAtom({
+                content: input.content,
+                kind: input.kind,
+                domain,
+                ...(input.subject === undefined ? {} : { subject: input.subject }),
+                ...(input.tags === undefined ? {} : { tags: input.tags }),
+                ...(mergeOutcome === undefined
+                    ? {}
+                    : { relations: semanticMergeRelations(mergeOutcome.plan, input.content) }),
+            });
+            const observation = schedulerApi.submitObservation({
+                owner: BUILTIN_MEMORY_OWNER,
+                observationId: atom.observationId,
+                draft: atom,
+            });
+            if (observation.state === "rejected") {
+                throw new Error(`memory rejected: ${observation.reason ?? "rejected"}`);
+            }
+            const candidate = schedulerApi.submitCandidate({
+                observationId: atom.observationId,
+                owner: BUILTIN_MEMORY_OWNER,
+            });
+            if (candidate.status === "rejected")
+                throw new Error(`memory rejected: ${candidate.reason ?? "rejected"}`);
+            if (candidate.status === "committed") {
+                ledger.append(atom);
+                // 向量投影埋点 (混合检索工程化): canonical 已提交, 投影写入异步旁路,
+                // 失败不阻塞不抛出 (vectorUpsertAtom 内部消化)。full 档携带语义合并
+                // 探测产物 (复用探测向量; 合并命中同时移除被 supersedes 的旧行)。
+                vectorUpsertAtom(atom, mergeOutcome);
+            }
+            await api.publish({
+                type: EVENT_TYPE,
+                version: 1,
+                correlationId: capabilityManifest.id,
+                data: { action: "written", memoryId: candidate.memoryId, memoryKind: atom.memoryKind, domain: domainName },
+            });
+            // 偏好晋升触发 (B2): the /promote capability command is the production
+            // caller of promotePreferenceToUserDefault; the tip is what tells the
+            // model (so it can tell the user) that the cross-suite promotion path
+            // exists. Facts have no promotion path — no tip.
+            return {
+                memoryId: candidate.memoryId,
+                kind: atom.memoryKind,
+                domain: domainName,
+                ...(atom.memoryKind === "preference"
+                    ? {
+                        tip: "[tip] If this is a general preference (not project-specific), the user can promote it across all suites using /promote.",
+                    }
+                    : {}),
+            };
+        },
+    });
+    /** recency 排序 (occurredAt 降序, memoryId 升序打破并列 — 与 recall index 同口径)。 */
+    const recencyOrdered = (entries) => [...entries]
+        .sort((left, right) => Date.parse(right.atom.occurredAt) - Date.parse(left.atom.occurredAt) ||
+        (left.atom.memoryId < right.atom.memoryId ? -1 : 1))
+        .map((entry, position) => ({ atom: entry.atom, position }));
+    /**
+     * superseded 过滤 (S3-B, store 回查后 / 精排前): 被某条在场候选的 supersedes
+     * 关系指向的旧条目不再出线 — 合并后同义查询只出新条目。"新条目在场"以候选
+     * 集为界: 继任条目被遗忘 (purge/过期) 后其关系随之消失, 旧条目自然恢复出线。
+     * memoryId 主键直查不经此过滤 (引用不失效), memory_list 管理面不过滤
+     * (nothing silently dropped — 用户可显式 forget 旧条目)。
+     */
+    const filterSupersededCandidates = (candidates) => {
+        const superseded = new Set();
+        for (const entry of candidates) {
+            for (const relation of entry.atom.relations) {
+                if (relation.kind === "supersedes" && relation.targetMemoryId !== undefined) {
+                    superseded.add(relation.targetMemoryId);
+                }
+            }
+        }
+        if (superseded.size === 0)
+            return candidates;
+        return candidates.filter((entry) => !superseded.has(entry.atom.memoryId));
+    };
+    /**
+     * store 回查 (正确性关键): 候选 id 逐条走与旧锚点通道相同的可见性单一路径
+     * (owner + suite 读边界 + 过期, 单一路径); suite 场景下不可见 id 按 legacy/
+     * 外套件区分计数 (suiteFilter 可观测), 不可见者丢弃且不回填 (诚实分页)。
+     */
+    const lookupCandidates = (rankedIds, suiteId) => {
+        const candidates = [];
+        let legacySkipped = 0;
+        let foreignSuiteSkipped = 0;
+        for (const [memoryId, position] of rankedIds) {
+            const record = store.get(memoryId, {
+                owner: BUILTIN_MEMORY_OWNER,
+                ...(suiteId === undefined ? {} : { suiteId }),
+            });
+            if (record !== undefined) {
+                candidates.push({ atom: record.atom, position });
+                continue;
+            }
+            if (suiteId !== undefined) {
+                const unfiltered = store.get(memoryId, { owner: BUILTIN_MEMORY_OWNER });
+                if (unfiltered !== undefined) {
+                    if (unfiltered.atom.suiteId === undefined)
+                        legacySkipped += 1;
+                    else
+                        foreignSuiteSkipped += 1;
+                }
+            }
+        }
+        return { candidates, suiteFilter: { legacySkipped, foreignSuiteSkipped } };
+    };
+    /**
+     * egress 门重放 (设计 §11 MUST run): 对最终候选统一执行, 与旧锚点 packet 同
+     * 一 gate、同一 factInfo 来源 (store); blocked 即 fail-closed, 该次 recall
+     * 返回 failed packet (来源未登记的事实永不越过出界面)。
+     */
+    const egressGate = (candidates) => {
+        const factInfo = {};
+        for (const entry of candidates) {
+            factInfo[entry.atom.memoryId] = {
+                sourceRefs: entry.atom.sourceRefs,
+                payload: entry.atom.payload,
+            };
+        }
+        return egressPolicy.apply({
+            operationId: `memory_recall:${sessionId}:${identityHash(candidates.map((entry) => entry.atom.memoryId).join("\u0000"))}`,
+            status: "completed",
+            facts: candidates.map((entry) => ({
+                memoryId: entry.atom.memoryId,
+                contentRevision: entry.atom.contentRevision,
+                statement: JSON.stringify(entry.atom.payload),
+                confidence: entry.atom.confidence,
+            })),
+            queryPlan: { lookupUsed: false, filtersApplied: [], scorerVersion: "semantic-rrf@1" },
+            attempts: 0,
+            narrowingHints: [],
+            omittedCount: 0,
+            truncated: false,
+            truncationScope: "none",
+            budget: {
+                candidateBudget: 0,
+                modelInspectionLimit: 0,
+                finalResultLimit: 0,
+                used: { candidateCount: 0, modelInspectedCount: 0, finalResultCount: 0 },
+            },
+        }, factInfo);
+    };
+    const recallSemantically = async (input) => {
+        // 读侧先等写侧队列落定 (启动对账 + 待处理的投影写入), 保证 recall 与
+        // 仓库/投影的线性一致: 本调用之前提交的记忆要么在 store 要么已补进投影,
+        // 不会与后台对账/埋点竞态。
+        await vectorQueue;
+        const channel = await vectorEnsure();
+        if (channel === undefined) {
+            return {
+                kind: "unavailable",
+                message: enablingFailure === undefined
+                    ? `memory channel is unavailable (state=${vectorState})`
+                    : `memory enabling failed: ${enablingFailure.reason} — actions: ${enablingFailure.actions.join(" | ")}`,
+            };
+        }
+        const suiteId = input.domain.kind === "suite" ? input.domain.suiteId : undefined;
+        let vectorFailed = false;
+        let ftsFailed = false;
+        let knnHits;
+        let ftsHits;
+        try {
+            const [queryVector] = await channel.embed.embed([channel.queryPrefix + input.query]);
+            knnHits = await channel.index.queryKnn(queryVector, {
+                owner: BUILTIN_MEMORY_OWNER,
+                limit: HYBRID_CHANNEL_DEPTH,
+            });
+        }
+        catch (error) {
+            vectorFailed = true;
+            api.logger?.warn("memory recall degraded: the vector channel failed; continuing on the FTS channel", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        try {
+            ftsHits = await channel.index.queryFts(input.query, {
+                owner: BUILTIN_MEMORY_OWNER,
+                limit: HYBRID_CHANNEL_DEPTH,
+            });
+        }
+        catch (error) {
+            ftsFailed = true;
+            api.logger?.warn("memory recall degraded: the FTS channel failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        let candidates;
+        let suiteFilter = { legacySkipped: 0, foreignSuiteSkipped: 0 };
+        let channelDegraded = false;
+        if (!vectorFailed && !ftsFailed && knnHits !== undefined && ftsHits !== undefined) {
+            // 主路径: 双通道 RRF k=60 融合 top20。
+            const pool = rrfFuseRankings([ftsHits.map((hit) => hit.memoryId), knnHits.map((hit) => hit.memoryId)]);
+            const lookup = lookupCandidates(pool.map((memoryId, position) => [memoryId, position]), suiteId);
+            candidates = lookup.candidates;
+            suiteFilter = lookup.suiteFilter;
+        }
+        else if (ftsHits !== undefined) {
+            // 向量失败: FTS-only + recency 排序。
+            channelDegraded = true;
+            const lookup = lookupCandidates(ftsHits.map((hit, position) => [hit.memoryId, position]), suiteId);
+            candidates = recencyOrdered(lookup.candidates);
+            suiteFilter = lookup.suiteFilter;
+        }
+        else if (knnHits !== undefined) {
+            // FTS 失败: KNN-only + recency 排序 (对称降级)。
+            channelDegraded = true;
+            const lookup = lookupCandidates(knnHits.map((hit, position) => [hit.memoryId, position]), suiteId);
+            candidates = recencyOrdered(lookup.candidates);
+            suiteFilter = lookup.suiteFilter;
+        }
+        else {
+            // 双通道皆败: 域内 recency 枚举兜底 (store.list, 列表语义保留)。
+            channelDegraded = true;
+            const page = listDomainMemories({ store }, { owner: BUILTIN_MEMORY_OWNER, domain: input.domain });
+            const domainCandidates = [];
+            for (const entry of page.entries) {
+                const record = store.get(entry.memoryId, { owner: BUILTIN_MEMORY_OWNER });
+                if (record !== undefined)
+                    domainCandidates.push({ atom: record.atom, position: 0 });
+            }
+            candidates = recencyOrdered(domainCandidates);
+        }
+        // 运行期通道故障 → degraded (可自愈: 下一次全通 recall 回 ready)。
+        if (channelDegraded)
+            vectorState = "degraded";
+        else if (vectorState === "degraded")
+            vectorState = "ready";
+        // superseded 过滤 (S3-B): 回查后、egress/精排前 (主路径与全部降级路径
+        // 统一收敛于此 — 被继任的旧条目任何通道都不再出线)。
+        candidates = filterSupersededCandidates(candidates);
+        if (candidates.length === 0) {
+            return { kind: "served", facts: [], candidateCount: 0, suiteFilter };
+        }
+        const egressOutcome = egressGate(candidates);
+        if (egressOutcome.status === "blocked")
+            return { kind: "blocked", reason: egressOutcome.reason };
+        const statementByMemoryId = new Map(egressOutcome.packet.facts.map((fact) => [fact.memoryId, fact.statement]));
+        let ordered = candidates.map((entry) => ({
+            memoryId: entry.atom.memoryId,
+            statement: unwrapEgressStatement(statementByMemoryId.get(entry.atom.memoryId) ?? ""),
+            confidence: entry.atom.confidence,
+            position: entry.position,
+        }));
+        // 精排 (仅主融合路径: 降级页的排序即其降级语义)。reranker 不可用或调用
+        // 失败 → 保持 RRF 序 (精排失败 → RRF 序), 各记一次结构化日志。
+        const reranker = channel.reranker;
+        if (!channelDegraded && reranker !== undefined && !vectorRerankerUnavailable) {
+            try {
+                const scores = await reranker.rerank(input.query, ordered.map((fact) => fact.statement));
+                ordered = ordered
+                    .map((fact, position) => ({ ...fact, score: scores[position] }))
+                    .sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.position - right.position);
+            }
+            catch (error) {
+                vectorRerankerUnavailable = true;
+                api.logger?.warn("memory reranker failed; recall continues on the RRF order", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // minScore 门槛 (§2.1): 仅精排实际产生 score 的候选参与过滤 (score <
+        // minScore 丢弃), 过滤先于 limit 截取; 降级路径与无 score 的候选不受影响。
+        const minScore = input.minScore;
+        const eligible = minScore === undefined
+            ? ordered
+            : ordered.filter((fact) => fact.score === undefined || fact.score >= minScore);
+        return {
+            kind: "served",
+            facts: eligible
+                .slice(0, input.limit)
+                .map(({ memoryId, statement, confidence }) => ({ memoryId, statement, confidence })),
+            candidateCount: ordered.length,
+            suiteFilter,
+        };
+    };
+    // 提取为具名闭包: 除模型工具面外, 下方的 auto-recall 钩子直接调用同一 execute
+    // (单参输入约定, memoryToolInput 取第一参), 不经 runtime.invokeTool —— 钩子
+    // 随插件注册/卸载, 与工具面同生命周期, 替换工具面不会重接自动召回。
+    const recallExecute = async (first, second) => {
+        const input = memoryToolInput(first, second);
+        assertNonEmptyString(input.query, "query");
+        const rawLimit = input.limit;
+        const limit = rawLimit === undefined
+            ? DEFAULT_RECALL_LIMIT
+            : (() => {
+                if (typeof rawLimit !== "number" ||
+                    !Number.isSafeInteger(rawLimit) ||
+                    rawLimit < 1 ||
+                    rawLimit > 100) {
+                    throw new Error("limit must be an integer between 1 and 100");
+                }
+                return rawLimit;
+            })();
+        // 内部执行缝 (§2.1): auto-recall 闭包经本字段恒传质量门槛; memory_recall
+        // 工具 schema 不含该参数 (工具面恒 undefined), 显式召回行为不变。
+        const rawMinScore = input.minScore;
+        const minScore = rawMinScore === undefined
+            ? undefined
+            : (() => {
+                if (typeof rawMinScore !== "number" || !Number.isFinite(rawMinScore)) {
+                    throw new Error("minScore must be a finite number");
+                }
+                return rawMinScore;
+            })();
+        const context = parseRecallContext(input.context);
+        const { domain } = resolveDomain();
+        // enabling 失败 = 本实例终态 (mode 记录回退 off): 记忆工具返回携带原因
+        // 与五选一行动清单的不可用 packet (设计 §3.2 硬性要求), 不再重试。
+        if (vectorState === "failed") {
+            const failure = enablingFailure ?? { reason: "memory enabling failed", actions: [] };
+            return {
+                status: "unavailable",
+                state: "failed",
+                facts: [],
+                error: `memory enabling failed: ${failure.reason}`,
+                actions: failure.actions,
+            };
+        }
+        // 主键快路径 (memoryIdEquals 语义保留, 幂等/引用而非检索): query 恰为本
+        // 域可见 memoryId 时直接取该条, 不依赖向量通道 (enabling 期间也可用)。
+        let outcome;
+        const directRecord = store.get(input.query.trim(), {
+            owner: BUILTIN_MEMORY_OWNER,
+            ...(domain.kind === "suite" ? { suiteId: domain.suiteId } : {}),
+        });
+        if (directRecord !== undefined) {
+            const gate = egressGate([{ atom: directRecord.atom, position: 0 }]);
+            if (gate.status === "blocked") {
+                return { status: "failed", facts: [], error: `egress blocked: ${gate.reason}` };
+            }
+            const statementByMemoryId = new Map(gate.packet.facts.map((fact) => [fact.memoryId, fact.statement]));
+            outcome = {
+                kind: "served",
+                facts: [
+                    {
+                        memoryId: directRecord.atom.memoryId,
+                        statement: unwrapEgressStatement(statementByMemoryId.get(directRecord.atom.memoryId) ?? ""),
+                        confidence: directRecord.atom.confidence,
+                    },
+                ],
+                candidateCount: 1,
+                suiteFilter: { legacySkipped: 0, foreignSuiteSkipped: 0 },
+            };
+        }
+        else {
+            try {
+                outcome = await recallSemantically({
+                    query: input.query,
+                    domain,
+                    limit,
+                    ...(minScore === undefined ? {} : { minScore }),
+                });
+            }
+            catch (error) {
+                // 全败 (枚举兜底也失败) → degraded packet: 结构化返回, 不抛给模型。
+                vectorState = "degraded";
+                const message = error instanceof Error ? error.message : String(error);
+                api.logger?.warn("memory recall degraded: every channel failed; returning a degraded packet", {
+                    error: message,
+                });
+                return { status: "failed", facts: [], error: message };
+            }
+        }
+        if (outcome.kind === "blocked") {
+            return { status: "failed", facts: [], error: `egress blocked: ${outcome.reason}` };
+        }
+        if (outcome.kind === "unavailable") {
+            return {
+                status: "unavailable",
+                state: vectorState,
+                facts: [],
+                error: outcome.message,
+            };
+        }
+        const facts = outcome.facts;
+        const resolved = context === undefined
+            ? undefined
+            : applyPreferenceContext({
+                facts,
+                context,
+                resolver: preferenceResolver,
+                disambiguator: preferenceDisambiguator,
+                atomOf: (memoryId) => store.get(memoryId, { owner: BUILTIN_MEMORY_OWNER })?.atom,
+            });
+        // 偏好消歧先于关系扩散: the diffusion seeds are the atoms the user
+        // actually sees — preference facts dropped by the conflict resolution
+        // never diffuse their relations.
+        const finalFacts = resolved === undefined ? facts : resolved.facts;
+        const seeds = [];
+        for (const fact of finalFacts) {
+            const atom = store.get(fact.memoryId, { owner: BUILTIN_MEMORY_OWNER })?.atom;
+            if (atom !== undefined)
+                seeds.push(atom);
+        }
+        // The traversal graph is the recall domain's visible atom set (same
+        // suite read boundary). Diffusion targets outside this set are dropped,
+        // so relations never leak across suites.
+        const domainMemoryIds = new Set();
+        const graph = [];
+        for (const entry of listDomainMemories({ store }, { owner: BUILTIN_MEMORY_OWNER, domain }).entries) {
+            domainMemoryIds.add(entry.memoryId);
+            const atom = store.get(entry.memoryId, { owner: BUILTIN_MEMORY_OWNER })?.atom;
+            if (atom !== undefined)
+                graph.push(atom);
+        }
+        const related = [];
+        let relatedOmittedCount = 0;
+        const seenRelatedMemoryIds = new Set();
+        for (const adapterResult of memoryNetwork.expand({ seeds, graph })) {
+            if (adapterResult.status !== "completed")
+                continue;
+            for (const expansion of adapterResult.related) {
+                if (!domainMemoryIds.has(expansion.memoryId))
+                    continue;
+                if (seenRelatedMemoryIds.has(expansion.memoryId))
+                    continue;
+                seenRelatedMemoryIds.add(expansion.memoryId);
+                if (related.length >= MAX_RELATED_REFS) {
+                    relatedOmittedCount += 1;
+                    continue;
+                }
+                related.push(expansion);
+            }
+        }
+        return {
+            status: finalFacts.length === 0 ? "empty" : "completed",
+            facts: finalFacts,
+            ...(resolved !== undefined && resolved.conflicts.length > 0 ? { conflicts: resolved.conflicts } : {}),
+            ...(domain.kind === "suite" ? { suiteFilter: outcome.suiteFilter } : {}),
+            omittedCount: Math.max(0, outcome.candidateCount - finalFacts.length),
+            truncated: false,
+            // References only — no statement/payload egress; the model fetches
+            // content via memory_list or another memory_recall.
+            ...(related.length > 0
+                ? {
+                    related: related.map((expansion) => ({
+                        memoryId: expansion.memoryId,
+                        relationKind: expansion.relationKind,
+                        hop: expansion.hop,
+                        weight: expansion.weight,
+                        via: expansion.via,
+                    })),
+                }
+                : {}),
+            ...(relatedOmittedCount > 0 ? { relatedOmittedCount } : {}),
+        };
+    };
+    const recallTool = api.registerTool({
+        name: MEMORY_RECALL_TOOL_NAME,
+        label: "Recall memories",
+        promptGuidelines: [MEMORY_TOOLS_GUIDE],
+        description: "Search this suite's durable memories with semantic recall: vector and full-text channels fuse (RRF) and the result is reranked; an exact memoryId retrieves that memory directly; the result may include related memory references (ids and relation metadata only — recall or list a referenced memory again for its content)",
+        parameters: recallSchema,
+        execute: recallExecute,
+    });
+    // ---- B1 记忆自动注入 (auto recall; D-071 增补裁决: 自 sdk transformContext 迁入) ----
+    // transformContext 链上的插件环节: 无事实可注入时返回 undefined 保持输入。工厂
+    // 执行 ⟺ memory 家族注册 (mode=off 时整体不注册), 钩子随插件卸载自动摘除, 无需
+    // 再检查工具在位。失败降级 (recall throw / 契约漂移): 不注入、不阻塞请求, 记
+    // 一条有界 api.logger warn。
+    const autoRecallBlock = async (query) => {
+        try {
+            // §2.1: 自动召回恒传质量门槛 (内部闭包, 不经工具 schema)。
+            const result = await recallExecute({
+                query,
+                limit: MEMORY_AUTO_RECALL_LIMIT,
+                minScore: MEMORY_AUTO_RECALL_MIN_RERANK_SCORE,
+            });
+            // Defensive contract-drift checks: recallExecute is this factory's own
+            // closure, so both branches are unreachable today — they exist in case
+            // the recall body ever grows an adapter seam (then add a test seam for
+            // them; until then there is no honest way to drive them from a test).
+            if (result === null || typeof result !== "object") {
+                api.logger?.warn("memory auto-recall failed: memory_recall returned a non-object result (contract drift)");
+                return "";
+            }
+            const facts = result.facts;
+            if (!Array.isArray(facts)) {
+                api.logger?.warn('memory auto-recall failed: memory_recall returned a non-array "facts" field (contract drift)');
+                return "";
+            }
+            const statements = [];
+            for (const fact of facts) {
+                if (fact !== null && typeof fact === "object") {
+                    const statement = fact.statement;
+                    if (typeof statement === "string" && statement.trim() !== "")
+                        statements.push(statement);
+                }
+            }
+            if (statements.length === 0)
+                return "";
+            return [
+                MEMORY_AUTO_RECALL_MARKER,
+                ...statements.map((statement) => `- ${statement}`),
+                "</auto_recalled_memory>",
+                MEMORY_AUTO_RECALL_DISCLAIMER,
+            ].join("\n");
+        }
+        catch (error) {
+            // Bound by code points, not UTF-16 code units, so the cut never splits a
+            // surrogate pair into a lone surrogate.
+            const message = error instanceof Error ? error.message : String(error);
+            const codePoints = Array.from(message);
+            const bounded = codePoints.length <= MEMORY_AUTO_RECALL_ERROR_MESSAGE_LIMIT
+                ? message
+                : `${codePoints.slice(0, MEMORY_AUTO_RECALL_ERROR_MESSAGE_LIMIT).join("")}…`;
+            api.logger?.warn(`memory auto-recall failed: memory_recall threw: ${bounded}`);
+            return "";
+        }
+    };
+    // Per-session cache keyed by the last user message text: one user turn runs
+    // at most one recall; the remembered block rides every model round of that
+    // turn unchanged, so request-time injections stay idempotent across tool
+    // loops. An empty block means "no injection for this turn" (no facts, or
+    // recall failure — the recall is an enhancement face and must never block
+    // the user's request).
+    const autoRecall = { lastQuery: undefined, block: "" };
+    const autoRecallHook = api.registerLoopHook("transformContext", async (messages) => {
+        const userText = lastBranchUserText(api);
+        if (userText === undefined || userText.trim() === "")
+            return undefined;
+        if (autoRecall.lastQuery !== userText) {
+            autoRecall.lastQuery = userText;
+            autoRecall.block = await autoRecallBlock(userText);
+        }
+        if (autoRecall.block === "")
+            return undefined;
+        return injectAfterLastUserMessage(messages, {
+            role: "user",
+            content: autoRecall.block,
+            timestamp: now(),
+        });
+    });
+    // ---- assistant 偏好卡注入 (统一修复轮 A 交付3; D-075 S4-4 第二批随拆包迁入) ----
+    // 宿主 sdk 曾在 system prompt 的 persona 段后注入本卡; 公共插件 API 无 system
+    // prompt 面, 迁入后经 transformContext 循环钩子注入 (最后一条 user 消息之后,
+    // 与 auto-recall 同一请求时视图)。卡文本与读边界语义逐字保留 (宿主
+    // memory-assistant-card.test.ts pin 的格式): own-suite 偏好 + 已晋升 user-default
+    // 偏好, legacy 原子不可见。会话期一卡: 首次模型轮次惰性读取并缓存 (绑定入口在
+    // 会话构造后才写入, 工厂时间读不到 domain — 与 B1 同因), 后续轮次复用。判定
+    // "assistant 定向" 用 builtin 默认方案 id (宿主 builtin suite 事实: assistant 方
+    // 案的 orientation 即 assistant); 自定义方案的 orientation 宿主未上公共通道,
+    // 不覆盖。IO 错误降级为一条 api.logger warn + 无注入 (插件无 suite 诊断通道,
+    // warn 即对等物), 绝不阻塞请求。
+    const assistantCard = { loaded: false, text: undefined };
+    const preferenceCardHook = api.registerLoopHook("transformContext", async (messages) => {
+        if (!assistantCard.loaded) {
+            assistantCard.loaded = true;
+            const domain = resolveSessionDomain(api);
+            if (domain.kind === "suite" && domain.suiteId === "assistant") {
+                try {
+                    assistantCard.text = loadAssistantPreferenceCard({
+                        agentDir: context.agentDir,
+                        owner: BUILTIN_MEMORY_OWNER,
+                        suiteId: domain.suiteId,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    api.logger?.warn(`assistant preference card could not be loaded: ${message}`);
+                }
+            }
+        }
+        if (assistantCard.text === undefined)
+            return undefined;
+        return injectAfterLastUserMessage(messages, {
+            role: "user",
+            content: assistantCard.text,
+            timestamp: now(),
+        });
+    });
+    // ---- bash 失败教训自动沉淀 (错误教训与召回质量护栏设计 §2.2) ----
+    // 家族内独立开关 (默认 on): mode=off 已在工厂入口零注册; lessons=off 时本块
+    // 不订阅任何事件 (无观察者即无捕获)。两个事件的公开载荷都不含工具入参, 命令
+    // 字符串在 tool.execution.start 时经会话分支的 assistant toolCall 块回读
+    // (与 lastBranchUserText 同一数据来源), 以 toolCallId 配对到 tool.result。
+    const lessonsResolution = resolveMemoryLessons(context.memory?.lessons);
+    if (lessonsResolution.invalidEnvValue !== undefined) {
+        api.logger?.warn(`invalid ${MEMORY_LESSONS_ENV} value "${lessonsResolution.invalidEnvValue}"; bash error-lesson capture stays on`);
+    }
+    // lifecycle 在 CapabilityAPI 类型上是必选成员（experimental），但最小宿主可以
+    // 不带该面；教训是增强面，与 auto-recall 同款降级：缺面时跳过注册、记一条
+    // 有界 warn，不影响记忆家族其余工具面。
+    const lifecycleReady = api.lifecycle !== undefined;
+    if (lessonsResolution.lessons === "on" && !lifecycleReady) {
+        api.logger?.warn("memory bash-lesson capture unavailable: host exposes no lifecycle face");
+    }
+    const lessonRegistrations = [];
+    if (lessonsResolution.lessons === "on" && lifecycleReady) {
+        /** (command, exitCode) 签名去重 (§2.2 风暴闸门): 同签名重复失败只写首条。 */
+        const lessonSignatures = new Set();
+        let lessonsWritten = 0;
+        let lessonCapWarned = false;
+        /** toolCallId → command 配对映射 (仅 bash, 容量 FIFO)。 */
+        const bashCommandsByToolCallId = new Map();
+        const rememberBashCommand = (toolCallId, command) => {
+            if (!bashCommandsByToolCallId.has(toolCallId) &&
+                bashCommandsByToolCallId.size >= MEMORY_LESSON_TOOLCALL_MAP_CAPACITY) {
+                const oldest = bashCommandsByToolCallId.keys().next();
+                if (oldest.done !== true)
+                    bashCommandsByToolCallId.delete(oldest.value);
+            }
+            bashCommandsByToolCallId.set(toolCallId, command);
+        };
+        /**
+         * 从会话分支回读该 toolCall 的 bash 命令 (assistant toolCall 块, 最新
+         * 优先): assistant 消息在工具执行前已入分支, tool.execution.start 时可查。
+         */
+        const bashCommandForToolCall = (toolCallId) => {
+            const entries = api.session?.getBranchEntries() ?? [];
+            for (let index = entries.length - 1; index >= 0; index -= 1) {
+                const entry = entries[index];
+                if (entry.type !== "message" || entry.message?.role !== "assistant")
+                    continue;
+                const content = entry.message.content;
+                if (!Array.isArray(content))
+                    continue;
+                for (const item of content) {
+                    if (!isPlainObject(item) || item.type !== "toolCall" || item.id !== toolCallId)
+                        continue;
+                    const args = item.arguments;
+                    const command = isPlainObject(args) ? args.command : undefined;
+                    if (typeof command === "string" && command.trim() !== "")
+                        return command;
+                }
+            }
+            return undefined;
+        };
+        /**
+         * 内部直写 (与 /promote 同构): ledger 追加持久副本, store.commit 以
+         * retentionModeId "short" 覆盖保留档 (7 天到期失去召回资格, 不物理清除),
+         * 向量投影异步埋点。教训不是模型工具调用, 不经 candidate 状态机。
+         */
+        const writeLesson = (command, exitCode, errorText) => {
+            const signature = `${command}\u0000${exitCode}`;
+            if (lessonSignatures.has(signature))
+                return;
+            if (lessonsWritten >= MEMORY_LESSON_MAX_PER_SESSION) {
+                if (!lessonCapWarned) {
+                    lessonCapWarned = true;
+                    api.logger?.warn(`memory bash-lesson cap reached (${MEMORY_LESSON_MAX_PER_SESSION} per instance); further failures are not captured`);
+                }
+                return;
+            }
+            const { domain, ledger } = resolveDomain();
+            const atom = buildWriteAtom({
+                content: buildLessonContent(command, exitCode, errorText),
+                kind: "fact",
+                tags: [...MEMORY_LESSON_TAGS],
+                domain,
+                writeReason: `${capabilityManifest.id}/auto-lesson`,
+            });
+            ledger.append(atom);
+            store.commit(atom, { retentionModeId: MEMORY_LESSON_RETENTION_MODE_ID });
+            vectorUpsertAtom(atom);
+            lessonsWritten += 1;
+            lessonSignatures.add(signature);
+        };
+        lessonRegistrations.push(api.lifecycle.registerObserve(TOOL_EXECUTION_START_EVENT_ID, (event) => {
+            if (event.data.toolName !== "bash")
+                return;
+            const command = bashCommandForToolCall(event.data.toolCallId);
+            if (command !== undefined)
+                rememberBashCommand(event.data.toolCallId, command);
+        }, TOOL_EXECUTION_START_EVENT_VERSION));
+        lessonRegistrations.push(api.lifecycle.registerObserve(TOOL_RESULT_EVENT_ID, (event) => {
+            const data = event.data;
+            if (data.toolName !== "bash" || !data.isError)
+                return;
+            const command = bashCommandsByToolCallId.get(data.toolCallId);
+            bashCommandsByToolCallId.delete(data.toolCallId);
+            if (command === undefined) {
+                // 配对失败 (start 未命中/映射溢出): 不写教训, 记一条有界 debug。
+                api.logger?.debug("memory bash-lesson capture skipped: no command paired with the failed toolCall", {
+                    toolCallId: data.toolCallId,
+                });
+                return;
+            }
+            const errorText = toolResultTextOf(data.message.content);
+            writeLesson(command, lessonExitCodeOf(errorText), errorText);
+        }, TOOL_RESULT_EVENT_VERSION));
+    }
+    const listTool = api.registerTool({
+        name: "memory_list",
+        label: "List memories",
+        description: "List this suite's durable memories (the explicit management surface for personal data)",
+        parameters: listSchema,
+        execute: async (first, second) => {
+            const input = memoryToolInput(first, second);
+            const rawLimit = input.limit;
+            const limit = rawLimit === undefined
+                ? DEFAULT_LIST_LIMIT
+                : (() => {
+                    if (typeof rawLimit !== "number" ||
+                        !Number.isSafeInteger(rawLimit) ||
+                        rawLimit < 1 ||
+                        rawLimit > 100) {
+                        throw new Error("limit must be an integer between 1 and 100");
+                    }
+                    return rawLimit;
+                })();
+            const { domain } = resolveDomain();
+            const page = listDomainMemories({ store }, { owner: BUILTIN_MEMORY_OWNER, domain });
+            return {
+                domain: page.domain,
+                entries: page.entries.slice(0, limit).map(entryToToolEntry),
+                total: page.entries.length,
+                preferenceCount: page.preferenceCount,
+                factCount: page.factCount,
+                filter: page.filter,
+            };
+        },
+    });
+    const forgetTool = api.registerTool({
+        name: "memory_forget",
+        label: "Forget memory",
+        description: "Physically delete one memory of this suite by memoryId (purge-gated, journalled, irreversible)",
+        parameters: forgetSchema,
+        execute: async (first, second) => {
+            const input = memoryToolInput(first, second);
+            assertNonEmptyString(input.memoryId, "memoryId");
+            const { domain, domainName, ledger } = resolveDomain();
+            const authorizationRef = {
+                mode: "user-immediate",
+                issuedAt: now(),
+                issuedBy: capabilityManifest.id,
+                confirmationRef: `memory_forget:${sessionId}:${input.memoryId}`,
+            };
+            const result = forgetDomainMemory({
+                store,
+                purgeGate,
+                purgeJournal,
+                // index 副本分派 (混合检索工程化): canonical 走下方原回调 (行为零
+                // 变化), 向量投影由 suite-memory 的 executePurgeBatch 按副本路由到这里。
+                purgeIndexReplica: vectorPurgeMemories,
+                now,
+            }, {
+                owner: BUILTIN_MEMORY_OWNER,
+                domain,
+                memoryId: input.memoryId,
+                authorizedBy: `${capabilityManifest.id}:memory_forget`,
+                authorizationRef,
+            }, (memoryIds) => {
+                const purged = new Set(memoryIds);
+                // Physical replica purge: rewrite the durable ledger without the
+                // purged atoms, then evict them from the in-memory store so the
+                // running process cannot recall them either (both idempotent for
+                // purge_eligible retries).
+                ledger.rewrite(ledger.atomsSnapshot().filter((atom) => !purged.has(atom.memoryId)));
+                for (const memoryId of memoryIds)
+                    store.evict(memoryId);
+            });
+            if (result.status === "completed") {
+                await api.publish({
+                    type: EVENT_TYPE,
+                    version: 1,
+                    correlationId: capabilityManifest.id,
+                    data: { action: "forgotten", memoryId: input.memoryId, domain: domainName, batchId: result.batchId },
+                });
+            }
+            return { status: result.status, memoryId: input.memoryId };
+        },
+    });
+    /** Canonical memoryId of the promoted copy of one preference (promotePreferenceToUserDefault suffix). */
+    const userDefaultMemoryId = (memoryId) => `${memoryId}-user-default`;
+    /**
+     * /promote (偏好晋升触发, B2): the production caller of
+     * {@link promotePreferenceToUserDefault}. Promotes one of THIS session's
+     * preferences to the user-default scope: the promoted canonical atom is
+     * appended to the session domain's durable ledger and committed to the
+     * store, so every suite's preference-card read (which applies the suite
+     * read boundary across all of the owner's ledgers) sees it from now on.
+     * The original atom is never rewritten. Errors (unknown id, non-preference,
+     * already promoted) surface as error results, never as thrown failures —
+     * a slash command must not crash the host.
+     */
+    const promoteCommand = api.registerCommand({
+        name: "promote",
+        description: "Promote a memory preference to the user-default scope (visible in every suite)",
+        argumentHint: "<memoryId>",
+        execute: async (args) => {
+            const memoryId = args.trim();
+            if (memoryId === "") {
+                return {
+                    status: "error",
+                    message: "Usage: /promote <memoryId> — run memory_list for this suite's memory ids",
+                };
+            }
+            const record = store.get(memoryId, { owner: BUILTIN_MEMORY_OWNER });
+            if (!record) {
+                return {
+                    status: "error",
+                    message: `No memory found with id ${memoryId}; run memory_list for this suite's memory ids`,
+                };
+            }
+            const atom = record.atom;
+            if (atom.memoryKind !== "preference" || atom.preference === undefined) {
+                return {
+                    status: "error",
+                    message: `${memoryId} is a fact, not a preference; only preferences can be promoted`,
+                };
+            }
+            if (store.get(userDefaultMemoryId(memoryId), { owner: BUILTIN_MEMORY_OWNER }) !== undefined) {
+                return {
+                    status: "error",
+                    message: `Preference ${memoryId} is already promoted to the user-default scope`,
+                };
+            }
+            try {
+                const promoted = promotePreferenceToUserDefault({
+                    atom,
+                    authorizedBy: "user:/promote",
+                    confirmedAt: new Date(now()).toISOString(),
+                });
+                const { domainName, ledger } = resolveDomain();
+                ledger.append(promoted);
+                store.commit(promoted);
+                // 向量投影埋点: 与 memory_write 同一异步旁路 (失败不阻塞命令返回)。
+                vectorUpsertAtom(promoted);
+                return {
+                    status: "success",
+                    message: `Promoted "${unwrapEgressStatement(statementOf(promoted.payload))}" to the user-default scope; it is now visible in every suite`,
+                    data: { memoryId: promoted.memoryId, sourceMemoryId: memoryId, domain: domainName },
+                };
+            }
+            catch (error) {
+                return { status: "error", message: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    });
+    // memory.scheduler@1 plugin capability (宪法 §3 显式声明面): a declarative
+    // marker only — the scheduler enforcement itself (per-instance single
+    // lease, acquired above) stays carried by the host builtin implementation.
+    // The declaration anchors "this suite's memory scheduling is provided by
+    // this plugin" so the code Profile assembly check (requiresMemoryScheduler)
+    // and third-party replacement detection have an explicit surface:
+    // list()-visible, a same-id double provide fails explicitly (no override
+    // priority), and after dispose a replacement provider can take the id.
+    const schedulerCapability = api.capabilities.provide({ id: "memory.scheduler", version: 1, kind: "service" }, () => Object.freeze({
+        id: "memory.scheduler",
+        version: 1,
+        owner: "agent-forge.builtin.memory",
+        leaseScope: "per-agent-instance",
+    }));
+    const registrations = [
+        writeTool,
+        recallTool,
+        listTool,
+        forgetTool,
+        promoteCommand,
+        schedulerCapability,
+        autoRecallHook,
+        preferenceCardHook,
+        ...lessonRegistrations,
+    ];
+    return {
+        registrations,
+        settleVectorWork: async () => {
+            await vectorQueue;
+        },
+        vectorState: () => vectorState,
+        // 触发惰性 enabling (已注入组件时已就绪) 并等待其落定: ready 或结构化失败。
+        enablingOutcome: async () => {
+            if (vectorState === "enabling")
+                void vectorEnsure();
+            await enablingSettledPromise;
+            return enablingFailure ?? "ready";
+        },
+    };
+}
+//# sourceMappingURL=capability.js.map