@ai-agent-forge/plugin-sdk 0.85.0

package/dist/ecosystem-manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Ecosystem package manifest schema (agent-forge.json), V1.
+ *
+ * These types describe compatibility facts only. They intentionally do not
+ * contain approval, sandbox, credential, or domain-specific policy.
+ *
+ * Authority: `@agent-forge/plugin-sdk` (D-075 S2); the host re-exports them from
+ * its ecosystem contracts module so existing imports keep resolving.
+ */
+export type PluginOperatingSystem = "windows" | "macos" | "linux" | "any";
+export type PluginArchitecture = "x64" | "arm64" | "any";
+export interface CapabilityRefV1 {
+    readonly id: string;
+    /** Exact capability schema version. A breaking schema change increments it. */
+    readonly version: number;
+}
+export interface RuntimeConstraintV1 {
+    readonly name: string;
+    readonly minVersion?: string;
+    readonly maxVersion?: string;
+}
+export interface PluginAdapterManifestV1 {
+    readonly id: string;
+    readonly version: string;
+    readonly os: readonly PluginOperatingSystem[];
+    readonly arch?: readonly PluginArchitecture[];
+    readonly hostFeatures?: readonly string[];
+}
+export interface PluginPlatformBindingV1 {
+    readonly os: readonly PluginOperatingSystem[];
+    readonly arch?: readonly PluginArchitecture[];
+    readonly runtime?: readonly RuntimeConstraintV1[];
+    readonly hostFeatures?: readonly string[];
+    readonly adapters?: readonly PluginAdapterManifestV1[];
+}
+export interface CapabilityRequirementV1 extends CapabilityRefV1 {
+    readonly optional?: boolean;
+}
+/** Versioned package manifest consumed by the deterministic resolver. */
+export interface PluginManifestV1 {
+    readonly id: string;
+    /** Package release version (normally MAJOR.MINOR.PATCH). */
+    readonly pluginVersion: string;
+    /** Public host API version required by this package. */
+    readonly apiVersion: string;
+    /** Minimum host version required to load this package; the host must be >= this version. */
+    readonly minHostVersion?: string;
+    /** Maximum host version supported by this package; the host must be <= this version. */
+    readonly maxHostVersion?: string;
+    readonly capabilityRefs?: readonly CapabilityRefV1[];
+    readonly requires?: readonly CapabilityRequirementV1[];
+    readonly platform?: PluginPlatformBindingV1;
+    /** A contract/mock package that must never be selected for a production Profile. */
+    readonly testOnly?: boolean;
+}
+//# sourceMappingURL=ecosystem-manifest.d.ts.map

package/dist/ecosystem-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecosystem-manifest.d.ts","sourceRoot":"","sources":["../src/ecosystem-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAC1E,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,EAAE,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wFAAwF;IACxF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAC5C,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC5B","sourcesContent":["/**\n * Ecosystem package manifest schema (agent-forge.json), V1.\n *\n * These types describe compatibility facts only. They intentionally do not\n * contain approval, sandbox, credential, or domain-specific policy.\n *\n * Authority: `@agent-forge/plugin-sdk` (D-075 S2); the host re-exports them from\n * its ecosystem contracts module so existing imports keep resolving.\n */\n\nexport type PluginOperatingSystem = \"windows\" | \"macos\" | \"linux\" | \"any\";\nexport type PluginArchitecture = \"x64\" | \"arm64\" | \"any\";\n\nexport interface CapabilityRefV1 {\n\treadonly id: string;\n\t/** Exact capability schema version. A breaking schema change increments it. */\n\treadonly version: number;\n}\n\nexport interface RuntimeConstraintV1 {\n\treadonly name: string;\n\treadonly minVersion?: string;\n\treadonly maxVersion?: string;\n}\n\nexport interface PluginAdapterManifestV1 {\n\treadonly id: string;\n\treadonly version: string;\n\treadonly os: readonly PluginOperatingSystem[];\n\treadonly arch?: readonly PluginArchitecture[];\n\treadonly hostFeatures?: readonly string[];\n}\n\nexport interface PluginPlatformBindingV1 {\n\treadonly os: readonly PluginOperatingSystem[];\n\treadonly arch?: readonly PluginArchitecture[];\n\treadonly runtime?: readonly RuntimeConstraintV1[];\n\treadonly hostFeatures?: readonly string[];\n\treadonly adapters?: readonly PluginAdapterManifestV1[];\n}\n\nexport interface CapabilityRequirementV1 extends CapabilityRefV1 {\n\treadonly optional?: boolean;\n}\n\n/** Versioned package manifest consumed by the deterministic resolver. */\nexport interface PluginManifestV1 {\n\treadonly id: string;\n\t/** Package release version (normally MAJOR.MINOR.PATCH). */\n\treadonly pluginVersion: string;\n\t/** Public host API version required by this package. */\n\treadonly apiVersion: string;\n\t/** Minimum host version required to load this package; the host must be >= this version. */\n\treadonly minHostVersion?: string;\n\t/** Maximum host version supported by this package; the host must be <= this version. */\n\treadonly maxHostVersion?: string;\n\treadonly capabilityRefs?: readonly CapabilityRefV1[];\n\treadonly requires?: readonly CapabilityRequirementV1[];\n\treadonly platform?: PluginPlatformBindingV1;\n\t/** A contract/mock package that must never be selected for a production Profile. */\n\treadonly testOnly?: boolean;\n}\n"]}

package/dist/ecosystem-manifest.js

@@ -0,0 +1,11 @@
+/**
+ * Ecosystem package manifest schema (agent-forge.json), V1.
+ *
+ * These types describe compatibility facts only. They intentionally do not
+ * contain approval, sandbox, credential, or domain-specific policy.
+ *
+ * Authority: `@agent-forge/plugin-sdk` (D-075 S2); the host re-exports them from
+ * its ecosystem contracts module so existing imports keep resolving.
+ */
+export {};
+//# sourceMappingURL=ecosystem-manifest.js.map

