@ai-agent-forge/plugin-memory 0.85.0

package/dist/memory/embedding-provider.js

@@ -0,0 +1,164 @@
+/**
+ * Memory embedding providers for hybrid retrieval (混合检索 · 向量侧).
+ *
+ * POC-verified (2026-09, 100k corpus): high tier (Xenova/bge-m3, 1024d) and
+ * low tier (Xenova/bge-small-zh-v1.5, 512d) inference is deterministic
+ * bit-exact across runs; high-tier drift queries reach re@10 100% after
+ * reranking, low tier 83%. Tier presets are caller configuration — this module
+ * only exposes a modelId-parameterized interface (宪法: 不绑死单一 provider).
+ *
+ * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at
+ * first embed (惯例参考 packages/agent-forge/src/utils/photon.ts); type
+ * positions use type-only imports. The deterministic mock provider keeps tests
+ * offline (门禁: deterministic mock AI; 真实模型不进 CI).
+ */
+/**
+ * Batch embedding provider. Implementations must be deterministic for
+ * identical input and must not silently degrade: any failure propagates.
+ */
+import { join } from "node:path";
+import { importHostOrBareModule } from "./host-module-import.js";
+import { purgeZeroByteCacheArtifacts } from "./model-cache-hygiene.js";
+const DEFAULT_TRANSFORMERS_MODEL_ID = "Xenova/bge-m3";
+const DEFAULT_TRANSFORMERS_DIMENSIONS = 1024;
+const DEFAULT_TRANSFORMERS_BATCH_SIZE = 16;
+const DEFAULT_REMOTE_HOST = "https://huggingface.co";
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let offset = 0; offset < input.length; offset += 1) {
+        hash ^= input.charCodeAt(offset);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function embedDeterministicMock(text, dimensions) {
+    const values = new Array(dimensions).fill(0);
+    const tokens = text.toLowerCase().split(/[^\p{L}\p{N}]+/u);
+    for (const token of tokens) {
+        if (token.length === 0) {
+            continue;
+        }
+        // 多轮混淆累加: 每个 token 经 FNV-1a 后再派生 3 个维度沉点,
+        // 放大不同文本间的向量差异; 全程无随机、无时钟。
+        let mixed = fnv1a32(token);
+        for (let round = 0; round < 3; round += 1) {
+            mixed = Math.imul(mixed ^ 0x9e3779b9, 0x85ebca6b) >>> 0;
+            values[mixed % dimensions] += 1;
+        }
+    }
+    let sumSquares = 0;
+    for (const value of values) {
+        sumSquares += value * value;
+    }
+    if (sumSquares === 0) {
+        // 空文本/全标点: 确定性零向量; L2 范数为 0, 不归一化 (避免除零 NaN)。
+        return values;
+    }
+    const norm = Math.sqrt(sumSquares);
+    return values.map((value) => value / norm);
+}
+/**
+ * Deterministic mock embedding provider for offline tests: tokenizes by
+ * `[^\p{L}\p{N}]+`, hashes each token with FNV-1a plus multi-round mixing into
+ * dimension indices, then L2-normalizes. Same text → same vector, no random,
+ * no clock. POC 已用真实模型验证 bit-exact; mock 只承担确定性测试门禁。
+ */
+export function createDeterministicMockEmbeddingProvider(options) {
+    const dimensions = options?.dimensions ?? 64;
+    return {
+        modelId: "mock-embedding@1",
+        dimensions,
+        embed: async (texts) => texts.map((text) => embedDeterministicMock(text, dimensions)),
+    };
+}
+const createDefaultTransformersLoadImpl = (moduleEntryPath) => {
+    return async (modelId, cacheDir, remoteHost) => {
+        const transformers = await importHostOrBareModule(moduleEntryPath ?? "@huggingface/transformers");
+        transformers.env.cacheDir = cacheDir;
+        transformers.env.remoteHost = remoteHost;
+        const extractor = await transformers.pipeline("feature-extraction", modelId, { dtype: "q8" });
+        return {
+            extract: async (texts) => {
+                const output = await extractor(texts, { pooling: "cls", normalize: true });
+                return { toList: () => output.tolist() };
+            },
+        };
+    };
+};
+/**
+ * Transformers.js-backed embedding provider (POC 档位: 高档默认
+ * Xenova/bge-m3/1024d; 低档由调用方传 modelId "Xenova/bge-small-zh-v1.5" +
+ * dimensions 512)。
+ *
+ * 镜像序列: 首次 embed 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传
+ * ["https://huggingface.co", "https://hf-mirror.com"]); 某 host 加载抛错则
+ * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次
+ * (并发 embed 共享同一 in-flight promise); 加载失败不缓存, 下次 embed 重新
+ * 走完整序列, 失败原因原样保留, 不静默降级。
+ *
+ * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名
+ * (modelId, cacheDir, remoteHost) => backend。
+ */
+export function createTransformersEmbeddingProvider(options) {
+    const modelId = options.modelId ?? DEFAULT_TRANSFORMERS_MODEL_ID;
+    const dimensions = options.dimensions ?? DEFAULT_TRANSFORMERS_DIMENSIONS;
+    const batchSize = options.batchSize ?? DEFAULT_TRANSFORMERS_BATCH_SIZE;
+    const cacheDir = options.cacheDir;
+    const remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];
+    const load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);
+    let backendPromise = null;
+    const loadBackend = () => {
+        const existing = backendPromise;
+        if (existing) {
+            return existing;
+        }
+        const attempt = (async () => {
+            let lastError;
+            for (const remoteHost of remoteHosts) {
+                try {
+                    return await load(modelId, cacheDir, remoteHost);
+                }
+                catch (error) {
+                    lastError = error;
+                    // 镜像轮换前清 0 字节残骸: 失败下载留下的空文件会被 transformers
+                    // 当作缓存命中, 毒化下一个 host 的重试 (model-cache-hygiene)。
+                    purgeZeroByteCacheArtifacts(join(cacheDir, modelId));
+                }
+            }
+            if (lastError === undefined)
+                throw new Error(`no remote hosts configured for model ${modelId}`);
+            throw lastError;
+        })();
+        backendPromise = attempt;
+        attempt.catch(() => {
+            // 失败不缓存: 下次 embed 重新走镜像序列 (显式失败, 不静默降级)。
+            if (backendPromise === attempt) {
+                backendPromise = null;
+            }
+        });
+        return attempt;
+    };
+    return {
+        modelId,
+        dimensions,
+        embed: async (texts) => {
+            if (texts.length === 0) {
+                return [];
+            }
+            const backend = await loadBackend();
+            const vectors = [];
+            for (let offset = 0; offset < texts.length; offset += batchSize) {
+                const batchTexts = texts.slice(offset, offset + batchSize);
+                const rows = (await backend.extract(batchTexts)).toList();
+                for (const row of rows) {
+                    if (row.length !== dimensions) {
+                        throw new Error(`embedding dimension mismatch: model ${modelId} returned ${row.length} dims, provider declares ${dimensions}`);
+                    }
+                    vectors.push(row);
+                }
+            }
+            return vectors;
+        },
+    };
+}
+//# sourceMappingURL=embedding-provider.js.map

