@ai-agent-forge/plugin-memory 0.85.0

package/dist/memory/store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Memory Foundation — three-scope store with revisions, TTL, and retention
+ * inputs (1C.1b).
+ *
+ * Scope decides which partition a committed atom belongs to (session / cycle /
+ * long-term); retention decides how long it stays recallable. Retention mode
+ * IDs are opaque strings resolved through a versioned registry provided by the
+ * Profile — the Foundation never hardcodes business durations. Expired records
+ * lose recall eligibility but are NOT physically purged here (physical purge
+ * is the controlled 1C.6d gate).
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+import type { MemoryAtomV1, MemoryScopeV1, MemorySuiteFilterStatsV1 } from "./foundation.ts";
+/** One retention mode published by a Profile's retention-mode registry. */
+export interface RetentionModeDefinitionV1 {
+    readonly id: string;
+    /** Recall duration in ms. Absent = no expiry (e.g. `permanent`). */
+    readonly durationMs?: number;
+    readonly autoPurge: boolean;
+}
+/** Versioned retention-mode registry snapshot. */
+export interface RetentionModeRegistryV1 {
+    readonly policyVersion: string;
+    readonly modes: readonly RetentionModeDefinitionV1[];
+    get(id: string): RetentionModeDefinitionV1 | undefined;
+}
+/** Validates a retention-mode registry: parseable, finite, non-negative, unique, traceable. */
+export declare function validateRetentionModeRegistry(value: unknown): RetentionModeRegistryV1;
+/** First-party default registry (short/standard/long/permanent). Durations live here, not in Foundation logic. */
+export declare function createFirstPartyRetentionRegistry(): RetentionModeRegistryV1;
+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 (方案系统设计 §6.1/§11). 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 {@link MemoryStoreV1.listForSuite}: visible records plus skip counters. */
+export interface MemoryStoreSuitePageV1 {
+    readonly records: readonly CommittedMemoryV1[];
+    /** Excluded-record counters for the suite read boundary (设计 §11). */
+    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 (设计 §3.3: only the purge
+     * flow may destroy committed atoms). Call it exclusively from the purge
+     * path (suite memory facade / scheduler purge); ordinary business code
+     * never evicts. Returns true when the record existed. Expired-then-evicted
+     * and unexpired records are removed alike; a restart replay cannot
+     * resurrect an evicted atom once the durable replica is rewritten.
+     */
+    evict(memoryId: string): boolean;
+}
+/** Creates a deterministic three-scope Foundation store. Expired records lose recall but stay ledgered. */
+export declare function createMemoryStore(options: {
+    readonly retentionRegistry: RetentionModeRegistryV1;
+    readonly now?: () => number;
+}): MemoryStoreV1;
+//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — three-scope store with revisions, TTL, and retention\n * inputs (1C.1b).\n *\n * Scope decides which partition a committed atom belongs to (session / cycle /\n * long-term); retention decides how long it stays recallable. Retention mode\n * IDs are opaque strings resolved through a versioned registry provided by the\n * Profile — the Foundation never hardcodes business durations. Expired records\n * lose recall eligibility but are NOT physically purged here (physical purge\n * is the controlled 1C.6d gate).\n */\n\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1, MemoryScopeV1, MemorySuiteFilterStatsV1 } from \"./foundation.ts\";\nimport { memorySuiteVisibility, validateMemoryAtomV1 } from \"./foundation.ts\";\n\n/** One retention mode published by a Profile's retention-mode registry. */\nexport interface RetentionModeDefinitionV1 {\n\treadonly id: string;\n\t/** Recall duration in ms. Absent = no expiry (e.g. `permanent`). */\n\treadonly durationMs?: number;\n\treadonly autoPurge: boolean;\n}\n\n/** Versioned retention-mode registry snapshot. */\nexport interface RetentionModeRegistryV1 {\n\treadonly policyVersion: string;\n\treadonly modes: readonly RetentionModeDefinitionV1[];\n\tget(id: string): RetentionModeDefinitionV1 | undefined;\n}\n\n/** Validates a retention-mode registry: parseable, finite, non-negative, unique, traceable. */\nexport function validateRetentionModeRegistry(value: unknown): RetentionModeRegistryV1 {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new Error(\"Retention mode registry must be a plain object\");\n\t}\n\tconst record = value as Record<string, unknown>;\n\tassertNonEmptyString(record.policyVersion, \"Retention mode registry.policyVersion\");\n\tif (!Array.isArray(record.modes) || record.modes.length === 0) {\n\t\tthrow new Error(\"Retention mode registry.modes must be a non-empty array\");\n\t}\n\tconst seen = new Set<string>();\n\tconst modes: RetentionModeDefinitionV1[] = record.modes.map((item, index) => {\n\t\tconst label = `Retention mode[${index}]`;\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item)) {\n\t\t\tthrow new Error(`${label} must be a plain object`);\n\t\t}\n\t\tconst entry = item as Record<string, unknown>;\n\t\tassertNonEmptyString(entry.id, `${label}.id`);\n\t\tif (seen.has(entry.id)) throw new Error(`${label} duplicates id: ${entry.id}`);\n\t\tseen.add(entry.id);\n\t\tif (typeof entry.autoPurge !== \"boolean\") throw new Error(`${label}.autoPurge must be boolean`);\n\t\tif (entry.durationMs !== undefined) {\n\t\t\tif (typeof entry.durationMs !== \"number\" || !Number.isSafeInteger(entry.durationMs) || entry.durationMs <= 0) {\n\t\t\t\tthrow new Error(`${label}.durationMs must be a positive safe integer`);\n\t\t\t}\n\t\t}\n\t\treturn Object.freeze({\n\t\t\tid: entry.id,\n\t\t\t...(entry.durationMs === undefined ? {} : { durationMs: entry.durationMs }),\n\t\t\tautoPurge: entry.autoPurge,\n\t\t});\n\t});\n\treturn Object.freeze({\n\t\tpolicyVersion: record.policyVersion,\n\t\tmodes: Object.freeze(modes),\n\t\tget(id: string) {\n\t\t\treturn modes.find((mode) => mode.id === id);\n\t\t},\n\t});\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\n/** First-party default registry (short/standard/long/permanent). Durations live here, not in Foundation logic. */\nexport function createFirstPartyRetentionRegistry(): RetentionModeRegistryV1 {\n\tconst DAY = 24 * 60 * 60 * 1000;\n\treturn validateRetentionModeRegistry({\n\t\tpolicyVersion: \"retention@1\",\n\t\tmodes: [\n\t\t\t{ id: \"short\", durationMs: 7 * DAY, autoPurge: true },\n\t\t\t{ id: \"standard\", durationMs: 30 * DAY, autoPurge: true },\n\t\t\t{ id: \"long\", durationMs: 365 * DAY, autoPurge: true },\n\t\t\t{ id: \"permanent\", autoPurge: false },\n\t\t],\n\t});\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 (方案系统设计 §6.1/§11). When set, only atoms\n\t * whose suiteId equals this value — plus explicitly promoted user-default\n\t * preferences — are visible; legacy (suiteId-less) atoms are skipped\n\t * fail-safe. When absent, 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 {@link 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 (设计 §11). */\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 (设计 §3.3: only the purge\n\t * flow may destroy committed atoms). Call it exclusively from the purge\n\t * path (suite memory facade / scheduler purge); ordinary business code\n\t * never evicts. Returns true when the record existed. Expired-then-evicted\n\t * and unexpired records are removed alike; a restart replay cannot\n\t * resurrect an evicted atom once the durable replica is rewritten.\n\t */\n\tevict(memoryId: string): boolean;\n}\n\n/** Creates a deterministic three-scope Foundation store. Expired records lose recall but stay ledgered. */\nexport function createMemoryStore(options: {\n\treadonly retentionRegistry: RetentionModeRegistryV1;\n\treadonly now?: () => number;\n}): MemoryStoreV1 {\n\tconst registry = options.retentionRegistry;\n\tconst now = options.now ?? (() => Date.now());\n\tconst records = new Map<string, CommittedMemoryV1>();\n\tlet storeRevision = 0;\n\tconst scopeRevisions = new Map<MemoryScopeV1, number>();\n\n\tconst isExpired = (record: CommittedMemoryV1): boolean => record.purgeAt !== undefined && record.purgeAt <= now();\n\n\tconst requireOwner = (query: MemoryStoreQuery): string => {\n\t\tif (query === null || typeof query !== \"object\" || typeof query.owner !== \"string\" || query.owner.trim() === \"\") {\n\t\t\tthrow new Error(\"Memory store query requires an owner\");\n\t\t}\n\t\tif (query.suiteId !== undefined && (typeof query.suiteId !== \"string\" || query.suiteId.trim() === \"\")) {\n\t\t\tthrow new Error(\"Memory store query requires a non-empty suiteId when filtering by suite\");\n\t\t}\n\t\treturn query.owner;\n\t};\n\n\t/** Suite read boundary: `undefined` query.suiteId means no suite filtering. */\n\tconst isVisibleInSuite = (atom: MemoryAtomV1, suiteId: string | undefined): boolean =>\n\t\tsuiteId === undefined || memorySuiteVisibility(atom, suiteId) === \"visible\";\n\n\treturn {\n\t\tcommit(atom, commitOptions) {\n\t\t\tconst validated = validateMemoryAtomV1(atom);\n\t\t\t// Canonical atoms are immutable once committed (设计 §4): a second\n\t\t\t// commit with the same memoryId is a caller bug and must fail\n\t\t\t// explicitly instead of silently overwriting verified facts.\n\t\t\tif (records.has(validated.memoryId)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Memory already committed: ${validated.memoryId} (canonical atoms are immutable; use the candidate machine for dedupe)`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst modeId = commitOptions?.retentionModeId ?? validated.retentionMode;\n\t\t\tconst mode = registry.get(modeId);\n\t\t\tif (!mode) throw new Error(`Retention mode is not registered: ${modeId}`);\n\t\t\tstoreRevision += 1;\n\t\t\tconst scopeRevision = (scopeRevisions.get(validated.scope) ?? 0) + 1;\n\t\t\tscopeRevisions.set(validated.scope, scopeRevision);\n\t\t\tconst committedAt = now();\n\t\t\tconst committed: CommittedMemoryV1 = Object.freeze({\n\t\t\t\tatom: validated,\n\t\t\t\tstoreRevision,\n\t\t\t\tscopeRevision,\n\t\t\t\tcommittedAt,\n\t\t\t\t...(mode.durationMs === undefined ? {} : { purgeAt: committedAt + mode.durationMs }),\n\t\t\t\tretentionModeId: mode.id,\n\t\t\t});\n\t\t\trecords.set(validated.memoryId, committed);\n\t\t\treturn committed;\n\t\t},\n\t\tget(memoryId, query) {\n\t\t\tconst owner = requireOwner(query);\n\t\t\tconst record = records.get(memoryId);\n\t\t\tif (!record) return undefined;\n\t\t\tif (record.atom.owner !== owner) return undefined;\n\t\t\tif (!isVisibleInSuite(record.atom, query.suiteId)) return undefined;\n\t\t\tif (isExpired(record)) return undefined;\n\t\t\treturn record;\n\t\t},\n\t\tlist(query, scope) {\n\t\t\tconst owner = requireOwner(query);\n\t\t\tconst results: CommittedMemoryV1[] = [];\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tif (record.atom.owner !== owner) continue;\n\t\t\t\tif (scope !== undefined && record.atom.scope !== scope) continue;\n\t\t\t\tif (!isVisibleInSuite(record.atom, query.suiteId)) continue;\n\t\t\t\tif (isExpired(record)) continue;\n\t\t\t\tresults.push(record);\n\t\t\t}\n\t\t\treturn Object.freeze(results.sort((left, right) => left.storeRevision - right.storeRevision));\n\t\t},\n\t\tlistForSuite(query, scope) {\n\t\t\trequireOwner(query);\n\t\t\tconst suiteId = query.suiteId;\n\t\t\tconst results: CommittedMemoryV1[] = [];\n\t\t\tlet legacySkipped = 0;\n\t\t\tlet foreignSuiteSkipped = 0;\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tif (record.atom.owner !== query.owner) continue;\n\t\t\t\tif (scope !== undefined && record.atom.scope !== scope) continue;\n\t\t\t\tif (isExpired(record)) continue;\n\t\t\t\tconst visibility = memorySuiteVisibility(record.atom, suiteId);\n\t\t\t\tif (visibility === \"legacy\") {\n\t\t\t\t\tlegacySkipped += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (visibility === \"foreign-suite\") {\n\t\t\t\t\tforeignSuiteSkipped += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tresults.push(record);\n\t\t\t}\n\t\t\tresults.sort((left, right) => left.storeRevision - right.storeRevision);\n\t\t\treturn Object.freeze({\n\t\t\t\trecords: Object.freeze(results),\n\t\t\t\tfilter: Object.freeze({ legacySkipped, foreignSuiteSkipped }),\n\t\t\t});\n\t\t},\n\t\tstats() {\n\t\t\tconst bucket = () => ({ active: 0, expired: 0 });\n\t\t\tconst byScope: Record<MemoryScopeV1, { active: number; expired: number }> = {\n\t\t\t\tsession: bucket(),\n\t\t\t\tcycle: bucket(),\n\t\t\t\t\"long-term\": bucket(),\n\t\t\t};\n\t\t\tlet active = 0;\n\t\t\tlet expired = 0;\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tconst target = byScope[record.atom.scope];\n\t\t\t\tif (isExpired(record)) {\n\t\t\t\t\texpired += 1;\n\t\t\t\t\ttarget.expired += 1;\n\t\t\t\t} else {\n\t\t\t\t\tactive += 1;\n\t\t\t\t\ttarget.active += 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { active, expired, byScope: Object.freeze(byScope) };\n\t\t},\n\t\tevict(memoryId) {\n\t\t\tif (typeof memoryId !== \"string\" || memoryId.trim() === \"\") {\n\t\t\t\tthrow new Error(\"Memory store evict requires a memoryId\");\n\t\t\t}\n\t\t\treturn records.delete(memoryId);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/store.js