package/dist/ecosystem-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecosystem-manifest.js","sourceRoot":"","sources":["../src/ecosystem-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * Ecosystem package manifest schema (agent-forge.json), V1.\n *\n * These types describe compatibility facts only. They intentionally do not\n * contain approval, sandbox, credential, or domain-specific policy.\n *\n * Authority: `@agent-forge/plugin-sdk` (D-075 S2); the host re-exports them from\n * its ecosystem contracts module so existing imports keep resolving.\n */\n\nexport type PluginOperatingSystem = \"windows\" | \"macos\" | \"linux\" | \"any\";\nexport type PluginArchitecture = \"x64\" | \"arm64\" | \"any\";\n\nexport interface CapabilityRefV1 {\n\treadonly id: string;\n\t/** Exact capability schema version. A breaking schema change increments it. */\n\treadonly version: number;\n}\n\nexport interface RuntimeConstraintV1 {\n\treadonly name: string;\n\treadonly minVersion?: string;\n\treadonly maxVersion?: string;\n}\n\nexport interface PluginAdapterManifestV1 {\n\treadonly id: string;\n\treadonly version: string;\n\treadonly os: readonly PluginOperatingSystem[];\n\treadonly arch?: readonly PluginArchitecture[];\n\treadonly hostFeatures?: readonly string[];\n}\n\nexport interface PluginPlatformBindingV1 {\n\treadonly os: readonly PluginOperatingSystem[];\n\treadonly arch?: readonly PluginArchitecture[];\n\treadonly runtime?: readonly RuntimeConstraintV1[];\n\treadonly hostFeatures?: readonly string[];\n\treadonly adapters?: readonly PluginAdapterManifestV1[];\n}\n\nexport interface CapabilityRequirementV1 extends CapabilityRefV1 {\n\treadonly optional?: boolean;\n}\n\n/** Versioned package manifest consumed by the deterministic resolver. */\nexport interface PluginManifestV1 {\n\treadonly id: string;\n\t/** Package release version (normally MAJOR.MINOR.PATCH). */\n\treadonly pluginVersion: string;\n\t/** Public host API version required by this package. */\n\treadonly apiVersion: string;\n\t/** Minimum host version required to load this package; the host must be >= this version. */\n\treadonly minHostVersion?: string;\n\t/** Maximum host version supported by this package; the host must be <= this version. */\n\treadonly maxHostVersion?: string;\n\treadonly capabilityRefs?: readonly CapabilityRefV1[];\n\treadonly requires?: readonly CapabilityRequirementV1[];\n\treadonly platform?: PluginPlatformBindingV1;\n\t/** A contract/mock package that must never be selected for a production Profile. */\n\treadonly testOnly?: boolean;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./artifact.ts";
+export * from "./capability-manifest.ts";
+export * from "./common.ts";
+export * from "./context-budget.ts";
+export * from "./diff.ts";
+export * from "./durable.ts";
+export * from "./ecosystem-manifest.ts";
+export * from "./memory.ts";
+export * from "./observability.ts";
+export * from "./operation.ts";
+export * from "./public-api.ts";
+export * from "./render.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC","sourcesContent":["export * from \"./artifact.ts\";\nexport * from \"./capability-manifest.ts\";\nexport * from \"./common.ts\";\nexport * from \"./context-budget.ts\";\nexport * from \"./diff.ts\";\nexport * from \"./durable.ts\";\nexport * from \"./ecosystem-manifest.ts\";\nexport * from \"./memory.ts\";\nexport * from \"./observability.ts\";\nexport * from \"./operation.ts\";\nexport * from \"./public-api.ts\";\nexport * from \"./render.ts\";\n"]}

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./artifact.js";
+export * from "./capability-manifest.js";
+export * from "./common.js";
+export * from "./context-budget.js";
+export * from "./diff.js";
+export * from "./durable.js";
+export * from "./ecosystem-manifest.js";
+export * from "./memory.js";
+export * from "./observability.js";
+export * from "./operation.js";
+export * from "./public-api.js";
+export * from "./render.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC","sourcesContent":["export * from \"./artifact.ts\";\nexport * from \"./capability-manifest.ts\";\nexport * from \"./common.ts\";\nexport * from \"./context-budget.ts\";\nexport * from \"./diff.ts\";\nexport * from \"./durable.ts\";\nexport * from \"./ecosystem-manifest.ts\";\nexport * from \"./memory.ts\";\nexport * from \"./observability.ts\";\nexport * from \"./operation.ts\";\nexport * from \"./public-api.ts\";\nexport * from \"./render.ts\";\n"]}