package/dist/memory/embedding-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.js","sourceRoot":"","sources":["../../src/memory/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AA6BvE,MAAM,6BAA6B,GAAG,eAAe,CAAC;AACtD,MAAM,+BAA+B,GAAG,IAAI,CAAC;AAC7C,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAC3C,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAErD,SAAS,OAAO,CAAC,KAAa,EAAU;IACvC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC;QACzD,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AAAA,CAClB;AAED,SAAS,sBAAsB,CAAC,IAAY,EAAE,UAAkB,EAAY;IAC3E,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC3D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,SAAS;QACV,CAAC;QACD,8EAA0C;QAC1C,uEAA2B;QAC3B,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC3C,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YACxD,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,UAAU,IAAI,KAAK,GAAG,KAAK,CAAC;IAC7B,CAAC;IACD,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACtB,8FAA8C;QAC9C,OAAO,MAAM,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;AAAA,CAC3C;AAED;;;;;GAKG;AACH,MAAM,UAAU,wCAAwC,CAAC,OAExD,EAA6B;IAC7B,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC;IAC7C,OAAO;QACN,OAAO,EAAE,kBAAkB;QAC3B,UAAU;QACV,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;KACrF,CAAC;AAAA,CACF;AAED,MAAM,iCAAiC,GAAG,CAAC,eAAwB,EAAiC,EAAE,CAAC;IACtG,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAG,MAAM,sBAAsB,CAChD,eAAe,IAAI,2BAA2B,CAC9C,CAAC;QACF,YAAY,CAAC,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACrC,YAAY,CAAC,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC;QACzC,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9F,OAAO;YACN,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3E,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAgB,EAAE,CAAC;YAAA,CACvD;SACD,CAAC;IAAA,CACF,CAAC;AAAA,CACF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mCAAmC,CAAC,OASnD,EAA6B;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,6BAA6B,CAAC;IACjE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,+BAA+B,CAAC;IACzE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,+BAA+B,CAAC;IACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,iCAAiC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5F,IAAI,cAAc,GAAmD,IAAI,CAAC;IAC1E,MAAM,WAAW,GAAG,GAA4C,EAAE,CAAC;QAClE,MAAM,QAAQ,GAAG,cAAc,CAAC;QAChC,IAAI,QAAQ,EAAE,CAAC;YACd,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC5B,IAAI,SAAkB,CAAC;YACvB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACtC,IAAI,CAAC;oBACJ,OAAO,MAAM,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;gBAClD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,SAAS,GAAG,KAAK,CAAC;oBAClB,uFAA2C;oBAC3C,8EAAgD;oBAChD,2BAA2B,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;gBACtD,CAAC;YACF,CAAC;YACD,IAAI,SAAS,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,OAAO,EAAE,CAAC,CAAC;YAChG,MAAM,SAAS,CAAC;QAAA,CAChB,CAAC,EAAE,CAAC;QACL,cAAc,GAAG,OAAO,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACnB,yFAAyC;YACzC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;gBAChC,cAAc,GAAG,IAAI,CAAC;YACvB,CAAC;QAAA,CACD,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IAAA,CACf,CAAC;IAEF,OAAO;QACN,OAAO;QACP,UAAU;QACV,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;YACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO,EAAE,CAAC;YACX,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,WAAW,EAAE,CAAC;YACpC,MAAM,OAAO,GAAe,EAAE,CAAC;YAC/B,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,SAAS,EAAE,CAAC;gBACjE,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;gBAC3D,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;gBAC1D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACxB,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;wBAC/B,MAAM,IAAI,KAAK,CACd,uCAAuC,OAAO,aAAa,GAAG,CAAC,MAAM,4BAA4B,UAAU,EAAE,CAC7G,CAAC;oBACH,CAAC;oBACD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACnB,CAAC;YACF,CAAC;YACD,OAAO,OAAO,CAAC;QAAA,CACf;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Memory embedding providers for hybrid retrieval (混合检索 · 向量侧).\n *\n * POC-verified (2026-09, 100k corpus): high tier (Xenova/bge-m3, 1024d) and\n * low tier (Xenova/bge-small-zh-v1.5, 512d) inference is deterministic\n * bit-exact across runs; high-tier drift queries reach re@10 100% after\n * reranking, low tier 83%. Tier presets are caller configuration — this module\n * only exposes a modelId-parameterized interface (宪法: 不绑死单一 provider).\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first embed (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. The deterministic mock provider keeps tests\n * offline (门禁: deterministic mock AI; 真实模型不进 CI).\n */\n\n/**\n * Batch embedding provider. Implementations must be deterministic for\n * identical input and must not silently degrade: any failure propagates.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryEmbeddingProviderV1 {\n\treadonly modelId: string;\n\treadonly dimensions: number;\n\t/**\n\t * Batch embed. Vectors are L2-normalized float arrays. Deterministic for\n\t * identical input. Plain text mapping — no instruction prefix is added\n\t * here; query-side instructions for bge-small-zh family are the caller's\n\t * responsibility (低档 bge-small-zh 系查询侧指令由调用方负责添加).\n\t */\n\tembed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js feature-extraction\n * pipeline, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersEmbeddingBackendV1 {\n\t/** Extract features for a batch of texts; one vector per input, input order. */\n\textract: (texts: string[]) => Promise<{ toList: () => number[][] }>;\n}\n\nexport type TransformersEmbeddingLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersEmbeddingBackendV1>;\n\nconst DEFAULT_TRANSFORMERS_MODEL_ID = \"Xenova/bge-m3\";\nconst DEFAULT_TRANSFORMERS_DIMENSIONS = 1024;\nconst DEFAULT_TRANSFORMERS_BATCH_SIZE = 16;\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\nfunction fnv1a32(input: string): number {\n\tlet hash = 0x811c9dc5;\n\tfor (let offset = 0; offset < input.length; offset += 1) {\n\t\thash ^= input.charCodeAt(offset);\n\t\thash = Math.imul(hash, 0x01000193);\n\t}\n\treturn hash >>> 0;\n}\n\nfunction embedDeterministicMock(text: string, dimensions: number): number[] {\n\tconst values = new Array<number>(dimensions).fill(0);\n\tconst tokens = text.toLowerCase().split(/[^\\p{L}\\p{N}]+/u);\n\tfor (const token of tokens) {\n\t\tif (token.length === 0) {\n\t\t\tcontinue;\n\t\t}\n\t\t// 多轮混淆累加: 每个 token 经 FNV-1a 后再派生 3 个维度沉点,\n\t\t// 放大不同文本间的向量差异; 全程无随机、无时钟。\n\t\tlet mixed = fnv1a32(token);\n\t\tfor (let round = 0; round < 3; round += 1) {\n\t\t\tmixed = Math.imul(mixed ^ 0x9e3779b9, 0x85ebca6b) >>> 0;\n\t\t\tvalues[mixed % dimensions] += 1;\n\t\t}\n\t}\n\tlet sumSquares = 0;\n\tfor (const value of values) {\n\t\tsumSquares += value * value;\n\t}\n\tif (sumSquares === 0) {\n\t\t// 空文本/全标点: 确定性零向量; L2 范数为 0, 不归一化 (避免除零 NaN)。\n\t\treturn values;\n\t}\n\tconst norm = Math.sqrt(sumSquares);\n\treturn values.map((value) => value / norm);\n}\n\n/**\n * Deterministic mock embedding provider for offline tests: tokenizes by\n * `[^\\p{L}\\p{N}]+`, hashes each token with FNV-1a plus multi-round mixing into\n * dimension indices, then L2-normalizes. Same text → same vector, no random,\n * no clock. POC 已用真实模型验证 bit-exact; mock 只承担确定性测试门禁。\n */\nexport function createDeterministicMockEmbeddingProvider(options?: {\n\treadonly dimensions?: number;\n}): MemoryEmbeddingProviderV1 {\n\tconst dimensions = options?.dimensions ?? 64;\n\treturn {\n\t\tmodelId: \"mock-embedding@1\",\n\t\tdimensions,\n\t\tembed: async (texts) => texts.map((text) => embedDeterministicMock(text, dimensions)),\n\t};\n}\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersEmbeddingLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst extractor = await transformers.pipeline(\"feature-extraction\", modelId, { dtype: \"q8\" });\n\t\treturn {\n\t\t\textract: async (texts) => {\n\t\t\t\tconst output = await extractor(texts, { pooling: \"cls\", normalize: true });\n\t\t\t\treturn { toList: () => output.tolist() as number[][] };\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed embedding provider (POC 档位: 高档默认\n * Xenova/bge-m3/1024d; 低档由调用方传 modelId \"Xenova/bge-small-zh-v1.5\" +\n * dimensions 512)。\n *\n * 镜像序列: 首次 embed 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 embed 共享同一 in-flight promise); 加载失败不缓存, 下次 embed 重新\n * 走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersEmbeddingProvider(options: {\n\treadonly modelId?: string;\n\treadonly dimensions?: number;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly batchSize?: number;\n\treadonly loadImpl?: TransformersEmbeddingLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryEmbeddingProviderV1 {\n\tconst modelId = options.modelId ?? DEFAULT_TRANSFORMERS_MODEL_ID;\n\tconst dimensions = options.dimensions ?? DEFAULT_TRANSFORMERS_DIMENSIONS;\n\tconst batchSize = options.batchSize ?? DEFAULT_TRANSFORMERS_BATCH_SIZE;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersEmbeddingBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersEmbeddingBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸: 失败下载留下的空文件会被 transformers\n\t\t\t\t\t// 当作缓存命中, 毒化下一个 host 的重试 (model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow lastError;\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 embed 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\tdimensions,\n\t\tembed: async (texts) => {\n\t\t\tif (texts.length === 0) {\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\tconst vectors: number[][] = [];\n\t\t\tfor (let offset = 0; offset < texts.length; offset += batchSize) {\n\t\t\t\tconst batchTexts = texts.slice(offset, offset + batchSize);\n\t\t\t\tconst rows = (await backend.extract(batchTexts)).toList();\n\t\t\t\tfor (const row of rows) {\n\t\t\t\t\tif (row.length !== dimensions) {\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`embedding dimension mismatch: model ${modelId} returned ${row.length} dims, provider declares ${dimensions}`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tvectors.push(row);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn vectors;\n\t\t},\n\t};\n}\n"]}

