@ai-agent-forge/plugin-memory 0.85.0

package/dist/testing/memory-testkit.d.ts

@@ -0,0 +1,149 @@
+import type { CapabilityAPI, JsonValue } from "@agent-forge/plugin-sdk";
+import { type MemoryCandidateMachineV1 } from "../memory/candidates.ts";
+import { createMemoryCompactionSequencer } from "../memory/compaction-sequencer.ts";
+import { type MemoryContinuationIssuerV1 } from "../memory/continuation.ts";
+import { type MemoryCurationAgentV1 } from "../memory/curation.ts";
+import type { MemoryEmbeddingProviderV1 } from "../memory/embedding-provider.ts";
+import type { MemoryRerankerV1 } from "../memory/embedding-reranker.ts";
+import type { MemoryAtomV1, MemoryScopeV1 } from "../memory/foundation.ts";
+import { type MemoryLifecycleManagerV1, type MemoryLifecyclePolicyV1 } from "../memory/lifecycle.ts";
+import { type MemoryPurgeGateV1 } from "../memory/purge.ts";
+import { type MemoryPurgeJournalV1 } from "../memory/purge-journal.ts";
+import { type MemoryRecallAgentV1 } from "../memory/recall-agent.ts";
+import { createMemoryRecallIndex, type MemoryRecallPageV1, type MemoryRecallQueryV1 } from "../memory/recall-index.ts";
+import { type MemorySchedulerV1 } from "../memory/scheduler.ts";
+import { type MemoryStoreV1, type RetentionModeRegistryV1 } from "../memory/store.ts";
+import type { MemoryVectorIndexV1 } from "../memory/vector-index.ts";
+export interface MemoryTestKitOptions {
+    readonly now?: () => number;
+    readonly retentionRegistry?: RetentionModeRegistryV1;
+    readonly lifecyclePolicy?: MemoryLifecyclePolicyV1;
+}
+export interface MemoryTestKitAtomSeed {
+    readonly owner?: string;
+    readonly scope?: MemoryScopeV1;
+    readonly retentionMode?: string;
+    readonly memoryId?: string;
+    readonly observationId?: string;
+    readonly project?: string;
+    readonly task?: string;
+    readonly scene?: string;
+    readonly occurredAt: string;
+    readonly payload?: JsonValue;
+}
+export interface MemoryTestKit {
+    readonly store: MemoryStoreV1;
+    readonly machine: MemoryCandidateMachineV1;
+    readonly sequencer: ReturnType<typeof createMemoryCompactionSequencer>;
+    readonly index: ReturnType<typeof createMemoryRecallIndex>;
+    readonly lifecycle: MemoryLifecycleManagerV1;
+    readonly scheduler: MemorySchedulerV1;
+    readonly curation: MemoryCurationAgentV1;
+    readonly continuation: MemoryContinuationIssuerV1;
+    readonly purgeGate: MemoryPurgeGateV1;
+    readonly purgeJournal: MemoryPurgeJournalV1;
+    readonly recallAgent: MemoryRecallAgentV1;
+    /** Builds a validated deterministic atom from a seed. */
+    makeAtom(seed: MemoryTestKitAtomSeed): MemoryAtomV1;
+    /** Convenience: curation-commit an atom and return its memoryId. */
+    commit(atom: MemoryAtomV1): string;
+    query(query: MemoryRecallQueryV1): MemoryRecallPageV1;
+}
+export declare function createMemoryTestKit(options?: MemoryTestKitOptions): MemoryTestKit;
+/** Repeats `run` up to `times` and requires every result to deep-equal the first. */
+export declare function repeatMemoryTestKit<T>(times: number, run: () => Promise<T>): Promise<{
+    readonly baseline: T;
+    readonly repeats: number;
+}>;
+/**
+ * In-memory fake of the LanceDB vector index (memory/vector-index.ts 同契约):
+ * KNN 平扫平方 L2 (score = 1/(1+距离), 与真组件同口径), FTS 按词元包含匹配
+ * (score = 1/(60+rank+1), 与真组件同口径)。确定性: 排序并列按插入序打破。
+ */
+export declare function createInMemoryMemoryVectorIndex(options: {
+    readonly dimensions: number;
+}): MemoryVectorIndexV1;
+/**
+ * Deterministic mock vector components for the capability's vector-channel
+ * injection seam: the FNV token-hash mock embedder plus a scripted or
+ * lexical-overlap reranker over an in-memory fake index. No network, no real
+ * models, fully deterministic.
+ */
+export interface MockMemoryVectorComponentsOptions {
+    readonly dimensions?: number;
+    /** Explicit rerank scoring; default = deterministic lexical-overlap reranker. */
+    readonly rerank?: (query: string, docs: readonly string[]) => readonly number[];
+    /** true → no reranker at all (精排不可用路径: 跳过精排, RRF 序)。 */
+    readonly rerankerUnavailable?: boolean;
+}
+export declare function createMockMemoryVectorComponents(options?: MockMemoryVectorComponentsOptions): {
+    readonly embedProvider: MemoryEmbeddingProviderV1;
+    readonly reranker: MemoryRerankerV1 | undefined;
+    readonly vectorIndex: MemoryVectorIndexV1;
+};
+/** Deterministic reranker mock: score = count of query tokens present in the doc. */
+export declare function createLexicalMockReranker(): MemoryRerankerV1;
+/**
+ * 显式向量表 mock 组件 (2.4d6 S3 语义合并测试用): 每条文本的向量由测试直接
+ * 指定 (绕过 FNV token hash — 合并阈值的余弦判定需要可控向量), 搭配
+ * in-memory fake index 与缺省词元重排器, 零网络零真实模型 (架构宪法测试
+ * 门禁)。dimensions 取自向量表首个声明向量; 未声明向量的文本显式抛错 —
+ * 测试必须登记每一条会被 embed 的内容与查询 (含召回 query), 保证确定性。
+ */
+export declare function createScriptedMockVectorComponents(vectors: {
+    readonly [text: string]: readonly number[];
+}): {
+    readonly embedProvider: MemoryEmbeddingProviderV1;
+    readonly reranker: MemoryRerankerV1 | undefined;
+    readonly vectorIndex: MemoryVectorIndexV1;
+};
+/** A loop hook captured from a capability registration (测试侧驱动用). */
+export interface MemoryCapabilityLoopHookCaptureV1 {
+    readonly position: string;
+    readonly handler: (messages: unknown) => Promise<unknown>;
+}
+/**
+ * Minimal capture api for driving `createCapability` / its vector-component
+ * test variant at the factory level (mirrors the runtime tool/command surface:
+ * registerTool, registerCommand, publish, logger, capabilities, session,
+ * lifecycle, registerLoopHook).
+ */
+export interface MemoryCapabilityTestApiV1 {
+    readonly api: CapabilityAPI;
+    /** Registered tool by name (undefined when the capability did not register it). */
+    tool(name: string): {
+        readonly execute: (first: unknown, second?: unknown) => Promise<unknown>;
+    } | undefined;
+    /** Registered command by name (undefined when the capability did not register it). */
+    command(name: string): {
+        readonly execute: (args: string) => Promise<unknown>;
+    } | undefined;
+    /** logger.warn messages captured for degraded-channel assertions. */
+    readonly warnings: readonly string[];
+    /** logger.info messages captured for off/enabling declaration assertions. */
+    readonly infos: readonly string[];
+    /** logger.debug messages captured for bounded-skip assertions (§2.2 配对失败). */
+    readonly debugs: readonly string[];
+    /** Appends a suite binding entry; resolveSessionDomain reads the LAST one. */
+    bindSuite(suiteId: string): void;
+    /**
+     * Appends one message entry (assistant/user/toolResult shape is the test's
+     * responsibility) to the branch; returns the entry id.
+     */
+    appendMessageEntry(message: unknown): string;
+    /** The registered loop hook for a position (undefined when not registered). */
+    loopHook(position: string): MemoryCapabilityLoopHookCaptureV1 | undefined;
+    /**
+     * Dispatches a committed lifecycle event to every registered observer of
+     * id@version (test-side stand-in for the host lifecycle dispatcher).
+     */
+    dispatchLifecycleEvent(event: {
+        readonly id: string;
+        readonly version?: number;
+        readonly data: unknown;
+    }): Promise<void>;
+}
+export declare function createMemoryCapabilityTestApi(options?: {
+    readonly suiteId?: string;
+}): MemoryCapabilityTestApiV1;
+//# sourceMappingURL=memory-testkit.d.ts.map