@@ -0,0 +1,208 @@
+/**
+ * Memory Foundation — three-scope store with revisions, TTL, and retention
+ * inputs (1C.1b).
+ *
+ * Scope decides which partition a committed atom belongs to (session / cycle /
+ * long-term); retention decides how long it stays recallable. Retention mode
+ * IDs are opaque strings resolved through a versioned registry provided by the
+ * Profile — the Foundation never hardcodes business durations. Expired records
+ * lose recall eligibility but are NOT physically purged here (physical purge
+ * is the controlled 1C.6d gate).
+ */
+import { memorySuiteVisibility, validateMemoryAtomV1 } from "./foundation.js";
+/** Validates a retention-mode registry: parseable, finite, non-negative, unique, traceable. */
+export function validateRetentionModeRegistry(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Retention mode registry must be a plain object");
+    }
+    const record = value;
+    assertNonEmptyString(record.policyVersion, "Retention mode registry.policyVersion");
+    if (!Array.isArray(record.modes) || record.modes.length === 0) {
+        throw new Error("Retention mode registry.modes must be a non-empty array");
+    }
+    const seen = new Set();
+    const modes = record.modes.map((item, index) => {
+        const label = `Retention mode[${index}]`;
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`${label} must be a plain object`);
+        }
+        const entry = item;
+        assertNonEmptyString(entry.id, `${label}.id`);
+        if (seen.has(entry.id))
+            throw new Error(`${label} duplicates id: ${entry.id}`);
+        seen.add(entry.id);
+        if (typeof entry.autoPurge !== "boolean")
+            throw new Error(`${label}.autoPurge must be boolean`);
+        if (entry.durationMs !== undefined) {
+            if (typeof entry.durationMs !== "number" || !Number.isSafeInteger(entry.durationMs) || entry.durationMs <= 0) {
+                throw new Error(`${label}.durationMs must be a positive safe integer`);
+            }
+        }
+        return Object.freeze({
+            id: entry.id,
+            ...(entry.durationMs === undefined ? {} : { durationMs: entry.durationMs }),
+            autoPurge: entry.autoPurge,
+        });
+    });
+    return Object.freeze({
+        policyVersion: record.policyVersion,
+        modes: Object.freeze(modes),
+        get(id) {
+            return modes.find((mode) => mode.id === id);
+        },
+    });
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+/** First-party default registry (short/standard/long/permanent). Durations live here, not in Foundation logic. */
+export function createFirstPartyRetentionRegistry() {
+    const DAY = 24 * 60 * 60 * 1000;
+    return validateRetentionModeRegistry({
+        policyVersion: "retention@1",
+        modes: [
+            { id: "short", durationMs: 7 * DAY, autoPurge: true },
+            { id: "standard", durationMs: 30 * DAY, autoPurge: true },
+            { id: "long", durationMs: 365 * DAY, autoPurge: true },
+            { id: "permanent", autoPurge: false },
+        ],
+    });
+}
+/** Creates a deterministic three-scope Foundation store. Expired records lose recall but stay ledgered. */
+export function createMemoryStore(options) {
+    const registry = options.retentionRegistry;
+    const now = options.now ?? (() => Date.now());
+    const records = new Map();
+    let storeRevision = 0;
+    const scopeRevisions = new Map();
+    const isExpired = (record) => record.purgeAt !== undefined && record.purgeAt <= now();
+    const requireOwner = (query) => {
+        if (query === null || typeof query !== "object" || typeof query.owner !== "string" || query.owner.trim() === "") {
+            throw new Error("Memory store query requires an owner");
+        }
+        if (query.suiteId !== undefined && (typeof query.suiteId !== "string" || query.suiteId.trim() === "")) {
+            throw new Error("Memory store query requires a non-empty suiteId when filtering by suite");
+        }
+        return query.owner;
+    };
+    /** Suite read boundary: `undefined` query.suiteId means no suite filtering. */
+    const isVisibleInSuite = (atom, suiteId) => suiteId === undefined || memorySuiteVisibility(atom, suiteId) === "visible";
+    return {
+        commit(atom, commitOptions) {
+            const validated = validateMemoryAtomV1(atom);
+            // Canonical atoms are immutable once committed (设计 §4): a second
+            // commit with the same memoryId is a caller bug and must fail
+            // explicitly instead of silently overwriting verified facts.
+            if (records.has(validated.memoryId)) {
+                throw new Error(`Memory already committed: ${validated.memoryId} (canonical atoms are immutable; use the candidate machine for dedupe)`);
+            }
+            const modeId = commitOptions?.retentionModeId ?? validated.retentionMode;
+            const mode = registry.get(modeId);
+            if (!mode)
+                throw new Error(`Retention mode is not registered: ${modeId}`);
+            storeRevision += 1;
+            const scopeRevision = (scopeRevisions.get(validated.scope) ?? 0) + 1;
+            scopeRevisions.set(validated.scope, scopeRevision);
+            const committedAt = now();
+            const committed = Object.freeze({
+                atom: validated,
+                storeRevision,
+                scopeRevision,
+                committedAt,
+                ...(mode.durationMs === undefined ? {} : { purgeAt: committedAt + mode.durationMs }),
+                retentionModeId: mode.id,
+            });
+            records.set(validated.memoryId, committed);
+            return committed;
+        },
+        get(memoryId, query) {
+            const owner = requireOwner(query);
+            const record = records.get(memoryId);
+            if (!record)
+                return undefined;
+            if (record.atom.owner !== owner)
+                return undefined;
+            if (!isVisibleInSuite(record.atom, query.suiteId))
+                return undefined;
+            if (isExpired(record))
+                return undefined;
+            return record;
+        },
+        list(query, scope) {
+            const owner = requireOwner(query);
+            const results = [];
+            for (const record of records.values()) {
+                if (record.atom.owner !== owner)
+                    continue;
+                if (scope !== undefined && record.atom.scope !== scope)
+                    continue;
+                if (!isVisibleInSuite(record.atom, query.suiteId))
+                    continue;
+                if (isExpired(record))
+                    continue;
+                results.push(record);
+            }
+            return Object.freeze(results.sort((left, right) => left.storeRevision - right.storeRevision));
+        },
+        listForSuite(query, scope) {
+            requireOwner(query);
+            const suiteId = query.suiteId;
+            const results = [];
+            let legacySkipped = 0;
+            let foreignSuiteSkipped = 0;
+            for (const record of records.values()) {
+                if (record.atom.owner !== query.owner)
+                    continue;
+                if (scope !== undefined && record.atom.scope !== scope)
+                    continue;
+                if (isExpired(record))
+                    continue;
+                const visibility = memorySuiteVisibility(record.atom, suiteId);
+                if (visibility === "legacy") {
+                    legacySkipped += 1;
+                    continue;
+                }
+                if (visibility === "foreign-suite") {
+                    foreignSuiteSkipped += 1;
+                    continue;
+                }
+                results.push(record);
+            }
+            results.sort((left, right) => left.storeRevision - right.storeRevision);
+            return Object.freeze({
+                records: Object.freeze(results),
+                filter: Object.freeze({ legacySkipped, foreignSuiteSkipped }),
+            });
+        },
+        stats() {
+            const bucket = () => ({ active: 0, expired: 0 });
+            const byScope = {
+                session: bucket(),
+                cycle: bucket(),
+                "long-term": bucket(),
+            };
+            let active = 0;
+            let expired = 0;
+            for (const record of records.values()) {
+                const target = byScope[record.atom.scope];
+                if (isExpired(record)) {
+                    expired += 1;
+                    target.expired += 1;
+                }
+                else {
+                    active += 1;
+                    target.active += 1;
+                }
+            }
+            return { active, expired, byScope: Object.freeze(byScope) };
+        },
+        evict(memoryId) {
+            if (typeof memoryId !== "string" || memoryId.trim() === "") {
+                throw new Error("Memory store evict requires a memoryId");
+            }
+            return records.delete(memoryId);
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/memory/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — three-scope store with revisions, TTL, and retention\n * inputs (1C.1b).\n *\n * Scope decides which partition a committed atom belongs to (session / cycle /\n * long-term); retention decides how long it stays recallable. Retention mode\n * IDs are opaque strings resolved through a versioned registry provided by the\n * Profile — the Foundation never hardcodes business durations. Expired records\n * lose recall eligibility but are NOT physically purged here (physical purge\n * is the controlled 1C.6d gate).\n */\n\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1, MemoryScopeV1, MemorySuiteFilterStatsV1 } from \"./foundation.ts\";\nimport { memorySuiteVisibility, validateMemoryAtomV1 } from \"./foundation.ts\";\n\n/** One retention mode published by a Profile's retention-mode registry. */\nexport interface RetentionModeDefinitionV1 {\n\treadonly id: string;\n\t/** Recall duration in ms. Absent = no expiry (e.g. `permanent`). */\n\treadonly durationMs?: number;\n\treadonly autoPurge: boolean;\n}\n\n/** Versioned retention-mode registry snapshot. */\nexport interface RetentionModeRegistryV1 {\n\treadonly policyVersion: string;\n\treadonly modes: readonly RetentionModeDefinitionV1[];\n\tget(id: string): RetentionModeDefinitionV1 | undefined;\n}\n\n/** Validates a retention-mode registry: parseable, finite, non-negative, unique, traceable. */\nexport function validateRetentionModeRegistry(value: unknown): RetentionModeRegistryV1 {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new Error(\"Retention mode registry must be a plain object\");\n\t}\n\tconst record = value as Record<string, unknown>;\n\tassertNonEmptyString(record.policyVersion, \"Retention mode registry.policyVersion\");\n\tif (!Array.isArray(record.modes) || record.modes.length === 0) {\n\t\tthrow new Error(\"Retention mode registry.modes must be a non-empty array\");\n\t}\n\tconst seen = new Set<string>();\n\tconst modes: RetentionModeDefinitionV1[] = record.modes.map((item, index) => {\n\t\tconst label = `Retention mode[${index}]`;\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item)) {\n\t\t\tthrow new Error(`${label} must be a plain object`);\n\t\t}\n\t\tconst entry = item as Record<string, unknown>;\n\t\tassertNonEmptyString(entry.id, `${label}.id`);\n\t\tif (seen.has(entry.id)) throw new Error(`${label} duplicates id: ${entry.id}`);\n\t\tseen.add(entry.id);\n\t\tif (typeof entry.autoPurge !== \"boolean\") throw new Error(`${label}.autoPurge must be boolean`);\n\t\tif (entry.durationMs !== undefined) {\n\t\t\tif (typeof entry.durationMs !== \"number\" || !Number.isSafeInteger(entry.durationMs) || entry.durationMs <= 0) {\n\t\t\t\tthrow new Error(`${label}.durationMs must be a positive safe integer`);\n\t\t\t}\n\t\t}\n\t\treturn Object.freeze({\n\t\t\tid: entry.id,\n\t\t\t...(entry.durationMs === undefined ? {} : { durationMs: entry.durationMs }),\n\t\t\tautoPurge: entry.autoPurge,\n\t\t});\n\t});\n\treturn Object.freeze({\n\t\tpolicyVersion: record.policyVersion,\n\t\tmodes: Object.freeze(modes),\n\t\tget(id: string) {\n\t\t\treturn modes.find((mode) => mode.id === id);\n\t\t},\n\t});\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\n/** First-party default registry (short/standard/long/permanent). Durations live here, not in Foundation logic. */\nexport function createFirstPartyRetentionRegistry(): RetentionModeRegistryV1 {\n\tconst DAY = 24 * 60 * 60 * 1000;\n\treturn validateRetentionModeRegistry({\n\t\tpolicyVersion: \"retention@1\",\n\t\tmodes: [\n\t\t\t{ id: \"short\", durationMs: 7 * DAY, autoPurge: true },\n\t\t\t{ id: \"standard\", durationMs: 30 * DAY, autoPurge: true },\n\t\t\t{ id: \"long\", durationMs: 365 * DAY, autoPurge: true },\n\t\t\t{ id: \"permanent\", autoPurge: false },\n\t\t],\n\t});\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 (方案系统设计 §6.1/§11). When set, only atoms\n\t * whose suiteId equals this value — plus explicitly promoted user-default\n\t * preferences — are visible; legacy (suiteId-less) atoms are skipped\n\t * fail-safe. When absent, 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 {@link 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 (设计 §11). */\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 (设计 §3.3: only the purge\n\t * flow may destroy committed atoms). Call it exclusively from the purge\n\t * path (suite memory facade / scheduler purge); ordinary business code\n\t * never evicts. Returns true when the record existed. Expired-then-evicted\n\t * and unexpired records are removed alike; a restart replay cannot\n\t * resurrect an evicted atom once the durable replica is rewritten.\n\t */\n\tevict(memoryId: string): boolean;\n}\n\n/** Creates a deterministic three-scope Foundation store. Expired records lose recall but stay ledgered. */\nexport function createMemoryStore(options: {\n\treadonly retentionRegistry: RetentionModeRegistryV1;\n\treadonly now?: () => number;\n}): MemoryStoreV1 {\n\tconst registry = options.retentionRegistry;\n\tconst now = options.now ?? (() => Date.now());\n\tconst records = new Map<string, CommittedMemoryV1>();\n\tlet storeRevision = 0;\n\tconst scopeRevisions = new Map<MemoryScopeV1, number>();\n\n\tconst isExpired = (record: CommittedMemoryV1): boolean => record.purgeAt !== undefined && record.purgeAt <= now();\n\n\tconst requireOwner = (query: MemoryStoreQuery): string => {\n\t\tif (query === null || typeof query !== \"object\" || typeof query.owner !== \"string\" || query.owner.trim() === \"\") {\n\t\t\tthrow new Error(\"Memory store query requires an owner\");\n\t\t}\n\t\tif (query.suiteId !== undefined && (typeof query.suiteId !== \"string\" || query.suiteId.trim() === \"\")) {\n\t\t\tthrow new Error(\"Memory store query requires a non-empty suiteId when filtering by suite\");\n\t\t}\n\t\treturn query.owner;\n\t};\n\n\t/** Suite read boundary: `undefined` query.suiteId means no suite filtering. */\n\tconst isVisibleInSuite = (atom: MemoryAtomV1, suiteId: string | undefined): boolean =>\n\t\tsuiteId === undefined || memorySuiteVisibility(atom, suiteId) === \"visible\";\n\n\treturn {\n\t\tcommit(atom, commitOptions) {\n\t\t\tconst validated = validateMemoryAtomV1(atom);\n\t\t\t// Canonical atoms are immutable once committed (设计 §4): a second\n\t\t\t// commit with the same memoryId is a caller bug and must fail\n\t\t\t// explicitly instead of silently overwriting verified facts.\n\t\t\tif (records.has(validated.memoryId)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Memory already committed: ${validated.memoryId} (canonical atoms are immutable; use the candidate machine for dedupe)`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst modeId = commitOptions?.retentionModeId ?? validated.retentionMode;\n\t\t\tconst mode = registry.get(modeId);\n\t\t\tif (!mode) throw new Error(`Retention mode is not registered: ${modeId}`);\n\t\t\tstoreRevision += 1;\n\t\t\tconst scopeRevision = (scopeRevisions.get(validated.scope) ?? 0) + 1;\n\t\t\tscopeRevisions.set(validated.scope, scopeRevision);\n\t\t\tconst committedAt = now();\n\t\t\tconst committed: CommittedMemoryV1 = Object.freeze({\n\t\t\t\tatom: validated,\n\t\t\t\tstoreRevision,\n\t\t\t\tscopeRevision,\n\t\t\t\tcommittedAt,\n\t\t\t\t...(mode.durationMs === undefined ? {} : { purgeAt: committedAt + mode.durationMs }),\n\t\t\t\tretentionModeId: mode.id,\n\t\t\t});\n\t\t\trecords.set(validated.memoryId, committed);\n\t\t\treturn committed;\n\t\t},\n\t\tget(memoryId, query) {\n\t\t\tconst owner = requireOwner(query);\n\t\t\tconst record = records.get(memoryId);\n\t\t\tif (!record) return undefined;\n\t\t\tif (record.atom.owner !== owner) return undefined;\n\t\t\tif (!isVisibleInSuite(record.atom, query.suiteId)) return undefined;\n\t\t\tif (isExpired(record)) return undefined;\n\t\t\treturn record;\n\t\t},\n\t\tlist(query, scope) {\n\t\t\tconst owner = requireOwner(query);\n\t\t\tconst results: CommittedMemoryV1[] = [];\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tif (record.atom.owner !== owner) continue;\n\t\t\t\tif (scope !== undefined && record.atom.scope !== scope) continue;\n\t\t\t\tif (!isVisibleInSuite(record.atom, query.suiteId)) continue;\n\t\t\t\tif (isExpired(record)) continue;\n\t\t\t\tresults.push(record);\n\t\t\t}\n\t\t\treturn Object.freeze(results.sort((left, right) => left.storeRevision - right.storeRevision));\n\t\t},\n\t\tlistForSuite(query, scope) {\n\t\t\trequireOwner(query);\n\t\t\tconst suiteId = query.suiteId;\n\t\t\tconst results: CommittedMemoryV1[] = [];\n\t\t\tlet legacySkipped = 0;\n\t\t\tlet foreignSuiteSkipped = 0;\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tif (record.atom.owner !== query.owner) continue;\n\t\t\t\tif (scope !== undefined && record.atom.scope !== scope) continue;\n\t\t\t\tif (isExpired(record)) continue;\n\t\t\t\tconst visibility = memorySuiteVisibility(record.atom, suiteId);\n\t\t\t\tif (visibility === \"legacy\") {\n\t\t\t\t\tlegacySkipped += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (visibility === \"foreign-suite\") {\n\t\t\t\t\tforeignSuiteSkipped += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tresults.push(record);\n\t\t\t}\n\t\t\tresults.sort((left, right) => left.storeRevision - right.storeRevision);\n\t\t\treturn Object.freeze({\n\t\t\t\trecords: Object.freeze(results),\n\t\t\t\tfilter: Object.freeze({ legacySkipped, foreignSuiteSkipped }),\n\t\t\t});\n\t\t},\n\t\tstats() {\n\t\t\tconst bucket = () => ({ active: 0, expired: 0 });\n\t\t\tconst byScope: Record<MemoryScopeV1, { active: number; expired: number }> = {\n\t\t\t\tsession: bucket(),\n\t\t\t\tcycle: bucket(),\n\t\t\t\t\"long-term\": bucket(),\n\t\t\t};\n\t\t\tlet active = 0;\n\t\t\tlet expired = 0;\n\t\t\tfor (const record of records.values()) {\n\t\t\t\tconst target = byScope[record.atom.scope];\n\t\t\t\tif (isExpired(record)) {\n\t\t\t\t\texpired += 1;\n\t\t\t\t\ttarget.expired += 1;\n\t\t\t\t} else {\n\t\t\t\t\tactive += 1;\n\t\t\t\t\ttarget.active += 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { active, expired, byScope: Object.freeze(byScope) };\n\t\t},\n\t\tevict(memoryId) {\n\t\t\tif (typeof memoryId !== \"string\" || memoryId.trim() === \"\") {\n\t\t\t\tthrow new Error(\"Memory store evict requires a memoryId\");\n\t\t\t}\n\t\t\treturn records.delete(memoryId);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/suite-memory.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Suite memory facade (M5, 方案系统设计 §6.1 + 方案实施计划 §10) — the library
+ * surface a host uses to LIST and FORGET one suite's memories.
+ *
+ * The listing is the user-visible control surface for assistant-style personal
+ * memory (显式管理命令：列出/忘记 — controllability is a hard requirement when
+ * personal information is stored). Forgetting is the M4 suite-deletion hook:
+ * the atom set circled by suiteId goes through the canonical purge gate
+ * (user-immediate or profile-policy authorization) plus the purge journal, so
+ * authorization is structured, partial failures stay `purge_eligible` for an
+ * idempotent retry, and every step leaves an audit record. The physical
+ * replica purge is injected — this facade never reaches into store internals.
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+import type { MemoryKindV1, MemoryPreferenceEnvelopeV1, MemoryScopeV1, MemorySuiteFilterStatsV1 } from "./foundation.ts";
+import type { MemoryPurgeGateV1 } from "./purge.ts";
+import type { MemoryPurgeJournalV1 } from "./purge-journal.ts";
+import type { MemoryStoreV1 } from "./store.ts";
+/**
+ * Structured authorization for forgetting a suite. Suite deletion is a bulk,
+ * user- or policy-initiated destructive action, so the unstructured
+ * `authorizedBy`-only path and `retention-expiry` mode are not accepted.
+ */
+export type SuiteForgetAuthorizationRefV1 = {
+    readonly mode: "user-immediate";
+    readonly issuedAt: number;
+    readonly issuedBy: string;
+    readonly confirmationRef: string;
+} | {
+    readonly mode: "profile-policy";
+    readonly issuedAt: number;
+    readonly issuedBy: string;
+    readonly policyServiceRef: string;
+};
+/** One user-visible suite memory entry (列出语义). */
+export interface SuiteMemoryListEntryV1 {
+    readonly memoryId: string;
+    readonly memoryKind: MemoryKindV1;
+    readonly isPreference: boolean;
+    readonly scope: MemoryScopeV1;
+    readonly occurredAt: string;
+    readonly payload: JsonValue;
+    /** Present for preference atoms: the preference envelope summary. */
+    readonly preference?: {
+        readonly subject: MemoryPreferenceEnvelopeV1["subject"];
+        readonly key: string;
+        readonly scopeLevel: MemoryPreferenceEnvelopeV1["scope"]["level"];
+        /** True when explicitly promoted (user-default + confirmedAt) — cross-suite visible. */
+        readonly crossSuiteVisible: boolean;
+    };
+}
+export interface SuiteMemoryListResultV1 {
+    readonly suiteId: string;
+    readonly owner: string;
+    /** Deterministic order: store revision ascending (commit order). */
+    readonly entries: readonly SuiteMemoryListEntryV1[];
+    readonly preferenceCount: number;
+    readonly factCount: number;
+    /** Legacy/foreign-suite records excluded by the suite read boundary (设计 §11). */
+    readonly filter: MemorySuiteFilterStatsV1;
+}
+export interface SuiteMemoryFacadeDepsV1 {
+    readonly store: MemoryStoreV1;
+    readonly purgeGate: MemoryPurgeGateV1;
+    readonly purgeJournal: MemoryPurgeJournalV1;
+    readonly now?: () => number;
+    /**
+     * index 副本 (如 memory-vector-index, 混合检索工程化) 的物理清除回调。缺省
+     * undefined 时 index 副本分派为 no-op 且不报错——向量通道未装配 (off) 或
+     * 不可用 (disabled) 时索引里没有本会话写入的行, 无物可清。canonical 及其余
+     * 副本仍走 `purgeMemories` 回调 (行为零变化)。
+     */
+    readonly purgeIndexReplica?: (memoryIds: readonly string[]) => void;
+}
+export interface ListSuiteMemoriesInputV1 {
+    readonly owner: string;
+    readonly suiteId: string;
+}
+/**
+ * The suite read-boundary DOMAIN a memory operation is scoped to: a real suite
+ * (方案) membership, or the "legacy" sentinel domain for atoms recorded
+ * without a suite binding (方案系统设计 §6.1). Membership, distinct from the
+ * read boundary: an atom belongs to exactly one domain — the suite stored in
+ * its `suiteId`, or the legacy domain when absent. A promoted user-default
+ * preference is READABLE from every suite but remains a member of its origin
+ * domain and is listed/forgotten only there.
+ */
+export type SuiteMemoryDomainV1 = {
+    readonly kind: "suite";
+    readonly suiteId: string;
+} | {
+    readonly kind: "legacy";
+};
+/** Visible name of a domain: the suite id, or the "legacy" sentinel. */
+export declare function suiteMemoryDomainName(domain: SuiteMemoryDomainV1): string;
+/**
+ * Lists one suite's memories with preference/fact classification and
+ * membership skip counters. Promoted user-default preferences stay listed
+ * under their origin suite — only their READ visibility crosses suites.
+ */
+export declare function listSuiteMemories(deps: Pick<SuiteMemoryFacadeDepsV1, "store">, input: ListSuiteMemoriesInputV1): SuiteMemoryListResultV1;
+/** Result of {@link listDomainMemories}: one domain's entries plus skip counters. */
+export interface DomainMemoryListResultV1 {
+    /** The suite id, or the "legacy" sentinel for the no-suite domain. */
+    readonly domain: string;
+    readonly owner: string;
+    /** Deterministic order: store revision ascending (commit order). */
+    readonly entries: readonly SuiteMemoryListEntryV1[];
+    readonly preferenceCount: number;
+    readonly factCount: number;
+    /** Excluded-record counters for the other domains (设计 §11). */
+    readonly filter: MemorySuiteFilterStatsV1;
+}
+export interface ListDomainMemoriesInputV1 {
+    readonly owner: string;
+    readonly domain: SuiteMemoryDomainV1;
+}
+/**
+ * Lists one read-boundary DOMAIN's memories (suite membership or the legacy
+ * no-suite domain). The legacy domain lists exactly the suite-less atoms;
+ * suite-bound atoms count into `foreignSuiteSkipped`.
+ */
+export declare function listDomainMemories(deps: Pick<SuiteMemoryFacadeDepsV1, "store">, input: ListDomainMemoriesInputV1): DomainMemoryListResultV1;
+export interface ForgetSuiteMemoriesInputV1 {
+    readonly owner: string;
+    readonly suiteId: string;
+    readonly authorizedBy: string;
+    readonly authorizationRef: SuiteForgetAuthorizationRefV1;
+}
+export type SuiteForgetResultV1 = {
+    readonly status: "nothing_to_purge";
+    readonly suiteId: string;
+    readonly filter: MemorySuiteFilterStatsV1;
+} | {
+    readonly status: "completed" | "purge_eligible";
+    readonly suiteId: string;
+    readonly batchId: string;
+    readonly memoryIds: readonly string[];
+    readonly confirmedReplicas: readonly string[];
+    readonly failedReplicas?: readonly {
+        readonly replicaId: string;
+        readonly error: string;
+    }[];
+};
+/**
+ * Forgets every memory belonging to one suite (membership = the atom's
+ * `suiteId`): circles the atom set, runs it through the purge gate
+ * (`user-immediate` requires `confirmationRef`, `profile-policy` requires
+ * `policyServiceRef`), journals authorization and per-replica confirmations,
+ * and completes the journal only when the barrier fully confirmed. A partial
+ * failure keeps the batch `purge_eligible` — retry with
+ * {@link retrySuiteForget} using the returned batchId. `purgeMemories` is the
+ * host-injected canonical-replica purge; it must be idempotent (the gate
+ * re-runs it on retry). Batch ids come from the gate's `batchIdFactory`
+ * (gate construction option).
+ */
+export declare function forgetSuiteMemories(deps: SuiteMemoryFacadeDepsV1, input: ForgetSuiteMemoriesInputV1, purgeMemories: (memoryIds: readonly string[]) => void): SuiteForgetResultV1;
+/**
+ * Idempotent retry of a `purge_eligible` suite-forget batch. Unknown batch ids
+ * throw; already-completed batches are a no-op that reports `completed`
+ * (gate semantics).
+ */
+export declare function retrySuiteForget(deps: Pick<SuiteMemoryFacadeDepsV1, "purgeGate" | "purgeJournal" | "purgeIndexReplica" | "now">, input: {
+    readonly batchId: string;
+    readonly suiteId: string;
+}, purgeMemories: (memoryIds: readonly string[]) => void): SuiteForgetResultV1;
+export interface ForgetDomainMemoryInputV1 {
+    readonly owner: string;
+    /** The read-boundary domain the CALLER is operating in (tool-side isolation). */
+    readonly domain: SuiteMemoryDomainV1;
+    /** The single memory to forget; it must be a member of the caller's domain. */
+    readonly memoryId: string;
+    readonly authorizedBy: string;
+    readonly authorizationRef: SuiteForgetAuthorizationRefV1;
+}
+export type DomainMemoryForgetResultV1 = 
+/** No memory with this id under the owner. */
+{
+    readonly status: "not_found";
+    readonly memoryId: string;
+}
+/** The memory exists but belongs to another domain — refused, no gate run. */
+ | {
+    readonly status: "foreign_domain";
+    readonly memoryId: string;
+} | {
+    readonly status: "completed" | "purge_eligible";
+    readonly batchId: string;
+    readonly memoryIds: readonly string[];
+    readonly confirmedReplicas: readonly string[];
+    readonly failedReplicas?: readonly {
+        readonly replicaId: string;
+        readonly error: string;
+    }[];
+};
+/**
+ * Forgets ONE memory on behalf of a caller scoped to a read-boundary domain
+ * (assistant 场景可控性硬需求, 方案系统设计 §6.1): the atom must be a member of
+ * the caller's domain (its `suiteId` matches, or it is suite-less for the
+ * legacy domain) — a caller can never forget another suite's atoms by id.
+ * Deletion goes through the canonical purge gate (user-immediate or
+ * profile-policy authorization) plus the purge journal, exactly like
+ * {@link forgetSuiteMemories}; the injected `purgeMemories` callback performs
+ * the physical replica purge (e.g. the durable ledger rewrite plus store
+ * eviction) and must be idempotent for `purge_eligible` retries.
+ */
+export declare function forgetDomainMemory(deps: SuiteMemoryFacadeDepsV1, input: ForgetDomainMemoryInputV1, purgeMemories: (memoryIds: readonly string[]) => void): DomainMemoryForgetResultV1;
+//# sourceMappingURL=suite-memory.d.ts.map