package/dist/memory/embedding-reranker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).
+ *
+ * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with
+ * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),
+ * inference deterministic across runs. Reranking is an independently
+ * disable-able component (宪法: 独立可禁用); tiers are caller configuration.
+ *
+ * Model note: default "Xenova/bge-reranker-base" is the only officially
+ * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,
+ * 512-token context — the caller owns the write-side length contract
+ * (statement ≤700 chars); overlong inputs are gracefully truncated by the
+ * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a
+ * modelId swap away, but it currently has no official transformers.js
+ * conversion.
+ *
+ * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at
+ * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type
+ * positions use type-only imports. Any failure propagates — 不静默降级.
+ */
+export interface MemoryRerankerV1 {
+    readonly modelId: string;
+    /** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */
+    rerank(query: string, docs: readonly string[]): Promise<readonly number[]>;
+}
+/**
+ * Minimal structural seam around a transformers.js sequence-classification
+ * pair, so tests can inject a fake without touching the real loader.
+ */
+export interface TransformersRerankerBackendV1 {
+    /** Score docs against the query; result[i] corresponds to docs[i]. */
+    score: (query: string, docs: string[]) => Promise<number[]>;
+}
+export type TransformersRerankerLoadImpl = (modelId: string, cacheDir: string, remoteHost: string) => Promise<TransformersRerankerBackendV1>;
+/**
+ * Transformers.js-backed cross-encoder reranker (两档共用默认
+ * Xenova/bge-reranker-base, 见文件头模型说明)。
+ *
+ * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传
+ * ["https://huggingface.co", "https://hf-mirror.com"]); 某 host 加载抛错则
+ * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次
+ * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank
+ * 重新走完整序列, 失败原因原样保留, 不静默降级。
+ *
+ * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名
+ * (modelId, cacheDir, remoteHost) => backend。
+ */
+export declare function createTransformersReranker(options: {
+    readonly modelId?: string;
+    readonly cacheDir: string;
+    readonly remoteHosts?: readonly string[];
+    readonly loadImpl?: TransformersRerankerLoadImpl;
+    /** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */
+    readonly moduleEntryPath?: string;
+}): MemoryRerankerV1;
+//# sourceMappingURL=embedding-reranker.d.ts.map