package/dist/testing/memory-testkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-testkit.d.ts","sourceRoot":"","sources":["../../src/testing/memory-testkit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic memory testkit (1C.8a) — wires the 1C.1–1C.7 Foundation pieces\n * (atom validator, store, candidate machine, recall index, lifecycle manager,\n * scheduler, curation, continuation, purge gate/journal) into one reusable,\n * clock-injectable fixture. Acceptance: the 1C.7b closed loop repeats 20 times\n * with identical results through this kit.\n */\nimport { deepStrictEqual } from \"node:assert\";\nimport type {\n\tCapabilityAPI,\n\tJsonValue,\n\tLifecycleEvent,\n\tLifecycleEventDefinition,\n\tLifecycleEventReference,\n\tLifecycleObserveHandler,\n} from \"@agent-forge/plugin-sdk\";\nimport { createMemoryCandidateMachine, type MemoryCandidateMachineV1 } from \"../memory/candidates.ts\";\nimport { createMemoryCompactionSequencer } from \"../memory/compaction-sequencer.ts\";\nimport { createMemoryContinuationIssuer, type MemoryContinuationIssuerV1 } from \"../memory/continuation.ts\";\nimport { createMemoryCurationAgent, type MemoryCurationAgentV1 } from \"../memory/curation.ts\";\nimport type { MemoryEmbeddingProviderV1 } from \"../memory/embedding-provider.ts\";\nimport { createDeterministicMockEmbeddingProvider } from \"../memory/embedding-provider.ts\";\nimport type { MemoryRerankerV1 } from \"../memory/embedding-reranker.ts\";\nimport type { MemoryAtomV1, MemoryScopeV1 } from \"../memory/foundation.ts\";\nimport { buildMemoryAtomV1 } from \"../memory/foundation.ts\";\nimport {\n\tcreateMemoryLifecycleManager,\n\ttype MemoryLifecycleManagerV1,\n\ttype MemoryLifecyclePolicyV1,\n} from \"../memory/lifecycle.ts\";\nimport {\n\tcreateMemoryPurgeGate,\n\tcreateMemoryReplicaRegistry,\n\ttype MemoryPurgeGateV1,\n\ttype MemoryReplicaRegistryV1,\n} from \"../memory/purge.ts\";\nimport { createMemoryPurgeJournal, type MemoryPurgeJournalV1 } from \"../memory/purge-journal.ts\";\nimport { createMemoryRecallAgent, type MemoryRecallAgentV1 } from \"../memory/recall-agent.ts\";\nimport { createMemoryRecallIndex, type MemoryRecallPageV1, type MemoryRecallQueryV1 } from \"../memory/recall-index.ts\";\nimport { createMemoryScheduler, type MemorySchedulerV1 } from \"../memory/scheduler.ts\";\nimport {\n\tcreateFirstPartyRetentionRegistry,\n\tcreateMemoryStore,\n\ttype MemoryStoreV1,\n\ttype RetentionModeRegistryV1,\n} from \"../memory/store.ts\";\nimport type { MemoryVectorIndexEntryV1, MemoryVectorIndexV1 } from \"../memory/vector-index.ts\";\n\nexport interface MemoryTestKitOptions {\n\treadonly now?: () => number;\n\treadonly retentionRegistry?: RetentionModeRegistryV1;\n\treadonly lifecyclePolicy?: MemoryLifecyclePolicyV1;\n}\n\nexport interface MemoryTestKitAtomSeed {\n\treadonly owner?: string;\n\treadonly scope?: MemoryScopeV1;\n\treadonly retentionMode?: string;\n\treadonly memoryId?: string;\n\treadonly observationId?: string;\n\treadonly project?: string;\n\treadonly task?: string;\n\treadonly scene?: string;\n\treadonly occurredAt: string;\n\treadonly payload?: JsonValue;\n}\n\nexport interface MemoryTestKit {\n\treadonly store: MemoryStoreV1;\n\treadonly machine: MemoryCandidateMachineV1;\n\treadonly sequencer: ReturnType<typeof createMemoryCompactionSequencer>;\n\treadonly index: ReturnType<typeof createMemoryRecallIndex>;\n\treadonly lifecycle: MemoryLifecycleManagerV1;\n\treadonly scheduler: MemorySchedulerV1;\n\treadonly curation: MemoryCurationAgentV1;\n\treadonly continuation: MemoryContinuationIssuerV1;\n\treadonly purgeGate: MemoryPurgeGateV1;\n\treadonly purgeJournal: MemoryPurgeJournalV1;\n\treadonly recallAgent: MemoryRecallAgentV1;\n\t/** Builds a validated deterministic atom from a seed. */\n\tmakeAtom(seed: MemoryTestKitAtomSeed): MemoryAtomV1;\n\t/** Convenience: curation-commit an atom and return its memoryId. */\n\tcommit(atom: MemoryAtomV1): string;\n\tquery(query: MemoryRecallQueryV1): MemoryRecallPageV1;\n}\n\nexport function createMemoryTestKit(options: MemoryTestKitOptions = {}): MemoryTestKit {\n\tconst now = options.now ?? (() => Date.now());\n\tconst retentionRegistry = options.retentionRegistry ?? createFirstPartyRetentionRegistry();\n\tconst store = createMemoryStore({ retentionRegistry, now });\n\tconst machine = createMemoryCandidateMachine({ store, now });\n\tconst sequencer = createMemoryCompactionSequencer({ store });\n\tconst index = createMemoryRecallIndex({ store });\n\tconst lifecyclePolicy: MemoryLifecyclePolicyV1 = options.lifecyclePolicy ?? {\n\t\tpolicyVersion: \"lifecycle@1\",\n\t\thalfLifeMs: Object.freeze({\n\t\t\tsession: 1 * 24 * 60 * 60 * 1000,\n\t\t\tcycle: 7 * 24 * 60 * 60 * 1000,\n\t\t\t\"long-term\": 30 * 24 * 60 * 60 * 1000,\n\t\t}),\n\t\tstaleAfterMs: Object.freeze({\n\t\t\tsession: 2 * 24 * 60 * 60 * 1000,\n\t\t\tcycle: 14 * 24 * 60 * 60 * 1000,\n\t\t\t\"long-term\": 60 * 24 * 60 * 60 * 1000,\n\t\t}),\n\t\tarchiveAfterMs: Object.freeze({\n\t\t\tsession: 7 * 24 * 60 * 60 * 1000,\n\t\t\tcycle: 60 * 24 * 60 * 60 * 1000,\n\t\t\t\"long-term\": 180 * 24 * 60 * 60 * 1000,\n\t\t}),\n\t\tbaselineAttention: 0.5,\n\t};\n\tconst lifecycle = createMemoryLifecycleManager({ policy: lifecyclePolicy, now });\n\tconst scheduler = createMemoryScheduler({ now });\n\tconst curation = createMemoryCurationAgent({ store });\n\tconst continuation = createMemoryContinuationIssuer();\n\tconst replicaRegistry: MemoryReplicaRegistryV1 = createMemoryReplicaRegistry();\n\treplicaRegistry.register({\n\t\treplicaId: \"canonical-1\",\n\t\tkind: \"canonical\",\n\t\townerScope: \"*\",\n\t\tcontractVersion: \"agent-forge/memory@1\",\n\t\thealthy: true,\n\t});\n\tconst purgeGate = createMemoryPurgeGate({ registry: replicaRegistry, now });\n\tconst purgeJournal = createMemoryPurgeJournal();\n\tconst recallAgent = createMemoryRecallAgent({\n\t\tscheduler,\n\t\tindex,\n\t\tpolicyDefaults: {\n\t\t\tcandidateBudget: 1000,\n\t\t\tmodelInspectionLimit: 20,\n\t\t\tfinalResultLimit: 10,\n\t\t\tmaxRelationHops: 2,\n\t\t\tmaxModelCalls: 3,\n\t\t\tmaxOutputTokens: 4000,\n\t\t\tmaxOutputBytes: 16_000,\n\t\t\tmaxRounds: 3,\n\t\t},\n\t\thostLimits: {\n\t\t\tcandidateBudget: 5000,\n\t\t\tmodelInspectionLimit: 100,\n\t\t\tfinalResultLimit: 100,\n\t\t\tmaxRelationHops: 5,\n\t\t\tmaxModelCalls: 10,\n\t\t\tmaxOutputTokens: 100_000,\n\t\t\tmaxOutputBytes: 1_000_000,\n\t\t\tmaxRounds: 10,\n\t\t},\n\t\tnow,\n\t});\n\n\tlet sequence = 0;\n\tconst makeAtom = (seed: MemoryTestKitAtomSeed): MemoryAtomV1 => {\n\t\tsequence += 1;\n\t\treturn buildMemoryAtomV1({\n\t\t\tmemoryId: seed.memoryId ?? `mem-${String(sequence).padStart(4, \"0\")}`,\n\t\t\tcontractVersion: \"agent-forge/memory@1\",\n\t\t\tschemaVersion: 1,\n\t\t\tscope: seed.scope ?? \"long-term\",\n\t\t\tretentionMode: seed.retentionMode ?? \"permanent\",\n\t\t\towner: seed.owner ?? \"code-memory\",\n\t\t\tprofileId: \"coding-agent\",\n\t\t\tretentionPolicyVersion: \"retention@1\",\n\t\t\tmemoryKind: \"fact\",\n\t\t\tpayload: seed.payload ?? { sequence },\n\t\t\toccurredAt: seed.occurredAt,\n\t\t\trecordedAt: seed.occurredAt,\n\t\t\tsourceRefs: [{ kind: \"entry\", id: `entry-${sequence}` }],\n\t\t\tobservationId: seed.observationId ?? `obs-${sequence}`,\n\t\t\tsessionRefs: [],\n\t\t\tagentInstanceRefs: [],\n\t\t\tprojectRefs: seed.project ? [seed.project] : [],\n\t\t\tsubjectRefs: seed.task ? [seed.task] : [],\n\t\t\tfacets: [],\n\t\t\trelations: [],\n\t\t\tconfidence: 1,\n\t\t\timportance: 0.5,\n\t\t\tevidenceClass: \"explicit\",\n\t\t\tcontentRevision: `c-${sequence}`,\n\t\t\twriteReason: \"test\",\n\t\t});\n\t};\n\n\tconst commit = (atom: MemoryAtomV1): string => {\n\t\tstore.commit(atom);\n\t\treturn atom.memoryId;\n\t};\n\n\tconst query = (query: MemoryRecallQueryV1): MemoryRecallPageV1 => index.query(query);\n\n\treturn {\n\t\tstore,\n\t\tmachine,\n\t\tsequencer,\n\t\tindex,\n\t\tlifecycle,\n\t\tscheduler,\n\t\tcuration,\n\t\tcontinuation,\n\t\tpurgeGate,\n\t\tpurgeJournal,\n\t\trecallAgent,\n\t\tmakeAtom,\n\t\tcommit,\n\t\tquery,\n\t};\n}\n\n/** Repeats `run` up to `times` and requires every result to deep-equal the first. */\nexport async function repeatMemoryTestKit<T>(\n\ttimes: number,\n\trun: () => Promise<T>,\n): Promise<{ readonly baseline: T; readonly repeats: number }> {\n\tlet baseline: T | undefined;\n\tlet repeats = 0;\n\tfor (let index = 0; index < times; index += 1) {\n\t\tconst result = await run();\n\t\tif (index === 0) {\n\t\t\tbaseline = result;\n\t\t\tcontinue;\n\t\t}\n\t\t// node:assert deep compare keeps the kit free of test-runner imports\n\t\t// (plugin-src boundary gate allows node: builtins only); vitest renders\n\t\t// the AssertionError like any other thrown assertion.\n\t\tdeepStrictEqual(result, baseline);\n\t\trepeats += 1;\n\t}\n\treturn { baseline: baseline as T, repeats };\n}\n\n// ---------------------------------------------------------------------------\n// 向量混合检索 mock 注入点 (架构宪法: 默认测试只允许 deterministic mock AI)。\n// 供 capabilities/memory.ts 的 createCapabilityWithVectorComponents 注入,\n// 不触真实 transformers/lancedb。\n// ---------------------------------------------------------------------------\n\nfunction tokenizeForFakeIndex(text: string): readonly string[] {\n\treturn text\n\t\t.toLowerCase()\n\t\t.split(/[^\\p{L}\\p{N}]+/u)\n\t\t.filter((token) => token !== \"\");\n}\n\n/**\n * In-memory fake of the LanceDB vector index (memory/vector-index.ts 同契约):\n * KNN 平扫平方 L2 (score = 1/(1+距离), 与真组件同口径), FTS 按词元包含匹配\n * (score = 1/(60+rank+1), 与真组件同口径)。确定性: 排序并列按插入序打破。\n */\nexport function createInMemoryMemoryVectorIndex(options: { readonly dimensions: number }): MemoryVectorIndexV1 {\n\tconst dimensions = options.dimensions;\n\tconst rows = new Map<string, MemoryVectorIndexEntryV1>();\n\tconst insertOrder: string[] = [];\n\tconst bodyOf = (entry: MemoryVectorIndexEntryV1): string => `${entry.statement} ${entry.tags.join(\" \")}`;\n\treturn {\n\t\treplicaId: \"memory-vector-index\",\n\t\tupsert: async (entries) => {\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (entry.vector.length !== dimensions) {\n\t\t\t\t\tthrow new Error(`dimension mismatch for ${entry.memoryId}`);\n\t\t\t\t}\n\t\t\t\tif (!rows.has(entry.memoryId)) insertOrder.push(entry.memoryId);\n\t\t\t\trows.set(entry.memoryId, entry);\n\t\t\t}\n\t\t},\n\t\tremove: async (memoryIds) => {\n\t\t\tfor (const memoryId of memoryIds) {\n\t\t\t\trows.delete(memoryId);\n\t\t\t\tconst position = insertOrder.indexOf(memoryId);\n\t\t\t\tif (position >= 0) insertOrder.splice(position, 1);\n\t\t\t}\n\t\t},\n\t\tqueryKnn: async (vector, query) => {\n\t\t\tif (vector.length !== dimensions) throw new Error(\"query vector dimension mismatch\");\n\t\t\tconst hits = insertOrder\n\t\t\t\t.map((memoryId) => {\n\t\t\t\t\tconst entry = rows.get(memoryId);\n\t\t\t\t\tif (entry === undefined || entry.owner !== query.owner) return undefined;\n\t\t\t\t\tlet sumSquares = 0;\n\t\t\t\t\tfor (const [axis, value] of vector.entries()) {\n\t\t\t\t\t\tconst delta = value - (entry.vector[axis] ?? 0);\n\t\t\t\t\t\tsumSquares += delta * delta;\n\t\t\t\t\t}\n\t\t\t\t\treturn { memoryId, score: 1 / (1 + sumSquares) };\n\t\t\t\t})\n\t\t\t\t.filter((hit): hit is { memoryId: string; score: number } => hit !== undefined);\n\t\t\thits.sort((left, right) => right.score - left.score);\n\t\t\treturn hits.slice(0, query.limit);\n\t\t},\n\t\tqueryFts: async (queryText, query) => {\n\t\t\tconst queryTokens = tokenizeForFakeIndex(queryText);\n\t\t\tif (queryTokens.length === 0) return [];\n\t\t\tconst matched = insertOrder\n\t\t\t\t.map((memoryId) => {\n\t\t\t\t\tconst entry = rows.get(memoryId);\n\t\t\t\t\tif (entry === undefined || entry.owner !== query.owner) return undefined;\n\t\t\t\t\tconst bodyTokens = new Set(tokenizeForFakeIndex(bodyOf(entry)));\n\t\t\t\t\tconst hits = queryTokens.filter((token) => bodyTokens.has(token)).length;\n\t\t\t\t\treturn hits > 0 ? { memoryId, hits } : undefined;\n\t\t\t\t})\n\t\t\t\t.filter((hit): hit is { memoryId: string; hits: number } => hit !== undefined);\n\t\t\t// 命中词元数降序, 并列按插入序; 打分与真组件同口径 (RRF_K=60)。\n\t\t\tmatched.sort((left, right) => right.hits - left.hits);\n\t\t\treturn matched\n\t\t\t\t.slice(0, query.limit)\n\t\t\t\t.map((hit, rank) => ({ memoryId: hit.memoryId, score: 1 / (60 + rank + 1) }));\n\t\t},\n\t\tlistMemoryIds: async () => new Set(rows.keys()),\n\t\tcount: async () => rows.size,\n\t\tgetStoredModelId: async () => {\n\t\t\tconst first = insertOrder.find((memoryId) => rows.has(memoryId));\n\t\t\treturn first === undefined ? undefined : rows.get(first)?.modelId;\n\t\t},\n\t\tclose: async () => {},\n\t};\n}\n\n/**\n * Deterministic mock vector components for the capability's vector-channel\n * injection seam: the FNV token-hash mock embedder plus a scripted or\n * lexical-overlap reranker over an in-memory fake index. No network, no real\n * models, fully deterministic.\n */\nexport interface MockMemoryVectorComponentsOptions {\n\treadonly dimensions?: number;\n\t/** Explicit rerank scoring; default = deterministic lexical-overlap reranker. */\n\treadonly rerank?: (query: string, docs: readonly string[]) => readonly number[];\n\t/** true → no reranker at all (精排不可用路径: 跳过精排, RRF 序)。 */\n\treadonly rerankerUnavailable?: boolean;\n}\n\nexport function createMockMemoryVectorComponents(options: MockMemoryVectorComponentsOptions = {}): {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker: MemoryRerankerV1 | undefined;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n} {\n\tconst embedProvider = createDeterministicMockEmbeddingProvider({ dimensions: options.dimensions ?? 8 });\n\tconst vectorIndex = createInMemoryMemoryVectorIndex({ dimensions: embedProvider.dimensions });\n\tconst scriptedRerank = options.rerank;\n\tconst reranker: MemoryRerankerV1 | undefined = options.rerankerUnavailable\n\t\t? undefined\n\t\t: {\n\t\t\t\tmodelId: \"mock-reranker@1\",\n\t\t\t\trerank:\n\t\t\t\t\tscriptedRerank === undefined\n\t\t\t\t\t\t? createLexicalMockReranker().rerank\n\t\t\t\t\t\t: async (query, docs) => scriptedRerank(query, docs),\n\t\t\t};\n\treturn { embedProvider, reranker, vectorIndex };\n}\n\n/** Deterministic reranker mock: score = count of query tokens present in the doc. */\nexport function createLexicalMockReranker(): MemoryRerankerV1 {\n\treturn {\n\t\tmodelId: \"mock-reranker@1\",\n\t\trerank: async (query, docs) => {\n\t\t\tconst queryTokens = new Set(tokenizeForFakeIndex(query));\n\t\t\treturn docs.map((doc) => {\n\t\t\t\tlet overlap = 0;\n\t\t\t\tfor (const token of tokenizeForFakeIndex(doc)) {\n\t\t\t\t\tif (queryTokens.has(token)) overlap += 1;\n\t\t\t\t}\n\t\t\t\treturn overlap;\n\t\t\t});\n\t\t},\n\t};\n}\n\n/**\n * 显式向量表 mock 组件 (2.4d6 S3 语义合并测试用): 每条文本的向量由测试直接\n * 指定 (绕过 FNV token hash — 合并阈值的余弦判定需要可控向量), 搭配\n * in-memory fake index 与缺省词元重排器, 零网络零真实模型 (架构宪法测试\n * 门禁)。dimensions 取自向量表首个声明向量; 未声明向量的文本显式抛错 —\n * 测试必须登记每一条会被 embed 的内容与查询 (含召回 query), 保证确定性。\n */\nexport function createScriptedMockVectorComponents(vectors: { readonly [text: string]: readonly number[] }): {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker: MemoryRerankerV1 | undefined;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n} {\n\tconst table = new Map<string, readonly number[]>(Object.entries(vectors));\n\tconst firstVector = table.values().next();\n\tif (firstVector.done || firstVector.value.length === 0) {\n\t\tthrow new Error(\"createScriptedMockVectorComponents requires at least one declared vector\");\n\t}\n\tconst dimensions = firstVector.value.length;\n\tconst embedProvider: MemoryEmbeddingProviderV1 = {\n\t\tmodelId: \"mock-embedding-scripted@1\",\n\t\tdimensions,\n\t\tembed: async (texts) =>\n\t\t\ttexts.map((text) => {\n\t\t\t\tconst vector = table.get(text);\n\t\t\t\tif (vector === undefined) throw new Error(`no scripted vector declared for text: ${text}`);\n\t\t\t\treturn vector;\n\t\t\t}),\n\t};\n\treturn {\n\t\tembedProvider,\n\t\treranker: createLexicalMockReranker(),\n\t\tvectorIndex: createInMemoryMemoryVectorIndex({ dimensions }),\n\t};\n}\n\n/** A loop hook captured from a capability registration (测试侧驱动用). */\nexport interface MemoryCapabilityLoopHookCaptureV1 {\n\treadonly position: string;\n\treadonly handler: (messages: unknown) => Promise<unknown>;\n}\n\n/**\n * Minimal capture api for driving `createCapability` / its vector-component\n * test variant at the factory level (mirrors the runtime tool/command surface:\n * registerTool, registerCommand, publish, logger, capabilities, session,\n * lifecycle, registerLoopHook).\n */\nexport interface MemoryCapabilityTestApiV1 {\n\treadonly api: CapabilityAPI;\n\t/** Registered tool by name (undefined when the capability did not register it). */\n\ttool(name: string): { readonly execute: (first: unknown, second?: unknown) => Promise<unknown> } | undefined;\n\t/** Registered command by name (undefined when the capability did not register it). */\n\tcommand(name: string): { readonly execute: (args: string) => Promise<unknown> } | undefined;\n\t/** logger.warn messages captured for degraded-channel assertions. */\n\treadonly warnings: readonly string[];\n\t/** logger.info messages captured for off/enabling declaration assertions. */\n\treadonly infos: readonly string[];\n\t/** logger.debug messages captured for bounded-skip assertions (§2.2 配对失败). */\n\treadonly debugs: readonly string[];\n\t/** Appends a suite binding entry; resolveSessionDomain reads the LAST one. */\n\tbindSuite(suiteId: string): void;\n\t/**\n\t * Appends one message entry (assistant/user/toolResult shape is the test's\n\t * responsibility) to the branch; returns the entry id.\n\t */\n\tappendMessageEntry(message: unknown): string;\n\t/** The registered loop hook for a position (undefined when not registered). */\n\tloopHook(position: string): MemoryCapabilityLoopHookCaptureV1 | undefined;\n\t/**\n\t * Dispatches a committed lifecycle event to every registered observer of\n\t * id@version (test-side stand-in for the host lifecycle dispatcher).\n\t */\n\tdispatchLifecycleEvent(event: {\n\t\treadonly id: string;\n\t\treadonly version?: number;\n\t\treadonly data: unknown;\n\t}): Promise<void>;\n}\n\nexport function createMemoryCapabilityTestApi(options: { readonly suiteId?: string } = {}): MemoryCapabilityTestApiV1 {\n\tconst warnings: string[] = [];\n\tconst infos: string[] = [];\n\tconst debugs: string[] = [];\n\tconst registered = new Map<string, { readonly execute: (first: unknown, second?: unknown) => Promise<unknown> }>();\n\tconst commands = new Map<string, { readonly execute: (args: string) => Promise<unknown> }>();\n\tconst entries: { id: string; type: string; customType?: string; data?: unknown; message?: unknown }[] = [];\n\tconst loopHooks: MemoryCapabilityLoopHookCaptureV1[] = [];\n\t// Lifecycle stand-in: definitions by id@version plus observer lists, enough\n\t// for capabilities that define catalog events and register observe handlers.\n\tlet deliverySequence = 0;\n\tconst lifecycleDefinitions = new Map<string, LifecycleEventDefinition<unknown>>();\n\tconst lifecycleObservers = new Map<string, ((event: LifecycleEvent<unknown>) => unknown)[]>();\n\tconst lifecycleKeyOf = (id: string, version: number): string => `${id}@${version}`;\n\tconst lifecycleReferenceOf = (\n\t\tevent: LifecycleEventDefinition<unknown> | LifecycleEventReference | string,\n\t\tversion?: number,\n\t): { readonly id: string; readonly version: number } => {\n\t\tif (typeof event === \"string\") return { id: event, version: version ?? 1 };\n\t\treturn { id: event.id, version: event.version };\n\t};\n\tconst registerLifecycleObserver = (\n\t\tevent: LifecycleEventDefinition<unknown> | LifecycleEventReference | string,\n\t\thandler: LifecycleObserveHandler<unknown>,\n\t\tversion?: number,\n\t): { dispose: () => void } => {\n\t\tconst reference = lifecycleReferenceOf(event, version);\n\t\tconst key = lifecycleKeyOf(reference.id, reference.version);\n\t\tconst list = lifecycleObservers.get(key) ?? [];\n\t\tlist.push(handler);\n\t\tlifecycleObservers.set(key, list);\n\t\treturn { dispose: () => {} };\n\t};\n\tconst lifecycle = {\n\t\tdefine: (definition: LifecycleEventDefinition<unknown>): LifecycleEventDefinition<unknown> => {\n\t\t\tconst key = lifecycleKeyOf(definition.id, definition.version);\n\t\t\tif (lifecycleDefinitions.has(key)) {\n\t\t\t\tthrow new Error(`Lifecycle event is already defined: ${definition.id}@${definition.version}`);\n\t\t\t}\n\t\t\tlifecycleDefinitions.set(key, definition);\n\t\t\treturn definition;\n\t\t},\n\t\tget: (id: string, version: number): LifecycleEventDefinition<unknown> => {\n\t\t\tconst definition = lifecycleDefinitions.get(lifecycleKeyOf(id, version));\n\t\t\tif (definition === undefined) throw new Error(`Lifecycle event is not defined: ${id}@${version}`);\n\t\t\treturn definition;\n\t\t},\n\t\tregisterObserve: registerLifecycleObserver,\n\t\tregisterTransform: (): { dispose: () => void } => {\n\t\t\tthrow new Error(\"lifecycle transform is not available in this fixture\");\n\t\t},\n\t\tregisterExecute: (): { dispose: () => void } => {\n\t\t\tthrow new Error(\"lifecycle execute is not available in this fixture\");\n\t\t},\n\t\tregisterAfterCommit: registerLifecycleObserver,\n\t};\n\tlet messageSequence = 0;\n\tif (options.suiteId !== undefined) {\n\t\tentries.push({ id: \"binding-0\", type: \"custom\", customType: \"suite\", data: { suiteId: options.suiteId } });\n\t}\n\tconst api = {\n\t\tregisterTool: (definition: { name: string; execute: (first: unknown, second?: unknown) => Promise<unknown> }) => {\n\t\t\tregistered.set(definition.name, definition);\n\t\t\treturn { dispose: async () => {} };\n\t\t},\n\t\tregisterCommand: (definition: { name: string; execute: (args: string) => Promise<unknown> }) => {\n\t\t\tcommands.set(definition.name, definition);\n\t\t\treturn { dispose: async () => {} };\n\t\t},\n\t\tregisterLoopHook: (position: string, handler: (messages: unknown) => Promise<unknown>) => {\n\t\t\tloopHooks.push({ position, handler });\n\t\t\treturn { dispose: async () => {} };\n\t\t},\n\t\tpublish: async (event: unknown) => ({ id: \"test-event\", source: \"test\", timestamp: 0, ...(event as object) }),\n\t\tlogger: {\n\t\t\tdebug: (message: string) => {\n\t\t\t\tdebugs.push(message);\n\t\t\t},\n\t\t\tinfo: (message: string) => {\n\t\t\t\tinfos.push(message);\n\t\t\t},\n\t\t\twarn: (message: string) => {\n\t\t\t\twarnings.push(message);\n\t\t\t},\n\t\t\terror: () => {},\n\t\t},\n\t\tcapabilities: {\n\t\t\tprovide: () => ({ dispose: () => {} }),\n\t\t\trequire: () => {\n\t\t\t\tthrow new Error(\"capability require is not available in this fixture\");\n\t\t\t},\n\t\t\tlist: () => [],\n\t\t},\n\t\tsession: {\n\t\t\tgetSessionId: () => \"memory-test-session\",\n\t\t\tgetBranchEntries: () => entries,\n\t\t},\n\t\tlifecycle,\n\t} as unknown as CapabilityAPI;\n\treturn {\n\t\tapi,\n\t\ttool: (name) => registered.get(name),\n\t\tcommand: (name) => commands.get(name),\n\t\twarnings,\n\t\tinfos,\n\t\tdebugs,\n\t\tbindSuite: (suiteId) => {\n\t\t\tentries.push({ id: `binding-${entries.length}`, type: \"custom\", customType: \"suite\", data: { suiteId } });\n\t\t},\n\t\tappendMessageEntry: (message) => {\n\t\t\tmessageSequence += 1;\n\t\t\tconst id = `message-${messageSequence}`;\n\t\t\tentries.push({ id, type: \"message\", message });\n\t\t\treturn id;\n\t\t},\n\t\tloopHook: (position) => loopHooks.find((hook) => hook.position === position),\n\t\tdispatchLifecycleEvent: async (event) => {\n\t\t\tconst version = event.version ?? 1;\n\t\t\tconst list = lifecycleObservers.get(lifecycleKeyOf(event.id, version)) ?? [];\n\t\t\tdeliverySequence += 1;\n\t\t\tconst lifecycleEvent: LifecycleEvent<unknown> = {\n\t\t\t\tid: event.id,\n\t\t\t\tdeliveryId: `test-delivery-${deliverySequence}`,\n\t\t\t\ttype: event.id,\n\t\t\t\tversion,\n\t\t\t\tphase: \"committed\",\n\t\t\t\tsource: \"test\",\n\t\t\t\ttimestamp: 0,\n\t\t\t\tdata: event.data,\n\t\t\t};\n\t\t\tfor (const handler of list) await handler(lifecycleEvent);\n\t\t},\n\t};\n}\n"]}