package/dist/memory.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Public contracts for the first-party memory capability (M5 Memory
+ * Foundation + the builtin memory family). The plugin package
+ * (`@agent-forge/plugin-memory`) is the implementation; this module is the
+ * single authoring authority for its public types and the host-facing storage
+ * injection contract. The host re-exports the surface from its historical
+ * module paths so existing imports keep resolving.
+ *
+ * Types only, plus the `MEMORY_RECALL_TOOL_NAME` contract constant: the
+ * recall tool name is pinned here because the host's B1 auto-recall path
+ * calls it by name (`runtime.invokeTool`) and replacement memory backends
+ * take over the same link by registering the same-named tool.
+ *
+ * Authority moved from the host's `capabilities/memory.ts` and
+ * `src/memory/*` (D-075 S4 fourth batch, first slice): every symbol below is
+ * a verbatim structural copy of its host definition; the transitive type
+ * chain (canonical atom, store, ledger, vector components) migrated with it
+ * so plugin authors never import host internals.
+ */
+import type { JsonValue } from "./common.ts";
+/** 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.
+ * Field semantics follow `docs/design/记忆系统设计.md` §4 (记录模型), which is
+ * the authoritative source for memory fields.
+ */
+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. Absent 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.
+     */
+    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;
+}
+/**
+ * Skipped-record counters attached to suite-scoped reads. The read boundary is
+ * lazy and observable: 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;
+}
+export interface MemoryStoreCommitOptions {
+    /** Overrides the atom's retentionMode id at commit time (policy-selected). */
+    readonly retentionModeId?: string;
+}
+/** A committed atom plus the store-assigned bookkeeping facts. */
+export interface CommittedMemoryV1<TPayload extends JsonValue = JsonValue> {
+    readonly atom: MemoryAtomV1<TPayload>;
+    /** Monotonic across the whole store. */
+    readonly storeRevision: number;
+    /** Monotonic within the atom's scope partition. */
+    readonly scopeRevision: number;
+    readonly committedAt: number;
+    /** Recall deadline computed from the retention registry. Absent = no expiry. */
+    readonly purgeAt?: number;
+    readonly retentionModeId: string;
+}
+export interface MemoryStoreQuery {
+    readonly owner: string;
+    /**
+     * Suite-scoped read boundary. When set, only atoms whose suiteId equals
+     * this value — plus explicitly promoted user-default preferences — are
+     * visible; legacy (suiteId-less) atoms are skipped fail-safe. When absent,
+     * no suite filtering happens (suite-unscoped read).
+     */
+    readonly suiteId?: string;
+}
+export interface MemoryStoreStats {
+    readonly active: number;
+    readonly expired: number;
+    readonly byScope: Readonly<Record<MemoryScopeV1, {
+        active: number;
+        expired: number;
+    }>>;
+}
+/** Result of `MemoryStoreV1.listForSuite`: visible records plus skip counters. */
+export interface MemoryStoreSuitePageV1 {
+    readonly records: readonly CommittedMemoryV1[];
+    /** Excluded-record counters for the suite read boundary. */
+    readonly filter: MemorySuiteFilterStatsV1;
+}
+export interface MemoryStoreV1 {
+    commit(atom: MemoryAtomV1, options?: MemoryStoreCommitOptions): CommittedMemoryV1;
+    /**
+     * Returns the record only when unexpired, owned by `query.owner`, and —
+     * when `query.suiteId` is set — visible in that suite (legacy atoms are
+     * invisible to every suite).
+     */
+    get(memoryId: string, query: MemoryStoreQuery): CommittedMemoryV1 | undefined;
+    /** Lists active records owned by `query.owner`, optionally narrowed to one scope. */
+    list(query: MemoryStoreQuery, scope?: MemoryScopeV1): readonly CommittedMemoryV1[];
+    /**
+     * Suite-scoped listing with skip diagnostics: returns the records visible
+     * in `query.suiteId` plus how many legacy and foreign-suite records were
+     * excluded (expired records are excluded before the suite filter and are
+     * not counted here).
+     */
+    listForSuite(query: MemoryStoreQuery & {
+        readonly suiteId: string;
+    }, scope?: MemoryScopeV1): MemoryStoreSuitePageV1;
+    stats(): MemoryStoreStats;
+    /**
+     * Physically removes one record from the canonical in-memory ledger — the
+     * store-side arm of the controlled purge gate (only the purge flow may
+     * destroy committed atoms). Returns true when the record existed.
+     */
+    evict(memoryId: string): boolean;
+}
+/** Result of `DurableMemoryLedgerV1.load`: replayable atoms plus skip diagnostics. */
+export interface DurableMemoryLedgerLoadResultV1 {
+    /** Valid atoms in file order — replay these into a fresh store. */
+    readonly atoms: readonly MemoryAtomV1[];
+    /** Malformed lines (invalid JSON or invalid atoms) skipped during load. */
+    readonly corruptedLines: number;
+    /** Atoms whose memoryId was already loaded (crash windows can duplicate appends). */
+    readonly duplicateSkipped: number;
+    /** True when the file existed but could not be read (permissions, IO error). */
+    readonly unreadable: boolean;
+}
+export interface DurableMemoryLedgerV1 {
+    /**
+     * Reads the ledger file and returns the replayable atom set plus skip
+     * counters. A missing file is an empty ledger, not an error; malformed or
+     * duplicate lines are skipped and counted — load NEVER throws.
+     */
+    load(): DurableMemoryLedgerLoadResultV1;
+    /**
+     * Appends one committed atom as a single JSONL line (strictly validated).
+     * The write serializes against other processes through the `.lock` sibling
+     * file and is fsynced before close, so an acknowledged append survives a
+     * hard crash; a lock timeout or IO failure throws (an append never fails
+     * silently).
+     */
+    append(atom: MemoryAtomV1): void;
+    /**
+     * Physically rewrites the whole file with the given atoms (atomic tmp-file
+     * + rename). The forget/purge flow calls this after removing atoms so the
+     * durable replica matches the surviving canonical set.
+     */
+    rewrite(atoms: readonly MemoryAtomV1[]): void;
+    /** The ledger's current in-memory atom set (append/rewrite keep it in sync). */
+    atomsSnapshot(): readonly MemoryAtomV1[];
+}
+/**
+ * Batch embedding provider. Implementations must be deterministic for
+ * identical input and must not silently degrade: any failure propagates.
+ */
+export interface MemoryEmbeddingProviderV1 {
+    readonly modelId: string;
+    readonly dimensions: number;
+    /**
+     * Batch embed. Vectors are L2-normalized float arrays. Deterministic for
+     * identical input. Plain text mapping — no instruction prefix is added
+     * here; query-side instructions for bge-small-zh family are the caller's
+     * responsibility.
+     */
+    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
+}
+/**
+ * Minimal structural seam around a transformers.js feature-extraction
+ * pipeline, so tests can inject a fake without touching the real loader.
+ */
+export interface TransformersEmbeddingBackendV1 {
+    /** Extract features for a batch of texts; one vector per input, input order. */
+    extract: (texts: string[]) => Promise<{
+        toList: () => number[][];
+    }>;
+}
+export type TransformersEmbeddingLoadImpl = (modelId: string, cacheDir: string, remoteHost: string) => Promise<TransformersEmbeddingBackendV1>;
+/**
+ * Cross-encoder reranker. Higher score = more relevant; raw logits are only
+ * order-preserving, not calibrated probabilities.
+ */
+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>;
+/** Stored-row shape for one vector-channel upsert. */
+export interface MemoryVectorIndexEntryV1 {
+    readonly memoryId: string;
+    readonly owner: string;
+    readonly modelId: string;
+    readonly statement: string;
+    readonly tags: readonly string[];
+    readonly vector: readonly number[];
+}
+export interface MemoryVectorIndexQueryV1 {
+    readonly owner: string;
+    readonly limit: number;
+}
+export interface MemoryVectorHitV1 {
+    readonly memoryId: string;
+    readonly score: number;
+}
+export interface MemoryVectorIndexV1 {
+    readonly replicaId: "memory-vector-index";
+    upsert(entries: readonly MemoryVectorIndexEntryV1[]): Promise<void>;
+    remove(memoryIds: readonly string[]): Promise<void>;
+    queryKnn(vector: readonly number[], query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;
+    queryFts(queryText: string, query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;
+    listMemoryIds(): Promise<ReadonlySet<string>>;
+    count(): Promise<number>;
+    getStoredModelId(): Promise<string | undefined>;
+    close(): Promise<void>;
+}
+/** 全局记忆档位: off = 家族不注册; light/full = 档位 + 开启意图。 */
+export type MemoryModeV1 = "off" | "light" | "full";
+/**
+ * 契约常量（扩展位盘点 B3）：记忆召回工具名——SDK 的 B1 自动回忆按它调用
+ * （`runtime.invokeTool`），替换记忆后端的插件也以同名工具接管该链路
+ * （registerTool 可替换 + 同名接管）。改名即破坏该公共链路，故名入契约。
+ */
+export declare const MEMORY_RECALL_TOOL_NAME = "memory_recall";
+/**
+ * 测试专用向量组件注入点 (架构宪法: deterministic mock AI 门禁)。注入后召回
+ * 直接进入 ready 并完全由注入组件驱动, 跳过 transformers/lancedb 真实装配;
+ * `reranker` 缺省 = 精排不可用 (跳过精排, 用 RRF 序)。
+ */
+export interface MemoryVectorComponentsOverrideV1 {
+    readonly embedProvider: MemoryEmbeddingProviderV1;
+    readonly reranker?: MemoryRerankerV1;
+    readonly vectorIndex: MemoryVectorIndexV1;
+    readonly queryPrefix?: string;
+}
+/**
+ * 真实装配路径的测试缝 (enabling 状态机测试用): 组件工厂照常构建
+ * (LanceDB 本地、零网络), 仅 transformers 加载被替换。
+ */
+export interface MemoryEnablingOverrideV1 {
+    readonly embeddingLoadImpl?: TransformersEmbeddingLoadImpl;
+    readonly rerankerLoadImpl?: TransformersRerankerLoadImpl;
+}
+/** Capability-level override: full vector components, or enabling-path load seams. */
+export type MemoryCapabilityOverrideV1 = MemoryVectorComponentsOverrideV1 | MemoryEnablingOverrideV1;
+/**
+ * 记忆底层组件注入契约 (扩展位盘点 A1/A2, D-068 增补 1): 宿主 SDK 经
+ * `CreateAgentSessionOptions.memoryCapability.storage`（D-075 S4-4 起经
+ * `HostCapabilities.memoryStorage`）替换记忆的持久化后端与向量组件——
+ * builtin memory 保持记忆语义的编排者 (原子契约/工具面/ledger 生命周期),
+ * 底层实现可换。缺省任一成员 = 内置默认实现, 默认行为零变化。工厂入参只含
+ * 作用域事实 (路径域与时钟), 实现不依赖内核内部布局。
+ */
+export interface MemoryStorageComponentsV1 {
+    /** A1: 记忆原子存取后端 (默认 = 本地内存 store + JSONL ledger 副本语义由 ledger 承担)。 */
+    readonly storeFactory?: (scope: {
+        readonly agentDir: string;
+        readonly owner: string;
+        readonly now: () => number;
+    }) => MemoryStoreV1;
+    /** A1: 持久化副本后端 (默认 = `<agentDir>/memory/<owner>/ledger-<domain>.jsonl`)。 */
+    readonly ledgerFactory?: (scope: {
+        readonly agentDir: string;
+        readonly owner: string;
+        readonly domain: string;
+        readonly now: () => number;
+    }) => DurableMemoryLedgerV1;
+    /** A2: 向量通道组件 (缺省 reranker = 跳过精排, 用 RRF 序)。 */
+    readonly vectorComponents?: MemoryVectorComponentsOverrideV1;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Public contracts for the first-party memory capability (M5 Memory\n * Foundation + the builtin memory family). The plugin package\n * (`@agent-forge/plugin-memory`) is the implementation; this module is the\n * single authoring authority for its public types and the host-facing storage\n * injection contract. The host re-exports the surface from its historical\n * module paths so existing imports keep resolving.\n *\n * Types only, plus the `MEMORY_RECALL_TOOL_NAME` contract constant: the\n * recall tool name is pinned here because the host's B1 auto-recall path\n * calls it by name (`runtime.invokeTool`) and replacement memory backends\n * take over the same link by registering the same-named tool.\n *\n * Authority moved from the host's `capabilities/memory.ts` and\n * `src/memory/*` (D-075 S4 fourth batch, first slice): every symbol below is\n * a verbatim structural copy of its host definition; the transitive type\n * chain (canonical atom, store, ledger, vector components) migrated with it\n * so plugin authors never import host internals.\n */\n\nimport type { JsonValue } from \"./common.ts\";\n\n// ---------------------------------------------------------------------------\n// Canonical atom (host `src/memory/foundation.ts`)\n// ---------------------------------------------------------------------------\n\n/** Source of one memory: where the fact came from, optionally pinned by revision/digest. */\nexport interface MemorySourceRefV1 {\n\treadonly kind: \"session\" | \"entry\" | \"artifact\" | \"tool\" | \"state\";\n\treadonly id: string;\n\treadonly revision?: string;\n\treadonly digest?: string;\n}\n\n/** Namespace-scoped search facet. Facets are atom facts, never derived. */\nexport interface MemoryFacetV1 {\n\treadonly namespace: string;\n\treadonly schemaVersion: number;\n\treadonly key: string;\n\treadonly value: string;\n}\n\n/** Typed relation between atoms. Weights/validity belong to projections, not here. */\nexport interface MemoryRelationV1 {\n\treadonly relationId: string;\n\treadonly namespace: string;\n\treadonly schemaVersion: number;\n\treadonly kind: string;\n\treadonly targetMemoryId?: string;\n\treadonly targetRef?: MemorySourceRefV1;\n\treadonly confidence?: number;\n\treadonly relationRevision: string;\n}\n\nexport interface MemoryTimeRangeV1 {\n\treadonly from?: string;\n\treadonly to?: string;\n}\n\n/** Applicability narrowing; empty means \"applies without narrowing\". */\nexport interface MemoryApplicabilityV1 {\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n\treadonly timeRange?: MemoryTimeRangeV1;\n\treadonly exceptions?: readonly string[];\n}\n\n/** Preference envelope: the generic schema frozen for 1C; policy semantics come later. */\nexport interface MemoryPreferenceEnvelopeV1 {\n\treadonly subject: \"user\" | \"project\" | \"task\" | \"environment\";\n\treadonly key: string;\n\treadonly preferredValue: JsonValue;\n\treadonly alternatives?: readonly JsonValue[];\n\treadonly scope: {\n\t\treadonly level: \"task\" | \"project\" | \"scene\" | \"timeRange\" | \"profile-private\" | \"user-default\";\n\t\treadonly scenes?: readonly string[];\n\t\treadonly projects?: readonly string[];\n\t\treadonly tasks?: readonly string[];\n\t\treadonly timeRange?: MemoryTimeRangeV1;\n\t\treadonly exceptions?: readonly string[];\n\t};\n\treadonly evidence: {\n\t\treadonly class: \"explicit\" | \"repeated_behavior\" | \"inferred\";\n\t\treadonly sourceRefs: readonly MemorySourceRefV1[];\n\t\treadonly confidence: number;\n\t};\n\treadonly applicabilityConfidence: number;\n\treadonly confirmedAt?: string;\n}\n\n/** Provenance for synthesis/compaction memories derived from other atoms. */\nexport interface MemoryProvenanceV1 {\n\treadonly sourceMemoryIds: readonly string[];\n\treadonly purgeGroupId: string;\n\treadonly containsSourceContent: boolean;\n}\n\nexport type MemoryScopeV1 = \"session\" | \"cycle\" | \"long-term\";\nexport type MemoryKindV1 =\n\t| \"observation\"\n\t| \"preference\"\n\t| \"fact\"\n\t| \"decision\"\n\t| \"constraint\"\n\t| \"inference\"\n\t| \"synthesis\";\nexport type MemoryEvidenceClassV1 = \"explicit\" | \"repeated_behavior\" | \"tool_or_test\" | \"derived\";\n\n/**\n * The immutable canonical atom. Once committed, no field may change in place.\n * Field semantics follow `docs/design/记忆系统设计.md` §4 (记录模型), which is\n * the authoritative source for memory fields.\n */\nexport interface MemoryAtomV1<TPayload = JsonValue> {\n\treadonly memoryId: string;\n\treadonly contractVersion: string;\n\treadonly schemaVersion: number;\n\treadonly scope: MemoryScopeV1;\n\treadonly retentionMode: string;\n\treadonly owner: string;\n\treadonly profileId: string;\n\treadonly shareGroupId?: string;\n\t/**\n\t * Suite (方案) this atom belongs to. Absent marks a legacy pre-M5 atom:\n\t * such atoms are fail-safe INVISIBLE to every suite-scoped read and only\n\t * readable through suite-unscoped queries. The one cross-suite exception\n\t * is an explicitly promoted user-default preference.\n\t */\n\treadonly suiteId?: string;\n\treadonly retentionPolicyVersion: string;\n\treadonly memoryKind: MemoryKindV1;\n\treadonly payload: TPayload;\n\treadonly preference?: MemoryPreferenceEnvelopeV1;\n\treadonly occurredAt: string;\n\treadonly recordedAt: string;\n\treadonly sourceRefs: readonly MemorySourceRefV1[];\n\treadonly observationId: string;\n\treadonly sessionRefs: readonly string[];\n\treadonly agentInstanceRefs: readonly string[];\n\treadonly projectRefs: readonly string[];\n\treadonly subjectRefs: readonly string[];\n\treadonly facets: readonly MemoryFacetV1[];\n\treadonly relations: readonly MemoryRelationV1[];\n\treadonly provenance?: MemoryProvenanceV1;\n\treadonly confidence: number;\n\treadonly importance: number;\n\treadonly applicability?: MemoryApplicabilityV1;\n\treadonly evidenceClass: MemoryEvidenceClassV1;\n\treadonly contentRevision: string;\n\treadonly writeReason: string;\n}\n\n/**\n * Skipped-record counters attached to suite-scoped reads. The read boundary is\n * lazy and observable: excluded atoms are counted, never silently dropped.\n */\nexport interface MemorySuiteFilterStatsV1 {\n\t/** Legacy (suiteId-less) atoms skipped as invisible to any suite. */\n\treadonly legacySkipped: number;\n\t/** Atoms bound to a different suiteId that were skipped. */\n\treadonly foreignSuiteSkipped: number;\n}\n\n// ---------------------------------------------------------------------------\n// Three-scope store (host `src/memory/store.ts`)\n// ---------------------------------------------------------------------------\n\nexport interface MemoryStoreCommitOptions {\n\t/** Overrides the atom's retentionMode id at commit time (policy-selected). */\n\treadonly retentionModeId?: string;\n}\n\n/** A committed atom plus the store-assigned bookkeeping facts. */\nexport interface CommittedMemoryV1<TPayload extends JsonValue = JsonValue> {\n\treadonly atom: MemoryAtomV1<TPayload>;\n\t/** Monotonic across the whole store. */\n\treadonly storeRevision: number;\n\t/** Monotonic within the atom's scope partition. */\n\treadonly scopeRevision: number;\n\treadonly committedAt: number;\n\t/** Recall deadline computed from the retention registry. Absent = no expiry. */\n\treadonly purgeAt?: number;\n\treadonly retentionModeId: string;\n}\n\nexport interface MemoryStoreQuery {\n\treadonly owner: string;\n\t/**\n\t * Suite-scoped read boundary. When set, only atoms whose suiteId equals\n\t * this value — plus explicitly promoted user-default preferences — are\n\t * visible; legacy (suiteId-less) atoms are skipped fail-safe. When absent,\n\t * no suite filtering happens (suite-unscoped read).\n\t */\n\treadonly suiteId?: string;\n}\n\nexport interface MemoryStoreStats {\n\treadonly active: number;\n\treadonly expired: number;\n\treadonly byScope: Readonly<Record<MemoryScopeV1, { active: number; expired: number }>>;\n}\n\n/** Result of `MemoryStoreV1.listForSuite`: visible records plus skip counters. */\nexport interface MemoryStoreSuitePageV1 {\n\treadonly records: readonly CommittedMemoryV1[];\n\t/** Excluded-record counters for the suite read boundary. */\n\treadonly filter: MemorySuiteFilterStatsV1;\n}\n\nexport interface MemoryStoreV1 {\n\tcommit(atom: MemoryAtomV1, options?: MemoryStoreCommitOptions): CommittedMemoryV1;\n\t/**\n\t * Returns the record only when unexpired, owned by `query.owner`, and —\n\t * when `query.suiteId` is set — visible in that suite (legacy atoms are\n\t * invisible to every suite).\n\t */\n\tget(memoryId: string, query: MemoryStoreQuery): CommittedMemoryV1 | undefined;\n\t/** Lists active records owned by `query.owner`, optionally narrowed to one scope. */\n\tlist(query: MemoryStoreQuery, scope?: MemoryScopeV1): readonly CommittedMemoryV1[];\n\t/**\n\t * Suite-scoped listing with skip diagnostics: returns the records visible\n\t * in `query.suiteId` plus how many legacy and foreign-suite records were\n\t * excluded (expired records are excluded before the suite filter and are\n\t * not counted here).\n\t */\n\tlistForSuite(query: MemoryStoreQuery & { readonly suiteId: string }, scope?: MemoryScopeV1): MemoryStoreSuitePageV1;\n\tstats(): MemoryStoreStats;\n\t/**\n\t * Physically removes one record from the canonical in-memory ledger — the\n\t * store-side arm of the controlled purge gate (only the purge flow may\n\t * destroy committed atoms). Returns true when the record existed.\n\t */\n\tevict(memoryId: string): boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Durable ledger replica (host `src/memory/ledger.ts`)\n// ---------------------------------------------------------------------------\n\n/** Result of `DurableMemoryLedgerV1.load`: replayable atoms plus skip diagnostics. */\nexport interface DurableMemoryLedgerLoadResultV1 {\n\t/** Valid atoms in file order — replay these into a fresh store. */\n\treadonly atoms: readonly MemoryAtomV1[];\n\t/** Malformed lines (invalid JSON or invalid atoms) skipped during load. */\n\treadonly corruptedLines: number;\n\t/** Atoms whose memoryId was already loaded (crash windows can duplicate appends). */\n\treadonly duplicateSkipped: number;\n\t/** True when the file existed but could not be read (permissions, IO error). */\n\treadonly unreadable: boolean;\n}\n\nexport interface DurableMemoryLedgerV1 {\n\t/**\n\t * Reads the ledger file and returns the replayable atom set plus skip\n\t * counters. A missing file is an empty ledger, not an error; malformed or\n\t * duplicate lines are skipped and counted — load NEVER throws.\n\t */\n\tload(): DurableMemoryLedgerLoadResultV1;\n\t/**\n\t * Appends one committed atom as a single JSONL line (strictly validated).\n\t * The write serializes against other processes through the `.lock` sibling\n\t * file and is fsynced before close, so an acknowledged append survives a\n\t * hard crash; a lock timeout or IO failure throws (an append never fails\n\t * silently).\n\t */\n\tappend(atom: MemoryAtomV1): void;\n\t/**\n\t * Physically rewrites the whole file with the given atoms (atomic tmp-file\n\t * + rename). The forget/purge flow calls this after removing atoms so the\n\t * durable replica matches the surviving canonical set.\n\t */\n\trewrite(atoms: readonly MemoryAtomV1[]): void;\n\t/** The ledger's current in-memory atom set (append/rewrite keep it in sync). */\n\tatomsSnapshot(): readonly MemoryAtomV1[];\n}\n\n// ---------------------------------------------------------------------------\n// Vector channel components (host `src/memory/{embedding-provider,embedding-reranker,vector-index}.ts`)\n// ---------------------------------------------------------------------------\n\n/**\n * Batch embedding provider. Implementations must be deterministic for\n * identical input and must not silently degrade: any failure propagates.\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.\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\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\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\n/** Stored-row shape for one vector-channel upsert. */\nexport interface MemoryVectorIndexEntryV1 {\n\treadonly memoryId: string;\n\treadonly owner: string;\n\treadonly modelId: string;\n\treadonly statement: string;\n\treadonly tags: readonly string[];\n\treadonly vector: readonly number[];\n}\n\nexport interface MemoryVectorIndexQueryV1 {\n\treadonly owner: string;\n\treadonly limit: number;\n}\n\nexport interface MemoryVectorHitV1 {\n\treadonly memoryId: string;\n\treadonly score: number;\n}\n\nexport interface MemoryVectorIndexV1 {\n\treadonly replicaId: \"memory-vector-index\";\n\tupsert(entries: readonly MemoryVectorIndexEntryV1[]): Promise<void>;\n\tremove(memoryIds: readonly string[]): Promise<void>;\n\tqueryKnn(vector: readonly number[], query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;\n\tqueryFts(queryText: string, query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;\n\tlistMemoryIds(): Promise<ReadonlySet<string>>;\n\tcount(): Promise<number>;\n\tgetStoredModelId(): Promise<string | undefined>;\n\tclose(): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Capability contracts (host `capabilities/memory.ts`)\n// ---------------------------------------------------------------------------\n\n/** 全局记忆档位: off = 家族不注册; light/full = 档位 + 开启意图。 */\nexport type MemoryModeV1 = \"off\" | \"light\" | \"full\";\n\n/**\n * 契约常量（扩展位盘点 B3）：记忆召回工具名——SDK 的 B1 自动回忆按它调用\n * （`runtime.invokeTool`），替换记忆后端的插件也以同名工具接管该链路\n * （registerTool 可替换 + 同名接管）。改名即破坏该公共链路，故名入契约。\n */\nexport const MEMORY_RECALL_TOOL_NAME = \"memory_recall\";\n\n/**\n * 测试专用向量组件注入点 (架构宪法: deterministic mock AI 门禁)。注入后召回\n * 直接进入 ready 并完全由注入组件驱动, 跳过 transformers/lancedb 真实装配;\n * `reranker` 缺省 = 精排不可用 (跳过精排, 用 RRF 序)。\n */\nexport interface MemoryVectorComponentsOverrideV1 {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker?: MemoryRerankerV1;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n\treadonly queryPrefix?: string;\n}\n\n/**\n * 真实装配路径的测试缝 (enabling 状态机测试用): 组件工厂照常构建\n * (LanceDB 本地、零网络), 仅 transformers 加载被替换。\n */\nexport interface MemoryEnablingOverrideV1 {\n\treadonly embeddingLoadImpl?: TransformersEmbeddingLoadImpl;\n\treadonly rerankerLoadImpl?: TransformersRerankerLoadImpl;\n}\n\n/** Capability-level override: full vector components, or enabling-path load seams. */\nexport type MemoryCapabilityOverrideV1 = MemoryVectorComponentsOverrideV1 | MemoryEnablingOverrideV1;\n\n/**\n * 记忆底层组件注入契约 (扩展位盘点 A1/A2, D-068 增补 1): 宿主 SDK 经\n * `CreateAgentSessionOptions.memoryCapability.storage`（D-075 S4-4 起经\n * `HostCapabilities.memoryStorage`）替换记忆的持久化后端与向量组件——\n * builtin memory 保持记忆语义的编排者 (原子契约/工具面/ledger 生命周期),\n * 底层实现可换。缺省任一成员 = 内置默认实现, 默认行为零变化。工厂入参只含\n * 作用域事实 (路径域与时钟), 实现不依赖内核内部布局。\n */\nexport interface MemoryStorageComponentsV1 {\n\t/** A1: 记忆原子存取后端 (默认 = 本地内存 store + JSONL ledger 副本语义由 ledger 承担)。 */\n\treadonly storeFactory?: (scope: {\n\t\treadonly agentDir: string;\n\t\treadonly owner: string;\n\t\treadonly now: () => number;\n\t}) => MemoryStoreV1;\n\t/** A1: 持久化副本后端 (默认 = `<agentDir>/memory/<owner>/ledger-<domain>.jsonl`)。 */\n\treadonly ledgerFactory?: (scope: {\n\t\treadonly agentDir: string;\n\t\treadonly owner: string;\n\t\treadonly domain: string;\n\t\treadonly now: () => number;\n\t}) => DurableMemoryLedgerV1;\n\t/** A2: 向量通道组件 (缺省 reranker = 跳过精排, 用 RRF 序)。 */\n\treadonly vectorComponents?: MemoryVectorComponentsOverrideV1;\n}\n"]}

package/dist/memory.js

@@ -0,0 +1,26 @@
+/**
+ * Public contracts for the first-party memory capability (M5 Memory
+ * Foundation + the builtin memory family). The plugin package
+ * (`@agent-forge/plugin-memory`) is the implementation; this module is the
+ * single authoring authority for its public types and the host-facing storage
+ * injection contract. The host re-exports the surface from its historical
+ * module paths so existing imports keep resolving.
+ *
+ * Types only, plus the `MEMORY_RECALL_TOOL_NAME` contract constant: the
+ * recall tool name is pinned here because the host's B1 auto-recall path
+ * calls it by name (`runtime.invokeTool`) and replacement memory backends
+ * take over the same link by registering the same-named tool.
+ *
+ * Authority moved from the host's `capabilities/memory.ts` and
+ * `src/memory/*` (D-075 S4 fourth batch, first slice): every symbol below is
+ * a verbatim structural copy of its host definition; the transitive type
+ * chain (canonical atom, store, ledger, vector components) migrated with it
+ * so plugin authors never import host internals.
+ */
+/**
+ * 契约常量（扩展位盘点 B3）：记忆召回工具名——SDK 的 B1 自动回忆按它调用
+ * （`runtime.invokeTool`），替换记忆后端的插件也以同名工具接管该链路
+ * （registerTool 可替换 + 同名接管）。改名即破坏该公共链路，故名入契约。
+ */
+export const MEMORY_RECALL_TOOL_NAME = "memory_recall";
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsWH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC","sourcesContent":["/**\n * Public contracts for the first-party memory capability (M5 Memory\n * Foundation + the builtin memory family). The plugin package\n * (`@agent-forge/plugin-memory`) is the implementation; this module is the\n * single authoring authority for its public types and the host-facing storage\n * injection contract. The host re-exports the surface from its historical\n * module paths so existing imports keep resolving.\n *\n * Types only, plus the `MEMORY_RECALL_TOOL_NAME` contract constant: the\n * recall tool name is pinned here because the host's B1 auto-recall path\n * calls it by name (`runtime.invokeTool`) and replacement memory backends\n * take over the same link by registering the same-named tool.\n *\n * Authority moved from the host's `capabilities/memory.ts` and\n * `src/memory/*` (D-075 S4 fourth batch, first slice): every symbol below is\n * a verbatim structural copy of its host definition; the transitive type\n * chain (canonical atom, store, ledger, vector components) migrated with it\n * so plugin authors never import host internals.\n */\n\nimport type { JsonValue } from \"./common.ts\";\n\n// ---------------------------------------------------------------------------\n// Canonical atom (host `src/memory/foundation.ts`)\n// ---------------------------------------------------------------------------\n\n/** Source of one memory: where the fact came from, optionally pinned by revision/digest. */\nexport interface MemorySourceRefV1 {\n\treadonly kind: \"session\" | \"entry\" | \"artifact\" | \"tool\" | \"state\";\n\treadonly id: string;\n\treadonly revision?: string;\n\treadonly digest?: string;\n}\n\n/** Namespace-scoped search facet. Facets are atom facts, never derived. */\nexport interface MemoryFacetV1 {\n\treadonly namespace: string;\n\treadonly schemaVersion: number;\n\treadonly key: string;\n\treadonly value: string;\n}\n\n/** Typed relation between atoms. Weights/validity belong to projections, not here. */\nexport interface MemoryRelationV1 {\n\treadonly relationId: string;\n\treadonly namespace: string;\n\treadonly schemaVersion: number;\n\treadonly kind: string;\n\treadonly targetMemoryId?: string;\n\treadonly targetRef?: MemorySourceRefV1;\n\treadonly confidence?: number;\n\treadonly relationRevision: string;\n}\n\nexport interface MemoryTimeRangeV1 {\n\treadonly from?: string;\n\treadonly to?: string;\n}\n\n/** Applicability narrowing; empty means \"applies without narrowing\". */\nexport interface MemoryApplicabilityV1 {\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n\treadonly timeRange?: MemoryTimeRangeV1;\n\treadonly exceptions?: readonly string[];\n}\n\n/** Preference envelope: the generic schema frozen for 1C; policy semantics come later. */\nexport interface MemoryPreferenceEnvelopeV1 {\n\treadonly subject: \"user\" | \"project\" | \"task\" | \"environment\";\n\treadonly key: string;\n\treadonly preferredValue: JsonValue;\n\treadonly alternatives?: readonly JsonValue[];\n\treadonly scope: {\n\t\treadonly level: \"task\" | \"project\" | \"scene\" | \"timeRange\" | \"profile-private\" | \"user-default\";\n\t\treadonly scenes?: readonly string[];\n\t\treadonly projects?: readonly string[];\n\t\treadonly tasks?: readonly string[];\n\t\treadonly timeRange?: MemoryTimeRangeV1;\n\t\treadonly exceptions?: readonly string[];\n\t};\n\treadonly evidence: {\n\t\treadonly class: \"explicit\" | \"repeated_behavior\" | \"inferred\";\n\t\treadonly sourceRefs: readonly MemorySourceRefV1[];\n\t\treadonly confidence: number;\n\t};\n\treadonly applicabilityConfidence: number;\n\treadonly confirmedAt?: string;\n}\n\n/** Provenance for synthesis/compaction memories derived from other atoms. */\nexport interface MemoryProvenanceV1 {\n\treadonly sourceMemoryIds: readonly string[];\n\treadonly purgeGroupId: string;\n\treadonly containsSourceContent: boolean;\n}\n\nexport type MemoryScopeV1 = \"session\" | \"cycle\" | \"long-term\";\nexport type MemoryKindV1 =\n\t| \"observation\"\n\t| \"preference\"\n\t| \"fact\"\n\t| \"decision\"\n\t| \"constraint\"\n\t| \"inference\"\n\t| \"synthesis\";\nexport type MemoryEvidenceClassV1 = \"explicit\" | \"repeated_behavior\" | \"tool_or_test\" | \"derived\";\n\n/**\n * The immutable canonical atom. Once committed, no field may change in place.\n * Field semantics follow `docs/design/记忆系统设计.md` §4 (记录模型), which is\n * the authoritative source for memory fields.\n */\nexport interface MemoryAtomV1<TPayload = JsonValue> {\n\treadonly memoryId: string;\n\treadonly contractVersion: string;\n\treadonly schemaVersion: number;\n\treadonly scope: MemoryScopeV1;\n\treadonly retentionMode: string;\n\treadonly owner: string;\n\treadonly profileId: string;\n\treadonly shareGroupId?: string;\n\t/**\n\t * Suite (方案) this atom belongs to. Absent marks a legacy pre-M5 atom:\n\t * such atoms are fail-safe INVISIBLE to every suite-scoped read and only\n\t * readable through suite-unscoped queries. The one cross-suite exception\n\t * is an explicitly promoted user-default preference.\n\t */\n\treadonly suiteId?: string;\n\treadonly retentionPolicyVersion: string;\n\treadonly memoryKind: MemoryKindV1;\n\treadonly payload: TPayload;\n\treadonly preference?: MemoryPreferenceEnvelopeV1;\n\treadonly occurredAt: string;\n\treadonly recordedAt: string;\n\treadonly sourceRefs: readonly MemorySourceRefV1[];\n\treadonly observationId: string;\n\treadonly sessionRefs: readonly string[];\n\treadonly agentInstanceRefs: readonly string[];\n\treadonly projectRefs: readonly string[];\n\treadonly subjectRefs: readonly string[];\n\treadonly facets: readonly MemoryFacetV1[];\n\treadonly relations: readonly MemoryRelationV1[];\n\treadonly provenance?: MemoryProvenanceV1;\n\treadonly confidence: number;\n\treadonly importance: number;\n\treadonly applicability?: MemoryApplicabilityV1;\n\treadonly evidenceClass: MemoryEvidenceClassV1;\n\treadonly contentRevision: string;\n\treadonly writeReason: string;\n}\n\n/**\n * Skipped-record counters attached to suite-scoped reads. The read boundary is\n * lazy and observable: excluded atoms are counted, never silently dropped.\n */\nexport interface MemorySuiteFilterStatsV1 {\n\t/** Legacy (suiteId-less) atoms skipped as invisible to any suite. */\n\treadonly legacySkipped: number;\n\t/** Atoms bound to a different suiteId that were skipped. */\n\treadonly foreignSuiteSkipped: number;\n}\n\n// ---------------------------------------------------------------------------\n// Three-scope store (host `src/memory/store.ts`)\n// ---------------------------------------------------------------------------\n\nexport interface MemoryStoreCommitOptions {\n\t/** Overrides the atom's retentionMode id at commit time (policy-selected). */\n\treadonly retentionModeId?: string;\n}\n\n/** A committed atom plus the store-assigned bookkeeping facts. */\nexport interface CommittedMemoryV1<TPayload extends JsonValue = JsonValue> {\n\treadonly atom: MemoryAtomV1<TPayload>;\n\t/** Monotonic across the whole store. */\n\treadonly storeRevision: number;\n\t/** Monotonic within the atom's scope partition. */\n\treadonly scopeRevision: number;\n\treadonly committedAt: number;\n\t/** Recall deadline computed from the retention registry. Absent = no expiry. */\n\treadonly purgeAt?: number;\n\treadonly retentionModeId: string;\n}\n\nexport interface MemoryStoreQuery {\n\treadonly owner: string;\n\t/**\n\t * Suite-scoped read boundary. When set, only atoms whose suiteId equals\n\t * this value — plus explicitly promoted user-default preferences — are\n\t * visible; legacy (suiteId-less) atoms are skipped fail-safe. When absent,\n\t * no suite filtering happens (suite-unscoped read).\n\t */\n\treadonly suiteId?: string;\n}\n\nexport interface MemoryStoreStats {\n\treadonly active: number;\n\treadonly expired: number;\n\treadonly byScope: Readonly<Record<MemoryScopeV1, { active: number; expired: number }>>;\n}\n\n/** Result of `MemoryStoreV1.listForSuite`: visible records plus skip counters. */\nexport interface MemoryStoreSuitePageV1 {\n\treadonly records: readonly CommittedMemoryV1[];\n\t/** Excluded-record counters for the suite read boundary. */\n\treadonly filter: MemorySuiteFilterStatsV1;\n}\n\nexport interface MemoryStoreV1 {\n\tcommit(atom: MemoryAtomV1, options?: MemoryStoreCommitOptions): CommittedMemoryV1;\n\t/**\n\t * Returns the record only when unexpired, owned by `query.owner`, and —\n\t * when `query.suiteId` is set — visible in that suite (legacy atoms are\n\t * invisible to every suite).\n\t */\n\tget(memoryId: string, query: MemoryStoreQuery): CommittedMemoryV1 | undefined;\n\t/** Lists active records owned by `query.owner`, optionally narrowed to one scope. */\n\tlist(query: MemoryStoreQuery, scope?: MemoryScopeV1): readonly CommittedMemoryV1[];\n\t/**\n\t * Suite-scoped listing with skip diagnostics: returns the records visible\n\t * in `query.suiteId` plus how many legacy and foreign-suite records were\n\t * excluded (expired records are excluded before the suite filter and are\n\t * not counted here).\n\t */\n\tlistForSuite(query: MemoryStoreQuery & { readonly suiteId: string }, scope?: MemoryScopeV1): MemoryStoreSuitePageV1;\n\tstats(): MemoryStoreStats;\n\t/**\n\t * Physically removes one record from the canonical in-memory ledger — the\n\t * store-side arm of the controlled purge gate (only the purge flow may\n\t * destroy committed atoms). Returns true when the record existed.\n\t */\n\tevict(memoryId: string): boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Durable ledger replica (host `src/memory/ledger.ts`)\n// ---------------------------------------------------------------------------\n\n/** Result of `DurableMemoryLedgerV1.load`: replayable atoms plus skip diagnostics. */\nexport interface DurableMemoryLedgerLoadResultV1 {\n\t/** Valid atoms in file order — replay these into a fresh store. */\n\treadonly atoms: readonly MemoryAtomV1[];\n\t/** Malformed lines (invalid JSON or invalid atoms) skipped during load. */\n\treadonly corruptedLines: number;\n\t/** Atoms whose memoryId was already loaded (crash windows can duplicate appends). */\n\treadonly duplicateSkipped: number;\n\t/** True when the file existed but could not be read (permissions, IO error). */\n\treadonly unreadable: boolean;\n}\n\nexport interface DurableMemoryLedgerV1 {\n\t/**\n\t * Reads the ledger file and returns the replayable atom set plus skip\n\t * counters. A missing file is an empty ledger, not an error; malformed or\n\t * duplicate lines are skipped and counted — load NEVER throws.\n\t */\n\tload(): DurableMemoryLedgerLoadResultV1;\n\t/**\n\t * Appends one committed atom as a single JSONL line (strictly validated).\n\t * The write serializes against other processes through the `.lock` sibling\n\t * file and is fsynced before close, so an acknowledged append survives a\n\t * hard crash; a lock timeout or IO failure throws (an append never fails\n\t * silently).\n\t */\n\tappend(atom: MemoryAtomV1): void;\n\t/**\n\t * Physically rewrites the whole file with the given atoms (atomic tmp-file\n\t * + rename). The forget/purge flow calls this after removing atoms so the\n\t * durable replica matches the surviving canonical set.\n\t */\n\trewrite(atoms: readonly MemoryAtomV1[]): void;\n\t/** The ledger's current in-memory atom set (append/rewrite keep it in sync). */\n\tatomsSnapshot(): readonly MemoryAtomV1[];\n}\n\n// ---------------------------------------------------------------------------\n// Vector channel components (host `src/memory/{embedding-provider,embedding-reranker,vector-index}.ts`)\n// ---------------------------------------------------------------------------\n\n/**\n * Batch embedding provider. Implementations must be deterministic for\n * identical input and must not silently degrade: any failure propagates.\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.\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\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\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\n/** Stored-row shape for one vector-channel upsert. */\nexport interface MemoryVectorIndexEntryV1 {\n\treadonly memoryId: string;\n\treadonly owner: string;\n\treadonly modelId: string;\n\treadonly statement: string;\n\treadonly tags: readonly string[];\n\treadonly vector: readonly number[];\n}\n\nexport interface MemoryVectorIndexQueryV1 {\n\treadonly owner: string;\n\treadonly limit: number;\n}\n\nexport interface MemoryVectorHitV1 {\n\treadonly memoryId: string;\n\treadonly score: number;\n}\n\nexport interface MemoryVectorIndexV1 {\n\treadonly replicaId: \"memory-vector-index\";\n\tupsert(entries: readonly MemoryVectorIndexEntryV1[]): Promise<void>;\n\tremove(memoryIds: readonly string[]): Promise<void>;\n\tqueryKnn(vector: readonly number[], query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;\n\tqueryFts(queryText: string, query: MemoryVectorIndexQueryV1): Promise<readonly MemoryVectorHitV1[]>;\n\tlistMemoryIds(): Promise<ReadonlySet<string>>;\n\tcount(): Promise<number>;\n\tgetStoredModelId(): Promise<string | undefined>;\n\tclose(): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Capability contracts (host `capabilities/memory.ts`)\n// ---------------------------------------------------------------------------\n\n/** 全局记忆档位: off = 家族不注册; light/full = 档位 + 开启意图。 */\nexport type MemoryModeV1 = \"off\" | \"light\" | \"full\";\n\n/**\n * 契约常量（扩展位盘点 B3）：记忆召回工具名——SDK 的 B1 自动回忆按它调用\n * （`runtime.invokeTool`），替换记忆后端的插件也以同名工具接管该链路\n * （registerTool 可替换 + 同名接管）。改名即破坏该公共链路，故名入契约。\n */\nexport const MEMORY_RECALL_TOOL_NAME = \"memory_recall\";\n\n/**\n * 测试专用向量组件注入点 (架构宪法: deterministic mock AI 门禁)。注入后召回\n * 直接进入 ready 并完全由注入组件驱动, 跳过 transformers/lancedb 真实装配;\n * `reranker` 缺省 = 精排不可用 (跳过精排, 用 RRF 序)。\n */\nexport interface MemoryVectorComponentsOverrideV1 {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker?: MemoryRerankerV1;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n\treadonly queryPrefix?: string;\n}\n\n/**\n * 真实装配路径的测试缝 (enabling 状态机测试用): 组件工厂照常构建\n * (LanceDB 本地、零网络), 仅 transformers 加载被替换。\n */\nexport interface MemoryEnablingOverrideV1 {\n\treadonly embeddingLoadImpl?: TransformersEmbeddingLoadImpl;\n\treadonly rerankerLoadImpl?: TransformersRerankerLoadImpl;\n}\n\n/** Capability-level override: full vector components, or enabling-path load seams. */\nexport type MemoryCapabilityOverrideV1 = MemoryVectorComponentsOverrideV1 | MemoryEnablingOverrideV1;\n\n/**\n * 记忆底层组件注入契约 (扩展位盘点 A1/A2, D-068 增补 1): 宿主 SDK 经\n * `CreateAgentSessionOptions.memoryCapability.storage`（D-075 S4-4 起经\n * `HostCapabilities.memoryStorage`）替换记忆的持久化后端与向量组件——\n * builtin memory 保持记忆语义的编排者 (原子契约/工具面/ledger 生命周期),\n * 底层实现可换。缺省任一成员 = 内置默认实现, 默认行为零变化。工厂入参只含\n * 作用域事实 (路径域与时钟), 实现不依赖内核内部布局。\n */\nexport interface MemoryStorageComponentsV1 {\n\t/** A1: 记忆原子存取后端 (默认 = 本地内存 store + JSONL ledger 副本语义由 ledger 承担)。 */\n\treadonly storeFactory?: (scope: {\n\t\treadonly agentDir: string;\n\t\treadonly owner: string;\n\t\treadonly now: () => number;\n\t}) => MemoryStoreV1;\n\t/** A1: 持久化副本后端 (默认 = `<agentDir>/memory/<owner>/ledger-<domain>.jsonl`)。 */\n\treadonly ledgerFactory?: (scope: {\n\t\treadonly agentDir: string;\n\t\treadonly owner: string;\n\t\treadonly domain: string;\n\t\treadonly now: () => number;\n\t}) => DurableMemoryLedgerV1;\n\t/** A2: 向量通道组件 (缺省 reranker = 跳过精排, 用 RRF 序)。 */\n\treadonly vectorComponents?: MemoryVectorComponentsOverrideV1;\n}\n"]}