package/dist/memory/embedding-reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-reranker.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC7C,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,MAAM,MAAM,4BAA4B,GAAG,CAC1C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAsC5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,iGAAiG;IACjG,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,gBAAgB,CA+CnB","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow lastError;\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/embedding-reranker.js

@@ -0,0 +1,109 @@
+/**
+ * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).
+ *
+ * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with
+ * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),
+ * inference deterministic across runs. Reranking is an independently
+ * disable-able component (宪法: 独立可禁用); tiers are caller configuration.
+ *
+ * Model note: default "Xenova/bge-reranker-base" is the only officially
+ * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,
+ * 512-token context — the caller owns the write-side length contract
+ * (statement ≤700 chars); overlong inputs are gracefully truncated by the
+ * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a
+ * modelId swap away, but it currently has no official transformers.js
+ * conversion.
+ *
+ * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at
+ * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type
+ * positions use type-only imports. Any failure propagates — 不静默降级.
+ */
+/**
+ * Cross-encoder reranker. Higher score = more relevant; raw logits are only
+ * order-preserving, not calibrated probabilities.
+ */
+import { join } from "node:path";
+import { importHostOrBareModule } from "./host-module-import.js";
+import { purgeZeroByteCacheArtifacts } from "./model-cache-hygiene.js";
+const DEFAULT_RERANKER_MODEL_ID = "Xenova/bge-reranker-base";
+const DEFAULT_REMOTE_HOST = "https://huggingface.co";
+const createDefaultTransformersLoadImpl = (moduleEntryPath) => {
+    return async (modelId, cacheDir, remoteHost) => {
+        const transformers = await importHostOrBareModule(moduleEntryPath ?? "@huggingface/transformers");
+        transformers.env.cacheDir = cacheDir;
+        transformers.env.remoteHost = remoteHost;
+        const tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId));
+        const model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {
+            dtype: "q8",
+        }));
+        return {
+            score: async (query, docs) => {
+                const inputs = tokenizer(docs.map(() => query), { text_pair: docs, padding: true, truncation: true });
+                const output = await model(inputs);
+                return Array.from(output.logits.data);
+            },
+        };
+    };
+};
+/**
+ * Transformers.js-backed cross-encoder reranker (两档共用默认
+ * Xenova/bge-reranker-base, 见文件头模型说明)。
+ *
+ * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传
+ * ["https://huggingface.co", "https://hf-mirror.com"]); 某 host 加载抛错则
+ * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次
+ * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank
+ * 重新走完整序列, 失败原因原样保留, 不静默降级。
+ *
+ * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名
+ * (modelId, cacheDir, remoteHost) => backend。
+ */
+export function createTransformersReranker(options) {
+    const modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;
+    const cacheDir = options.cacheDir;
+    const remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];
+    const load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);
+    let backendPromise = null;
+    const loadBackend = () => {
+        const existing = backendPromise;
+        if (existing) {
+            return existing;
+        }
+        const attempt = (async () => {
+            let lastError;
+            for (const remoteHost of remoteHosts) {
+                try {
+                    return await load(modelId, cacheDir, remoteHost);
+                }
+                catch (error) {
+                    lastError = error;
+                    // 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。
+                    purgeZeroByteCacheArtifacts(join(cacheDir, modelId));
+                }
+            }
+            if (lastError === undefined)
+                throw new Error(`no remote hosts configured for model ${modelId}`);
+            throw lastError;
+        })();
+        backendPromise = attempt;
+        attempt.catch(() => {
+            // 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。
+            if (backendPromise === attempt) {
+                backendPromise = null;
+            }
+        });
+        return attempt;
+    };
+    return {
+        modelId,
+        rerank: async (query, docs) => {
+            if (docs.length === 0) {
+                // 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。
+                return [];
+            }
+            const backend = await loadBackend();
+            return backend.score(query, [...docs]);
+        },
+    };
+}
+//# sourceMappingURL=embedding-reranker.js.map