package/dist/testing/memory-testkit.js

@@ -0,0 +1,438 @@
+/**
+ * Deterministic memory testkit (1C.8a) — wires the 1C.1–1C.7 Foundation pieces
+ * (atom validator, store, candidate machine, recall index, lifecycle manager,
+ * scheduler, curation, continuation, purge gate/journal) into one reusable,
+ * clock-injectable fixture. Acceptance: the 1C.7b closed loop repeats 20 times
+ * with identical results through this kit.
+ */
+import { deepStrictEqual } from "node:assert";
+import { createMemoryCandidateMachine } from "../memory/candidates.js";
+import { createMemoryCompactionSequencer } from "../memory/compaction-sequencer.js";
+import { createMemoryContinuationIssuer } from "../memory/continuation.js";
+import { createMemoryCurationAgent } from "../memory/curation.js";
+import { createDeterministicMockEmbeddingProvider } from "../memory/embedding-provider.js";
+import { buildMemoryAtomV1 } from "../memory/foundation.js";
+import { createMemoryLifecycleManager, } from "../memory/lifecycle.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 { createFirstPartyRetentionRegistry, createMemoryStore, } from "../memory/store.js";
+export function createMemoryTestKit(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const retentionRegistry = options.retentionRegistry ?? createFirstPartyRetentionRegistry();
+    const store = createMemoryStore({ retentionRegistry, now });
+    const machine = createMemoryCandidateMachine({ store, now });
+    const sequencer = createMemoryCompactionSequencer({ store });
+    const index = createMemoryRecallIndex({ store });
+    const lifecyclePolicy = options.lifecyclePolicy ?? {
+        policyVersion: "lifecycle@1",
+        halfLifeMs: Object.freeze({
+            session: 1 * 24 * 60 * 60 * 1000,
+            cycle: 7 * 24 * 60 * 60 * 1000,
+            "long-term": 30 * 24 * 60 * 60 * 1000,
+        }),
+        staleAfterMs: Object.freeze({
+            session: 2 * 24 * 60 * 60 * 1000,
+            cycle: 14 * 24 * 60 * 60 * 1000,
+            "long-term": 60 * 24 * 60 * 60 * 1000,
+        }),
+        archiveAfterMs: Object.freeze({
+            session: 7 * 24 * 60 * 60 * 1000,
+            cycle: 60 * 24 * 60 * 60 * 1000,
+            "long-term": 180 * 24 * 60 * 60 * 1000,
+        }),
+        baselineAttention: 0.5,
+    };
+    const lifecycle = createMemoryLifecycleManager({ policy: lifecyclePolicy, now });
+    const scheduler = createMemoryScheduler({ now });
+    const curation = createMemoryCurationAgent({ store });
+    const continuation = createMemoryContinuationIssuer();
+    const replicaRegistry = createMemoryReplicaRegistry();
+    replicaRegistry.register({
+        replicaId: "canonical-1",
+        kind: "canonical",
+        ownerScope: "*",
+        contractVersion: "agent-forge/memory@1",
+        healthy: true,
+    });
+    const purgeGate = createMemoryPurgeGate({ registry: replicaRegistry, now });
+    const purgeJournal = createMemoryPurgeJournal();
+    const recallAgent = createMemoryRecallAgent({
+        scheduler,
+        index,
+        policyDefaults: {
+            candidateBudget: 1000,
+            modelInspectionLimit: 20,
+            finalResultLimit: 10,
+            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,
+    });
+    let sequence = 0;
+    const makeAtom = (seed) => {
+        sequence += 1;
+        return buildMemoryAtomV1({
+            memoryId: seed.memoryId ?? `mem-${String(sequence).padStart(4, "0")}`,
+            contractVersion: "agent-forge/memory@1",
+            schemaVersion: 1,
+            scope: seed.scope ?? "long-term",
+            retentionMode: seed.retentionMode ?? "permanent",
+            owner: seed.owner ?? "code-memory",
+            profileId: "coding-agent",
+            retentionPolicyVersion: "retention@1",
+            memoryKind: "fact",
+            payload: seed.payload ?? { sequence },
+            occurredAt: seed.occurredAt,
+            recordedAt: seed.occurredAt,
+            sourceRefs: [{ kind: "entry", id: `entry-${sequence}` }],
+            observationId: seed.observationId ?? `obs-${sequence}`,
+            sessionRefs: [],
+            agentInstanceRefs: [],
+            projectRefs: seed.project ? [seed.project] : [],
+            subjectRefs: seed.task ? [seed.task] : [],
+            facets: [],
+            relations: [],
+            confidence: 1,
+            importance: 0.5,
+            evidenceClass: "explicit",
+            contentRevision: `c-${sequence}`,
+            writeReason: "test",
+        });
+    };
+    const commit = (atom) => {
+        store.commit(atom);
+        return atom.memoryId;
+    };
+    const query = (query) => index.query(query);
+    return {
+        store,
+        machine,
+        sequencer,
+        index,
+        lifecycle,
+        scheduler,
+        curation,
+        continuation,
+        purgeGate,
+        purgeJournal,
+        recallAgent,
+        makeAtom,
+        commit,
+        query,
+    };
+}
+/** Repeats `run` up to `times` and requires every result to deep-equal the first. */
+export async function repeatMemoryTestKit(times, run) {
+    let baseline;
+    let repeats = 0;
+    for (let index = 0; index < times; index += 1) {
+        const result = await run();
+        if (index === 0) {
+            baseline = result;
+            continue;
+        }
+        // node:assert deep compare keeps the kit free of test-runner imports
+        // (plugin-src boundary gate allows node: builtins only); vitest renders
+        // the AssertionError like any other thrown assertion.
+        deepStrictEqual(result, baseline);
+        repeats += 1;
+    }
+    return { baseline: baseline, repeats };
+}
+// ---------------------------------------------------------------------------
+// 向量混合检索 mock 注入点 (架构宪法: 默认测试只允许 deterministic mock AI)。
+// 供 capabilities/memory.ts 的 createCapabilityWithVectorComponents 注入,
+// 不触真实 transformers/lancedb。
+// ---------------------------------------------------------------------------
+function tokenizeForFakeIndex(text) {
+    return text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((token) => token !== "");
+}
+/**
+ * In-memory fake of the LanceDB vector index (memory/vector-index.ts 同契约):
+ * KNN 平扫平方 L2 (score = 1/(1+距离), 与真组件同口径), FTS 按词元包含匹配
+ * (score = 1/(60+rank+1), 与真组件同口径)。确定性: 排序并列按插入序打破。
+ */
+export function createInMemoryMemoryVectorIndex(options) {
+    const dimensions = options.dimensions;
+    const rows = new Map();
+    const insertOrder = [];
+    const bodyOf = (entry) => `${entry.statement} ${entry.tags.join(" ")}`;
+    return {
+        replicaId: "memory-vector-index",
+        upsert: async (entries) => {
+            for (const entry of entries) {
+                if (entry.vector.length !== dimensions) {
+                    throw new Error(`dimension mismatch for ${entry.memoryId}`);
+                }
+                if (!rows.has(entry.memoryId))
+                    insertOrder.push(entry.memoryId);
+                rows.set(entry.memoryId, entry);
+            }
+        },
+        remove: async (memoryIds) => {
+            for (const memoryId of memoryIds) {
+                rows.delete(memoryId);
+                const position = insertOrder.indexOf(memoryId);
+                if (position >= 0)
+                    insertOrder.splice(position, 1);
+            }
+        },
+        queryKnn: async (vector, query) => {
+            if (vector.length !== dimensions)
+                throw new Error("query vector dimension mismatch");
+            const hits = insertOrder
+                .map((memoryId) => {
+                const entry = rows.get(memoryId);
+                if (entry === undefined || entry.owner !== query.owner)
+                    return undefined;
+                let sumSquares = 0;
+                for (const [axis, value] of vector.entries()) {
+                    const delta = value - (entry.vector[axis] ?? 0);
+                    sumSquares += delta * delta;
+                }
+                return { memoryId, score: 1 / (1 + sumSquares) };
+            })
+                .filter((hit) => hit !== undefined);
+            hits.sort((left, right) => right.score - left.score);
+            return hits.slice(0, query.limit);
+        },
+        queryFts: async (queryText, query) => {
+            const queryTokens = tokenizeForFakeIndex(queryText);
+            if (queryTokens.length === 0)
+                return [];
+            const matched = insertOrder
+                .map((memoryId) => {
+                const entry = rows.get(memoryId);
+                if (entry === undefined || entry.owner !== query.owner)
+                    return undefined;
+                const bodyTokens = new Set(tokenizeForFakeIndex(bodyOf(entry)));
+                const hits = queryTokens.filter((token) => bodyTokens.has(token)).length;
+                return hits > 0 ? { memoryId, hits } : undefined;
+            })
+                .filter((hit) => hit !== undefined);
+            // 命中词元数降序, 并列按插入序; 打分与真组件同口径 (RRF_K=60)。
+            matched.sort((left, right) => right.hits - left.hits);
+            return matched
+                .slice(0, query.limit)
+                .map((hit, rank) => ({ memoryId: hit.memoryId, score: 1 / (60 + rank + 1) }));
+        },
+        listMemoryIds: async () => new Set(rows.keys()),
+        count: async () => rows.size,
+        getStoredModelId: async () => {
+            const first = insertOrder.find((memoryId) => rows.has(memoryId));
+            return first === undefined ? undefined : rows.get(first)?.modelId;
+        },
+        close: async () => { },
+    };
+}
+export function createMockMemoryVectorComponents(options = {}) {
+    const embedProvider = createDeterministicMockEmbeddingProvider({ dimensions: options.dimensions ?? 8 });
+    const vectorIndex = createInMemoryMemoryVectorIndex({ dimensions: embedProvider.dimensions });
+    const scriptedRerank = options.rerank;
+    const reranker = options.rerankerUnavailable
+        ? undefined
+        : {
+            modelId: "mock-reranker@1",
+            rerank: scriptedRerank === undefined
+                ? createLexicalMockReranker().rerank
+                : async (query, docs) => scriptedRerank(query, docs),
+        };
+    return { embedProvider, reranker, vectorIndex };
+}
+/** Deterministic reranker mock: score = count of query tokens present in the doc. */
+export function createLexicalMockReranker() {
+    return {
+        modelId: "mock-reranker@1",
+        rerank: async (query, docs) => {
+            const queryTokens = new Set(tokenizeForFakeIndex(query));
+            return docs.map((doc) => {
+                let overlap = 0;
+                for (const token of tokenizeForFakeIndex(doc)) {
+                    if (queryTokens.has(token))
+                        overlap += 1;
+                }
+                return overlap;
+            });
+        },
+    };
+}
+/**
+ * 显式向量表 mock 组件 (2.4d6 S3 语义合并测试用): 每条文本的向量由测试直接
+ * 指定 (绕过 FNV token hash — 合并阈值的余弦判定需要可控向量), 搭配
+ * in-memory fake index 与缺省词元重排器, 零网络零真实模型 (架构宪法测试
+ * 门禁)。dimensions 取自向量表首个声明向量; 未声明向量的文本显式抛错 —
+ * 测试必须登记每一条会被 embed 的内容与查询 (含召回 query), 保证确定性。
+ */
+export function createScriptedMockVectorComponents(vectors) {
+    const table = new Map(Object.entries(vectors));
+    const firstVector = table.values().next();
+    if (firstVector.done || firstVector.value.length === 0) {
+        throw new Error("createScriptedMockVectorComponents requires at least one declared vector");
+    }
+    const dimensions = firstVector.value.length;
+    const embedProvider = {
+        modelId: "mock-embedding-scripted@1",
+        dimensions,
+        embed: async (texts) => texts.map((text) => {
+            const vector = table.get(text);
+            if (vector === undefined)
+                throw new Error(`no scripted vector declared for text: ${text}`);
+            return vector;
+        }),
+    };
+    return {
+        embedProvider,
+        reranker: createLexicalMockReranker(),
+        vectorIndex: createInMemoryMemoryVectorIndex({ dimensions }),
+    };
+}
+export function createMemoryCapabilityTestApi(options = {}) {
+    const warnings = [];
+    const infos = [];
+    const debugs = [];
+    const registered = new Map();
+    const commands = new Map();
+    const entries = [];
+    const loopHooks = [];
+    // Lifecycle stand-in: definitions by id@version plus observer lists, enough
+    // for capabilities that define catalog events and register observe handlers.
+    let deliverySequence = 0;
+    const lifecycleDefinitions = new Map();
+    const lifecycleObservers = new Map();
+    const lifecycleKeyOf = (id, version) => `${id}@${version}`;
+    const lifecycleReferenceOf = (event, version) => {
+        if (typeof event === "string")
+            return { id: event, version: version ?? 1 };
+        return { id: event.id, version: event.version };
+    };
+    const registerLifecycleObserver = (event, handler, version) => {
+        const reference = lifecycleReferenceOf(event, version);
+        const key = lifecycleKeyOf(reference.id, reference.version);
+        const list = lifecycleObservers.get(key) ?? [];
+        list.push(handler);
+        lifecycleObservers.set(key, list);
+        return { dispose: () => { } };
+    };
+    const lifecycle = {
+        define: (definition) => {
+            const key = lifecycleKeyOf(definition.id, definition.version);
+            if (lifecycleDefinitions.has(key)) {
+                throw new Error(`Lifecycle event is already defined: ${definition.id}@${definition.version}`);
+            }
+            lifecycleDefinitions.set(key, definition);
+            return definition;
+        },
+        get: (id, version) => {
+            const definition = lifecycleDefinitions.get(lifecycleKeyOf(id, version));
+            if (definition === undefined)
+                throw new Error(`Lifecycle event is not defined: ${id}@${version}`);
+            return definition;
+        },
+        registerObserve: registerLifecycleObserver,
+        registerTransform: () => {
+            throw new Error("lifecycle transform is not available in this fixture");
+        },
+        registerExecute: () => {
+            throw new Error("lifecycle execute is not available in this fixture");
+        },
+        registerAfterCommit: registerLifecycleObserver,
+    };
+    let messageSequence = 0;
+    if (options.suiteId !== undefined) {
+        entries.push({ id: "binding-0", type: "custom", customType: "suite", data: { suiteId: options.suiteId } });
+    }
+    const api = {
+        registerTool: (definition) => {
+            registered.set(definition.name, definition);
+            return { dispose: async () => { } };
+        },
+        registerCommand: (definition) => {
+            commands.set(definition.name, definition);
+            return { dispose: async () => { } };
+        },
+        registerLoopHook: (position, handler) => {
+            loopHooks.push({ position, handler });
+            return { dispose: async () => { } };
+        },
+        publish: async (event) => ({ id: "test-event", source: "test", timestamp: 0, ...event }),
+        logger: {
+            debug: (message) => {
+                debugs.push(message);
+            },
+            info: (message) => {
+                infos.push(message);
+            },
+            warn: (message) => {
+                warnings.push(message);
+            },
+            error: () => { },
+        },
+        capabilities: {
+            provide: () => ({ dispose: () => { } }),
+            require: () => {
+                throw new Error("capability require is not available in this fixture");
+            },
+            list: () => [],
+        },
+        session: {
+            getSessionId: () => "memory-test-session",
+            getBranchEntries: () => entries,
+        },
+        lifecycle,
+    };
+    return {
+        api,
+        tool: (name) => registered.get(name),
+        command: (name) => commands.get(name),
+        warnings,
+        infos,
+        debugs,
+        bindSuite: (suiteId) => {
+            entries.push({ id: `binding-${entries.length}`, type: "custom", customType: "suite", data: { suiteId } });
+        },
+        appendMessageEntry: (message) => {
+            messageSequence += 1;
+            const id = `message-${messageSequence}`;
+            entries.push({ id, type: "message", message });
+            return id;
+        },
+        loopHook: (position) => loopHooks.find((hook) => hook.position === position),
+        dispatchLifecycleEvent: async (event) => {
+            const version = event.version ?? 1;
+            const list = lifecycleObservers.get(lifecycleKeyOf(event.id, version)) ?? [];
+            deliverySequence += 1;
+            const lifecycleEvent = {
+                id: event.id,
+                deliveryId: `test-delivery-${deliverySequence}`,
+                type: event.id,
+                version,
+                phase: "committed",
+                source: "test",
+                timestamp: 0,
+                data: event.data,
+            };
+            for (const handler of list)
+                await handler(lifecycleEvent);
+        },
+    };
+}
+//# sourceMappingURL=memory-testkit.js.map