package/dist/memory/embedding-reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-reranker.js","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow lastError;\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/foundation.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Memory Foundation — canonical atom, identity, and immutable snapshots (1C.1a).
+ *
+ * A canonical atom is the immutable committed fact. Derived state (attention,
+ * effective status, purgeAt) is NOT part of the atom; it is rebuilt from
+ * lifecycle events (1C.1b/1C.2). Everything returned to hosts and plugins is a
+ * detached, deep-frozen snapshot: mutating the input after `buildMemoryAtomV1`
+ * never changes the stored atom.
+ *
+ * Field semantics follow `docs/design/记忆系统设计.md` §4 (记录模型), which is the
+ * authoritative source for memory fields.
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+/** Source of one memory: where the fact came from, optionally pinned by revision/digest. */
+export interface MemorySourceRefV1 {
+    readonly kind: "session" | "entry" | "artifact" | "tool" | "state";
+    readonly id: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+/** Namespace-scoped search facet. Facets are atom facts, never derived. */
+export interface MemoryFacetV1 {
+    readonly namespace: string;
+    readonly schemaVersion: number;
+    readonly key: string;
+    readonly value: string;
+}
+/** Typed relation between atoms. Weights/validity belong to projections, not here. */
+export interface MemoryRelationV1 {
+    readonly relationId: string;
+    readonly namespace: string;
+    readonly schemaVersion: number;
+    readonly kind: string;
+    readonly targetMemoryId?: string;
+    readonly targetRef?: MemorySourceRefV1;
+    readonly confidence?: number;
+    readonly relationRevision: string;
+}
+export interface MemoryTimeRangeV1 {
+    readonly from?: string;
+    readonly to?: string;
+}
+/** Applicability narrowing; empty means "applies without narrowing". */
+export interface MemoryApplicabilityV1 {
+    readonly scenes?: readonly string[];
+    readonly projects?: readonly string[];
+    readonly tasks?: readonly string[];
+    readonly timeRange?: MemoryTimeRangeV1;
+    readonly exceptions?: readonly string[];
+}
+/** Preference envelope: the generic schema frozen for 1C; policy semantics come later. */
+export interface MemoryPreferenceEnvelopeV1 {
+    readonly subject: "user" | "project" | "task" | "environment";
+    readonly key: string;
+    readonly preferredValue: JsonValue;
+    readonly alternatives?: readonly JsonValue[];
+    readonly scope: {
+        readonly level: "task" | "project" | "scene" | "timeRange" | "profile-private" | "user-default";
+        readonly scenes?: readonly string[];
+        readonly projects?: readonly string[];
+        readonly tasks?: readonly string[];
+        readonly timeRange?: MemoryTimeRangeV1;
+        readonly exceptions?: readonly string[];
+    };
+    readonly evidence: {
+        readonly class: "explicit" | "repeated_behavior" | "inferred";
+        readonly sourceRefs: readonly MemorySourceRefV1[];
+        readonly confidence: number;
+    };
+    readonly applicabilityConfidence: number;
+    readonly confirmedAt?: string;
+}
+/** Provenance for synthesis/compaction memories derived from other atoms. */
+export interface MemoryProvenanceV1 {
+    readonly sourceMemoryIds: readonly string[];
+    readonly purgeGroupId: string;
+    readonly containsSourceContent: boolean;
+}
+export type MemoryScopeV1 = "session" | "cycle" | "long-term";
+export type MemoryKindV1 = "observation" | "preference" | "fact" | "decision" | "constraint" | "inference" | "synthesis";
+export type MemoryEvidenceClassV1 = "explicit" | "repeated_behavior" | "tool_or_test" | "derived";
+/** The immutable canonical atom. Once committed, no field may change in place. */
+export interface MemoryAtomV1<TPayload = JsonValue> {
+    readonly memoryId: string;
+    readonly contractVersion: string;
+    readonly schemaVersion: number;
+    readonly scope: MemoryScopeV1;
+    readonly retentionMode: string;
+    readonly owner: string;
+    readonly profileId: string;
+    readonly shareGroupId?: string;
+    /**
+     * Suite (方案) this atom belongs to (方案系统设计 §6.1/§11, M5). Absent
+     * (or protocol-level `null` on the wire, normalized to absent here) marks a
+     * legacy pre-M5 atom: such atoms are fail-safe INVISIBLE to every
+     * suite-scoped read and only readable through suite-unscoped queries. The
+     * one cross-suite exception is an explicitly promoted user-default
+     * preference (see {@link memorySuiteVisibility}).
+     */
+    readonly suiteId?: string;
+    readonly retentionPolicyVersion: string;
+    readonly memoryKind: MemoryKindV1;
+    readonly payload: TPayload;
+    readonly preference?: MemoryPreferenceEnvelopeV1;
+    readonly occurredAt: string;
+    readonly recordedAt: string;
+    readonly sourceRefs: readonly MemorySourceRefV1[];
+    readonly observationId: string;
+    readonly sessionRefs: readonly string[];
+    readonly agentInstanceRefs: readonly string[];
+    readonly projectRefs: readonly string[];
+    readonly subjectRefs: readonly string[];
+    readonly facets: readonly MemoryFacetV1[];
+    readonly relations: readonly MemoryRelationV1[];
+    readonly provenance?: MemoryProvenanceV1;
+    readonly confidence: number;
+    readonly importance: number;
+    readonly applicability?: MemoryApplicabilityV1;
+    readonly evidenceClass: MemoryEvidenceClassV1;
+    readonly contentRevision: string;
+    readonly writeReason: string;
+}
+/**
+ * Validates a canonical memory atom and returns a detached, deep-frozen
+ * snapshot. Unknown fields, wrong enums, non-JSON payloads, preference-kind
+ * atoms without a preference envelope, and identity fields (memoryId,
+ * observationId, contentRevision, owner) that are not non-empty strings are
+ * rejected.
+ */
+export declare function validateMemoryAtomV1<TPayload = JsonValue>(value: unknown): MemoryAtomV1<TPayload>;
+/** Builds a detached, frozen canonical atom (validate + freeze). */
+export declare function buildMemoryAtomV1<TPayload = JsonValue>(atom: MemoryAtomV1<TPayload>): MemoryAtomV1<TPayload>;
+/** FNV-1a 64-bit digest over the stable JSON serialization of `value`. */
+export declare function memoryContentDigest(value: JsonValue): string;
+/** Idempotent submission identity: the same (owner, observationId) is one observation. */
+export declare function memoryObservationKey(owner: string, observationId: string): string;
+/** Why a record was excluded from a suite-scoped read (读取边界惰性可观测). */
+export type MemorySuiteVisibilityV1 = 
+/** The atom matches the queried suite, or is an explicitly promoted user-default preference. */
+"visible"
+/** Legacy (pre-M5) atom without a suiteId — fail-safe invisible to every suite. */
+ | "legacy"
+/** The atom belongs to a different suite. */
+ | "foreign-suite";
+/**
+ * Skipped-record counters attached to suite-scoped reads. The read boundary is
+ * lazy and observable (设计 §11 三段式): excluded atoms are counted, never
+ * silently dropped.
+ */
+export interface MemorySuiteFilterStatsV1 {
+    /** Legacy (suiteId-less) atoms skipped as invisible to any suite. */
+    readonly legacySkipped: number;
+    /** Atoms bound to a different suiteId that were skipped. */
+    readonly foreignSuiteSkipped: number;
+}
+/**
+ * Suite-scoped visibility of one atom (方案系统设计 §6.1/§11):
+ * - `atom.suiteId === suiteId` → visible;
+ * - an explicitly promoted user-default preference (scope.level
+ *   "user-default" WITH `confirmedAt` — the canonical explicit-confirmation
+ *   marker set only by the explicit promotion channel) ignores the suiteId
+ *   filter and is visible in every suite (§6.1 跨方案偏好);
+ * - absent suiteId (legacy/存量) → invisible to every suite (fail-safe
+ *   default), counted via {@link MemorySuiteFilterStatsV1};
+ * - any other suiteId → invisible.
+ */
+export declare function memorySuiteVisibility(atom: MemoryAtomV1, suiteId: string): MemorySuiteVisibilityV1;
+//# sourceMappingURL=foundation.d.ts.map