@ai-agent-forge/plugin-memory 0.85.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"foundation.d.ts","sourceRoot":"","sources":["../../src/memory/foundation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — canonical atom, identity, and immutable snapshots (1C.1a).\n *\n * A canonical atom is the immutable committed fact. Derived state (attention,\n * effective status, purgeAt) is NOT part of the atom; it is rebuilt from\n * lifecycle events (1C.1b/1C.2). Everything returned to hosts and plugins is a\n * detached, deep-frozen snapshot: mutating the input after `buildMemoryAtomV1`\n * never changes the stored atom.\n *\n * Field semantics follow `docs/design/记忆系统设计.md` §4 (记录模型), which is the\n * authoritative source for memory fields.\n */\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\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/** The immutable canonical atom. Once committed, no field may change in place. */\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 (方案系统设计 §6.1/§11, M5). Absent\n\t * (or protocol-level `null` on the wire, normalized to absent here) marks a\n\t * legacy pre-M5 atom: such atoms are fail-safe INVISIBLE to every\n\t * suite-scoped read and only readable through suite-unscoped queries. The\n\t * one cross-suite exception is an explicitly promoted user-default\n\t * preference (see {@link memorySuiteVisibility}).\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\ntype PlainRecord = Record<string, unknown>;\n\nfunction isPlainRecord(value: unknown): value is PlainRecord {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nfunction assertPlainRecord(value: unknown, label: string): asserts value is PlainRecord {\n\tif (!isPlainRecord(value)) throw new Error(`${label} must be a plain object`);\n}\n\nfunction assertExactKeys(\n\tvalue: PlainRecord,\n\trequired: readonly string[],\n\toptional: readonly string[],\n\tlabel: string,\n): void {\n\tconst allowed = new Set([...required, ...optional]);\n\tconst unsupported = Object.keys(value)\n\t\t.filter((key) => !allowed.has(key))\n\t\t.sort();\n\tif (unsupported.length > 0) throw new Error(`${label} has unsupported fields: ${unsupported.join(\", \")}`);\n\tfor (const key of required) {\n\t\tif (!(key in value)) throw new Error(`${label} is missing required field: ${key}`);\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\nfunction assertPositiveSafeInteger(value: unknown, label: string): asserts value is number {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < 1) {\n\t\tthrow new Error(`${label} must be a positive safe integer`);\n\t}\n}\n\nfunction assertUnitInterval(value: unknown, label: string): asserts value is number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || value < 0 || value > 1) {\n\t\tthrow new Error(`${label} must be a number between 0 and 1`);\n\t}\n}\n\nfunction assertTimestamp(value: unknown, label: string): asserts value is string {\n\tassertNonEmptyString(value, label);\n\tif (Number.isNaN(Date.parse(value))) throw new Error(`${label} must be an ISO-8601 timestamp`);\n}\n\nfunction assertJsonValue(value: unknown, label: string, seen = new WeakSet<object>()): asserts value is JsonValue {\n\tif (value === null || typeof value === \"string\" || typeof value === \"boolean\") return;\n\tif (typeof value === \"number\") {\n\t\tif (Number.isFinite(value)) return;\n\t\tthrow new Error(`${label} must contain finite JSON numbers`);\n\t}\n\tif (typeof value !== \"object\") throw new Error(`${label} must be JSON-compatible`);\n\tif (seen.has(value)) throw new Error(`${label} must not contain cycles`);\n\tseen.add(value);\n\tif (Array.isArray(value)) {\n\t\tfor (const [index, child] of value.entries()) assertJsonValue(child, `${label}[${index}]`, seen);\n\t} else {\n\t\tif (!isPlainRecord(value)) throw new Error(`${label} must contain only plain JSON objects`);\n\t\tfor (const [key, child] of Object.entries(value)) assertJsonValue(child, `${label}.${key}`, seen);\n\t}\n\tseen.delete(value);\n}\n\nfunction assertStringArray(value: unknown, label: string): asserts value is readonly string[] {\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\tfor (const [index, item] of value.entries()) assertNonEmptyString(item, `${label}[${index}]`);\n}\n\nfunction detachedFreeze<T>(value: T, seen = new WeakMap<object, unknown>()): T {\n\tif (value === null || typeof value !== \"object\") return value;\n\tconst existing = seen.get(value);\n\t// v8 ignore next -- 校验后的原子全部由新副本构成，不存在共享引用\n\tif (existing !== undefined) return existing as T;\n\tif (Array.isArray(value)) {\n\t\tconst copy: unknown[] = [];\n\t\tseen.set(value, copy);\n\t\tfor (const child of value) copy.push(detachedFreeze(child, seen));\n\t\treturn Object.freeze(copy) as T;\n\t}\n\tconst copy: Record<string, unknown> = Object.create(null) as Record<string, unknown>;\n\tseen.set(value, copy);\n\tfor (const [key, child] of Object.entries(value as Record<string, unknown>)) {\n\t\tcopy[key] = detachedFreeze(child, seen);\n\t}\n\treturn Object.freeze(copy) as T;\n}\n\n/** Stable JSON serialization with recursively sorted object keys (for identity digests). */\nfunction stableStringify(value: JsonValue): string {\n\tif (value === null || typeof value === \"boolean\" || typeof value === \"number\" || typeof value === \"string\") {\n\t\treturn JSON.stringify(value);\n\t}\n\tif (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(\",\")}]`;\n\tconst entries = Object.keys(value)\n\t\t.sort()\n\t\t.map((key) => `${JSON.stringify(key)}:${stableStringify((value as Record<string, JsonValue>)[key])}`);\n\treturn `{${entries.join(\",\")}}`;\n}\n\nconst MEMORY_SCOPES_V1: readonly MemoryScopeV1[] = [\"session\", \"cycle\", \"long-term\"];\nconst MEMORY_KINDS_V1: readonly MemoryKindV1[] = [\n\t\"observation\",\n\t\"preference\",\n\t\"fact\",\n\t\"decision\",\n\t\"constraint\",\n\t\"inference\",\n\t\"synthesis\",\n];\nconst MEMORY_EVIDENCE_CLASSES_V1: readonly MemoryEvidenceClassV1[] = [\n\t\"explicit\",\n\t\"repeated_behavior\",\n\t\"tool_or_test\",\n\t\"derived\",\n];\nconst SOURCE_REF_KINDS: readonly MemorySourceRefV1[\"kind\"][] = [\"session\", \"entry\", \"artifact\", \"tool\", \"state\"];\n\nfunction validateSourceRef(value: unknown, label: string): MemorySourceRefV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"kind\", \"id\"], [\"revision\", \"digest\"], label);\n\tif (!SOURCE_REF_KINDS.includes(value.kind as MemorySourceRefV1[\"kind\"])) {\n\t\tthrow new Error(`${label}.kind is invalid`);\n\t}\n\tassertNonEmptyString(value.id, `${label}.id`);\n\tif (value.revision !== undefined) assertNonEmptyString(value.revision, `${label}.revision`);\n\tif (value.digest !== undefined) assertNonEmptyString(value.digest, `${label}.digest`);\n\treturn detachedFreeze({\n\t\tkind: value.kind as MemorySourceRefV1[\"kind\"],\n\t\tid: value.id,\n\t\t...(value.revision === undefined ? {} : { revision: value.revision }),\n\t\t...(value.digest === undefined ? {} : { digest: value.digest }),\n\t});\n}\n\nfunction validateFacet(value: unknown, label: string): MemoryFacetV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"namespace\", \"schemaVersion\", \"key\", \"value\"], [], label);\n\tassertNonEmptyString(value.namespace, `${label}.namespace`);\n\tassertPositiveSafeInteger(value.schemaVersion, `${label}.schemaVersion`);\n\tassertNonEmptyString(value.key, `${label}.key`);\n\tassertNonEmptyString(value.value, `${label}.value`);\n\treturn detachedFreeze({\n\t\tnamespace: value.namespace,\n\t\tschemaVersion: value.schemaVersion,\n\t\tkey: value.key,\n\t\tvalue: value.value,\n\t});\n}\n\nfunction validateRelation(value: unknown, label: string): MemoryRelationV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"relationId\", \"namespace\", \"schemaVersion\", \"kind\", \"relationRevision\"],\n\t\t[\"targetMemoryId\", \"targetRef\", \"confidence\"],\n\t\tlabel,\n\t);\n\tassertNonEmptyString(value.relationId, `${label}.relationId`);\n\tassertNonEmptyString(value.namespace, `${label}.namespace`);\n\tassertPositiveSafeInteger(value.schemaVersion, `${label}.schemaVersion`);\n\tassertNonEmptyString(value.kind, `${label}.kind`);\n\tassertNonEmptyString(value.relationRevision, `${label}.relationRevision`);\n\tif (value.targetMemoryId !== undefined && value.targetRef !== undefined) {\n\t\tthrow new Error(`${label} must not declare both targetMemoryId and targetRef`);\n\t}\n\tconst targetMemoryId = value.targetMemoryId === undefined ? undefined : (value.targetMemoryId as string);\n\tif (targetMemoryId !== undefined) assertNonEmptyString(targetMemoryId, `${label}.targetMemoryId`);\n\tconst targetRef =\n\t\tvalue.targetRef === undefined ? undefined : validateSourceRef(value.targetRef, `${label}.targetRef`);\n\tif (value.confidence !== undefined) assertUnitInterval(value.confidence, `${label}.confidence`);\n\treturn detachedFreeze({\n\t\trelationId: value.relationId,\n\t\tnamespace: value.namespace,\n\t\tschemaVersion: value.schemaVersion,\n\t\tkind: value.kind,\n\t\t...(targetMemoryId === undefined ? {} : { targetMemoryId }),\n\t\t...(targetRef === undefined ? {} : { targetRef }),\n\t\t...(value.confidence === undefined ? {} : { confidence: value.confidence }),\n\t\trelationRevision: value.relationRevision,\n\t});\n}\n\nfunction validateTimeRange(value: unknown, label: string): MemoryTimeRangeV1 {\n\tassertPlainRecord(value, label);\n\t// Key order reversed on purpose: in the natural order the boundary-gate\n\t// lexical scanner reads this key pair as an import specifier (first key\n\t// string, comma, second key string). `assertExactKeys` builds a Set, so the\n\t// order is irrelevant to validation.\n\tassertExactKeys(value, [], [\"to\", \"from\"], label);\n\tconst from = value.from === undefined ? undefined : (value.from as string);\n\tconst to = value.to === undefined ? undefined : (value.to as string);\n\tif (from !== undefined) assertTimestamp(from, `${label}.from`);\n\tif (to !== undefined) assertTimestamp(to, `${label}.to`);\n\treturn detachedFreeze({\n\t\t...(from === undefined ? {} : { from }),\n\t\t...(to === undefined ? {} : { to }),\n\t});\n}\n\nfunction validateApplicability(value: unknown, label: string): MemoryApplicabilityV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [], [\"scenes\", \"projects\", \"tasks\", \"timeRange\", \"exceptions\"], label);\n\tconst timeRange =\n\t\tvalue.timeRange === undefined ? undefined : validateTimeRange(value.timeRange, `${label}.timeRange`);\n\treturn detachedFreeze({\n\t\t...(value.scenes === undefined ? {} : { scenes: Object.freeze([...(value.scenes as readonly string[])]) }),\n\t\t...(value.projects === undefined ? {} : { projects: Object.freeze([...(value.projects as readonly string[])]) }),\n\t\t...(value.tasks === undefined ? {} : { tasks: Object.freeze([...(value.tasks as readonly string[])]) }),\n\t\t...(timeRange === undefined ? {} : { timeRange }),\n\t\t...(value.exceptions === undefined\n\t\t\t? {}\n\t\t\t: { exceptions: Object.freeze([...(value.exceptions as readonly string[])]) }),\n\t});\n}\n\nfunction validatePreferenceEnvelope(value: unknown, label: string): MemoryPreferenceEnvelopeV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"subject\", \"key\", \"preferredValue\", \"scope\", \"evidence\", \"applicabilityConfidence\"],\n\t\t[\"alternatives\", \"confirmedAt\"],\n\t\tlabel,\n\t);\n\tconst subjects: readonly MemoryPreferenceEnvelopeV1[\"subject\"][] = [\"user\", \"project\", \"task\", \"environment\"];\n\tif (!subjects.includes(value.subject as MemoryPreferenceEnvelopeV1[\"subject\"])) {\n\t\tthrow new Error(`${label}.subject is invalid`);\n\t}\n\tassertNonEmptyString(value.key, `${label}.key`);\n\tassertJsonValue(value.preferredValue, `${label}.preferredValue`);\n\tif (value.alternatives !== undefined) {\n\t\tif (!Array.isArray(value.alternatives)) throw new Error(`${label}.alternatives must be an array`);\n\t\tfor (const [index, item] of value.alternatives.entries()) {\n\t\t\tassertJsonValue(item, `${label}.alternatives[${index}]`);\n\t\t}\n\t}\n\tconst scope = value.scope;\n\tassertPlainRecord(scope, `${label}.scope`);\n\tassertExactKeys(scope, [\"level\"], [\"scenes\", \"projects\", \"tasks\", \"timeRange\", \"exceptions\"], `${label}.scope`);\n\tconst levels: readonly MemoryPreferenceEnvelopeV1[\"scope\"][\"level\"][] = [\n\t\t\"task\",\n\t\t\"project\",\n\t\t\"scene\",\n\t\t\"timeRange\",\n\t\t\"profile-private\",\n\t\t\"user-default\",\n\t];\n\tif (!levels.includes(scope.level as MemoryPreferenceEnvelopeV1[\"scope\"][\"level\"])) {\n\t\tthrow new Error(`${label}.scope.level is invalid`);\n\t}\n\t// Anchor levels require their anchor to be present (记录模型约束).\n\tconst anchors: ReadonlyArray<[string, keyof PlainRecord]> = [\n\t\t[\"task\", \"tasks\"],\n\t\t[\"project\", \"projects\"],\n\t\t[\"scene\", \"scenes\"],\n\t\t[\"timeRange\", \"timeRange\"],\n\t];\n\tfor (const [level, field] of anchors) {\n\t\tif (\n\t\t\tscope.level === level &&\n\t\t\t(scope[field] === undefined || (Array.isArray(scope[field]) && scope[field].length === 0))\n\t\t) {\n\t\t\tthrow new Error(`${label}.scope.level \"${level}\" requires non-empty ${field}`);\n\t\t}\n\t}\n\tconst evidence = value.evidence;\n\tassertPlainRecord(evidence, `${label}.evidence`);\n\tassertExactKeys(evidence, [\"class\", \"sourceRefs\", \"confidence\"], [], `${label}.evidence`);\n\tconst evidenceClasses: readonly MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"][] = [\n\t\t\"explicit\",\n\t\t\"repeated_behavior\",\n\t\t\"inferred\",\n\t];\n\tif (!evidenceClasses.includes(evidence.class as MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"])) {\n\t\tthrow new Error(`${label}.evidence.class is invalid`);\n\t}\n\tif (!Array.isArray(evidence.sourceRefs) || evidence.sourceRefs.length === 0) {\n\t\tthrow new Error(`${label}.evidence.sourceRefs must not be empty`);\n\t}\n\tconst evidenceSourceRefs = evidence.sourceRefs.map((item, index) =>\n\t\tvalidateSourceRef(item, `${label}.evidence.sourceRefs[${index}]`),\n\t);\n\tassertUnitInterval(evidence.confidence, `${label}.evidence.confidence`);\n\tassertUnitInterval(value.applicabilityConfidence, `${label}.applicabilityConfidence`);\n\tif (value.confirmedAt !== undefined) assertTimestamp(value.confirmedAt, `${label}.confirmedAt`);\n\treturn detachedFreeze({\n\t\tsubject: value.subject as MemoryPreferenceEnvelopeV1[\"subject\"],\n\t\tkey: value.key,\n\t\tpreferredValue: value.preferredValue,\n\t\t...(value.alternatives === undefined ? {} : { alternatives: Object.freeze([...value.alternatives]) }),\n\t\tscope: detachedFreeze({\n\t\t\tlevel: scope.level as MemoryPreferenceEnvelopeV1[\"scope\"][\"level\"],\n\t\t\t...(scope.scenes === undefined ? {} : { scenes: Object.freeze([...(scope.scenes as readonly string[])]) }),\n\t\t\t...(scope.projects === undefined\n\t\t\t\t? {}\n\t\t\t\t: { projects: Object.freeze([...(scope.projects as readonly string[])]) }),\n\t\t\t...(scope.tasks === undefined ? {} : { tasks: Object.freeze([...(scope.tasks as readonly string[])]) }),\n\t\t\t...(scope.timeRange === undefined\n\t\t\t\t? {}\n\t\t\t\t: { timeRange: validateTimeRange(scope.timeRange, `${label}.scope.timeRange`) }),\n\t\t\t...(scope.exceptions === undefined\n\t\t\t\t? {}\n\t\t\t\t: { exceptions: Object.freeze([...(scope.exceptions as readonly string[])]) }),\n\t\t}),\n\t\tevidence: detachedFreeze({\n\t\t\tclass: evidence.class as MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"],\n\t\t\tsourceRefs: Object.freeze(evidenceSourceRefs),\n\t\t\tconfidence: evidence.confidence,\n\t\t}),\n\t\tapplicabilityConfidence: value.applicabilityConfidence,\n\t\t...(value.confirmedAt === undefined ? {} : { confirmedAt: value.confirmedAt }),\n\t}) as MemoryPreferenceEnvelopeV1;\n}\n\nfunction validateProvenance(value: unknown, label: string): MemoryProvenanceV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"sourceMemoryIds\", \"purgeGroupId\", \"containsSourceContent\"], [], label);\n\tassertStringArray(value.sourceMemoryIds, `${label}.sourceMemoryIds`);\n\tif (value.sourceMemoryIds.length === 0) throw new Error(`${label}.sourceMemoryIds must not be empty`);\n\tassertNonEmptyString(value.purgeGroupId, `${label}.purgeGroupId`);\n\tif (typeof value.containsSourceContent !== \"boolean\") {\n\t\tthrow new Error(`${label}.containsSourceContent must be boolean`);\n\t}\n\treturn detachedFreeze({\n\t\tsourceMemoryIds: Object.freeze([...(value.sourceMemoryIds as readonly string[])]),\n\t\tpurgeGroupId: value.purgeGroupId,\n\t\tcontainsSourceContent: value.containsSourceContent,\n\t});\n}\n\n/**\n * Validates a canonical memory atom and returns a detached, deep-frozen\n * snapshot. Unknown fields, wrong enums, non-JSON payloads, preference-kind\n * atoms without a preference envelope, and identity fields (memoryId,\n * observationId, contentRevision, owner) that are not non-empty strings are\n * rejected.\n */\nexport function validateMemoryAtomV1<TPayload = JsonValue>(value: unknown): MemoryAtomV1<TPayload> {\n\tassertPlainRecord(value, \"Memory atom\");\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\n\t\t\t\"memoryId\",\n\t\t\t\"contractVersion\",\n\t\t\t\"schemaVersion\",\n\t\t\t\"scope\",\n\t\t\t\"retentionMode\",\n\t\t\t\"owner\",\n\t\t\t\"profileId\",\n\t\t\t\"retentionPolicyVersion\",\n\t\t\t\"memoryKind\",\n\t\t\t\"payload\",\n\t\t\t\"occurredAt\",\n\t\t\t\"recordedAt\",\n\t\t\t\"sourceRefs\",\n\t\t\t\"observationId\",\n\t\t\t\"sessionRefs\",\n\t\t\t\"agentInstanceRefs\",\n\t\t\t\"projectRefs\",\n\t\t\t\"subjectRefs\",\n\t\t\t\"facets\",\n\t\t\t\"relations\",\n\t\t\t\"confidence\",\n\t\t\t\"importance\",\n\t\t\t\"evidenceClass\",\n\t\t\t\"contentRevision\",\n\t\t\t\"writeReason\",\n\t\t],\n\t\t[\"tenantId\", \"shareGroupId\", \"suiteId\", \"preference\", \"provenance\", \"applicability\"],\n\t\t\"Memory atom\",\n\t);\n\tassertNonEmptyString(value.memoryId, \"Memory atom.memoryId\");\n\tassertNonEmptyString(value.contractVersion, \"Memory atom.contractVersion\");\n\tassertPositiveSafeInteger(value.schemaVersion, \"Memory atom.schemaVersion\");\n\tif (!MEMORY_SCOPES_V1.includes(value.scope as MemoryScopeV1)) throw new Error(\"Memory atom.scope is invalid\");\n\tassertNonEmptyString(value.retentionMode, \"Memory atom.retentionMode\");\n\tassertNonEmptyString(value.owner, \"Memory atom.owner\");\n\tassertNonEmptyString(value.profileId, \"Memory atom.profileId\");\n\tif (value.shareGroupId !== undefined) assertNonEmptyString(value.shareGroupId, \"Memory atom.shareGroupId\");\n\t// Legacy (pre-M5) atoms may carry protocol-level `null` for \"no suite\"; it\n\t// is tolerated here and normalized to an absent field (存量语义), while a\n\t// present suiteId must be a non-empty string.\n\tif (value.suiteId !== undefined && value.suiteId !== null) {\n\t\tassertNonEmptyString(value.suiteId, \"Memory atom.suiteId\");\n\t}\n\tassertNonEmptyString(value.retentionPolicyVersion, \"Memory atom.retentionPolicyVersion\");\n\tif (!MEMORY_KINDS_V1.includes(value.memoryKind as MemoryKindV1))\n\t\tthrow new Error(\"Memory atom.memoryKind is invalid\");\n\tassertJsonValue(value.payload, \"Memory atom.payload\");\n\tif (value.memoryKind === \"preference\" && value.preference === undefined) {\n\t\tthrow new Error(\"Memory atom.memoryKind preference requires a preference envelope\");\n\t}\n\tconst preference =\n\t\tvalue.preference === undefined\n\t\t\t? undefined\n\t\t\t: validatePreferenceEnvelope(value.preference, \"Memory atom.preference\");\n\tassertTimestamp(value.occurredAt, \"Memory atom.occurredAt\");\n\tassertTimestamp(value.recordedAt, \"Memory atom.recordedAt\");\n\tif (!Array.isArray(value.sourceRefs)) throw new Error(\"Memory atom.sourceRefs must be an array\");\n\tconst sourceRefs = value.sourceRefs.map((item, index) =>\n\t\tvalidateSourceRef(item, `Memory atom.sourceRefs[${index}]`),\n\t);\n\tassertNonEmptyString(value.observationId, \"Memory atom.observationId\");\n\tassertStringArray(value.sessionRefs, \"Memory atom.sessionRefs\");\n\tassertStringArray(value.agentInstanceRefs, \"Memory atom.agentInstanceRefs\");\n\tassertStringArray(value.projectRefs, \"Memory atom.projectRefs\");\n\tassertStringArray(value.subjectRefs, \"Memory atom.subjectRefs\");\n\tif (!Array.isArray(value.facets)) throw new Error(\"Memory atom.facets must be an array\");\n\tconst facets = value.facets.map((item, index) => validateFacet(item, `Memory atom.facets[${index}]`));\n\tif (!Array.isArray(value.relations)) throw new Error(\"Memory atom.relations must be an array\");\n\tconst relations = value.relations.map((item, index) => validateRelation(item, `Memory atom.relations[${index}]`));\n\tconst provenance =\n\t\tvalue.provenance === undefined ? undefined : validateProvenance(value.provenance, \"Memory atom.provenance\");\n\tassertUnitInterval(value.confidence, \"Memory atom.confidence\");\n\tassertUnitInterval(value.importance, \"Memory atom.importance\");\n\tconst applicability =\n\t\tvalue.applicability === undefined\n\t\t\t? undefined\n\t\t\t: validateApplicability(value.applicability, \"Memory atom.applicability\");\n\tif (!MEMORY_EVIDENCE_CLASSES_V1.includes(value.evidenceClass as MemoryEvidenceClassV1)) {\n\t\tthrow new Error(\"Memory atom.evidenceClass is invalid\");\n\t}\n\tassertNonEmptyString(value.contentRevision, \"Memory atom.contentRevision\");\n\tassertNonEmptyString(value.writeReason, \"Memory atom.writeReason\");\n\n\treturn detachedFreeze({\n\t\tmemoryId: value.memoryId,\n\t\tcontractVersion: value.contractVersion,\n\t\tschemaVersion: value.schemaVersion,\n\t\tscope: value.scope as MemoryScopeV1,\n\t\tretentionMode: value.retentionMode,\n\t\towner: value.owner,\n\t\tprofileId: value.profileId,\n\t\t...(value.shareGroupId === undefined ? {} : { shareGroupId: value.shareGroupId }),\n\t\t...(value.suiteId === undefined || value.suiteId === null ? {} : { suiteId: value.suiteId }),\n\t\tretentionPolicyVersion: value.retentionPolicyVersion,\n\t\tmemoryKind: value.memoryKind as MemoryKindV1,\n\t\tpayload: value.payload as TPayload,\n\t\t...(preference === undefined ? {} : { preference }),\n\t\toccurredAt: value.occurredAt,\n\t\trecordedAt: value.recordedAt,\n\t\tsourceRefs: Object.freeze(sourceRefs),\n\t\tobservationId: value.observationId,\n\t\tsessionRefs: Object.freeze([...value.sessionRefs]),\n\t\tagentInstanceRefs: Object.freeze([...value.agentInstanceRefs]),\n\t\tprojectRefs: Object.freeze([...value.projectRefs]),\n\t\tsubjectRefs: Object.freeze([...value.subjectRefs]),\n\t\tfacets: Object.freeze(facets),\n\t\trelations: Object.freeze(relations),\n\t\t...(provenance === undefined ? {} : { provenance }),\n\t\tconfidence: value.confidence,\n\t\timportance: value.importance,\n\t\t...(applicability === undefined ? {} : { applicability }),\n\t\tevidenceClass: value.evidenceClass as MemoryEvidenceClassV1,\n\t\tcontentRevision: value.contentRevision,\n\t\twriteReason: value.writeReason,\n\t}) as MemoryAtomV1<TPayload>;\n}\n\n/** Builds a detached, frozen canonical atom (validate + freeze). */\nexport function buildMemoryAtomV1<TPayload = JsonValue>(atom: MemoryAtomV1<TPayload>): MemoryAtomV1<TPayload> {\n\treturn validateMemoryAtomV1<TPayload>(atom);\n}\n\n/** FNV-1a 64-bit digest over the stable JSON serialization of `value`. */\nexport function memoryContentDigest(value: JsonValue): string {\n\tconst serialized = stableStringify(value);\n\tlet digest = 14695981039346656037n;\n\tfor (const byte of new TextEncoder().encode(serialized)) {\n\t\tdigest ^= BigInt(byte);\n\t\tdigest = BigInt.asUintN(64, digest * 1099511628211n);\n\t}\n\treturn digest.toString(16).padStart(16, \"0\");\n}\n\n/** Idempotent submission identity: the same (owner, observationId) is one observation. */\nexport function memoryObservationKey(owner: string, observationId: string): string {\n\tassertNonEmptyString(owner, \"owner\");\n\tassertNonEmptyString(observationId, \"observationId\");\n\treturn `${owner}\\u0000${observationId}`;\n}\n\n// ---------------------------------------------------------------------------\n// Suite (方案) read boundary (方案系统设计 §6.1/§11, M5)\n// ---------------------------------------------------------------------------\n\n/** Why a record was excluded from a suite-scoped read (读取边界惰性可观测). */\nexport type MemorySuiteVisibilityV1 =\n\t/** The atom matches the queried suite, or is an explicitly promoted user-default preference. */\n\t| \"visible\"\n\t/** Legacy (pre-M5) atom without a suiteId — fail-safe invisible to every suite. */\n\t| \"legacy\"\n\t/** The atom belongs to a different suite. */\n\t| \"foreign-suite\";\n\n/**\n * Skipped-record counters attached to suite-scoped reads. The read boundary is\n * lazy and observable (设计 §11 三段式): excluded atoms are counted, never\n * 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 * Suite-scoped visibility of one atom (方案系统设计 §6.1/§11):\n * - `atom.suiteId === suiteId` → visible;\n * - an explicitly promoted user-default preference (scope.level\n *   \"user-default\" WITH `confirmedAt` — the canonical explicit-confirmation\n *   marker set only by the explicit promotion channel) ignores the suiteId\n *   filter and is visible in every suite (§6.1 跨方案偏好);\n * - absent suiteId (legacy/存量) → invisible to every suite (fail-safe\n *   default), counted via {@link MemorySuiteFilterStatsV1};\n * - any other suiteId → invisible.\n */\nexport function memorySuiteVisibility(atom: MemoryAtomV1, suiteId: string): MemorySuiteVisibilityV1 {\n\tassertNonEmptyString(suiteId, \"suiteId\");\n\tif (\n\t\tatom.memoryKind === \"preference\" &&\n\t\tatom.preference?.scope.level === \"user-default\" &&\n\t\tatom.preference.confirmedAt !== undefined\n\t) {\n\t\treturn \"visible\";\n\t}\n\tif (atom.suiteId === undefined) return \"legacy\";\n\tif (atom.suiteId === suiteId) return \"visible\";\n\treturn \"foreign-suite\";\n}\n"]}

package/dist/memory/foundation.js

@@ -0,0 +1,487 @@
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertPlainRecord(value, label) {
+    if (!isPlainRecord(value))
+        throw new Error(`${label} must be a plain object`);
+}
+function assertExactKeys(value, required, optional, label) {
+    const allowed = new Set([...required, ...optional]);
+    const unsupported = Object.keys(value)
+        .filter((key) => !allowed.has(key))
+        .sort();
+    if (unsupported.length > 0)
+        throw new Error(`${label} has unsupported fields: ${unsupported.join(", ")}`);
+    for (const key of required) {
+        if (!(key in value))
+            throw new Error(`${label} is missing required field: ${key}`);
+    }
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+function assertPositiveSafeInteger(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${label} must be a positive safe integer`);
+    }
+}
+function assertUnitInterval(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`${label} must be a number between 0 and 1`);
+    }
+}
+function assertTimestamp(value, label) {
+    assertNonEmptyString(value, label);
+    if (Number.isNaN(Date.parse(value)))
+        throw new Error(`${label} must be an ISO-8601 timestamp`);
+}
+function assertJsonValue(value, label, seen = new WeakSet()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new Error(`${label} must contain finite JSON numbers`);
+    }
+    if (typeof value !== "object")
+        throw new Error(`${label} must be JSON-compatible`);
+    if (seen.has(value))
+        throw new Error(`${label} must not contain cycles`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const [index, child] of value.entries())
+            assertJsonValue(child, `${label}[${index}]`, seen);
+    }
+    else {
+        if (!isPlainRecord(value))
+            throw new Error(`${label} must contain only plain JSON objects`);
+        for (const [key, child] of Object.entries(value))
+            assertJsonValue(child, `${label}.${key}`, seen);
+    }
+    seen.delete(value);
+}
+function assertStringArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    for (const [index, item] of value.entries())
+        assertNonEmptyString(item, `${label}[${index}]`);
+}
+function detachedFreeze(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== "object")
+        return value;
+    const existing = seen.get(value);
+    // v8 ignore next -- 校验后的原子全部由新副本构成，不存在共享引用
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const child of value)
+            copy.push(detachedFreeze(child, seen));
+        return Object.freeze(copy);
+    }
+    const copy = Object.create(null);
+    seen.set(value, copy);
+    for (const [key, child] of Object.entries(value)) {
+        copy[key] = detachedFreeze(child, seen);
+    }
+    return Object.freeze(copy);
+}
+/** Stable JSON serialization with recursively sorted object keys (for identity digests). */
+function stableStringify(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(",")}}`;
+}
+const MEMORY_SCOPES_V1 = ["session", "cycle", "long-term"];
+const MEMORY_KINDS_V1 = [
+    "observation",
+    "preference",
+    "fact",
+    "decision",
+    "constraint",
+    "inference",
+    "synthesis",
+];
+const MEMORY_EVIDENCE_CLASSES_V1 = [
+    "explicit",
+    "repeated_behavior",
+    "tool_or_test",
+    "derived",
+];
+const SOURCE_REF_KINDS = ["session", "entry", "artifact", "tool", "state"];
+function validateSourceRef(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["kind", "id"], ["revision", "digest"], label);
+    if (!SOURCE_REF_KINDS.includes(value.kind)) {
+        throw new Error(`${label}.kind is invalid`);
+    }
+    assertNonEmptyString(value.id, `${label}.id`);
+    if (value.revision !== undefined)
+        assertNonEmptyString(value.revision, `${label}.revision`);
+    if (value.digest !== undefined)
+        assertNonEmptyString(value.digest, `${label}.digest`);
+    return detachedFreeze({
+        kind: value.kind,
+        id: value.id,
+        ...(value.revision === undefined ? {} : { revision: value.revision }),
+        ...(value.digest === undefined ? {} : { digest: value.digest }),
+    });
+}
+function validateFacet(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["namespace", "schemaVersion", "key", "value"], [], label);
+    assertNonEmptyString(value.namespace, `${label}.namespace`);
+    assertPositiveSafeInteger(value.schemaVersion, `${label}.schemaVersion`);
+    assertNonEmptyString(value.key, `${label}.key`);
+    assertNonEmptyString(value.value, `${label}.value`);
+    return detachedFreeze({
+        namespace: value.namespace,
+        schemaVersion: value.schemaVersion,
+        key: value.key,
+        value: value.value,
+    });
+}
+function validateRelation(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["relationId", "namespace", "schemaVersion", "kind", "relationRevision"], ["targetMemoryId", "targetRef", "confidence"], label);
+    assertNonEmptyString(value.relationId, `${label}.relationId`);
+    assertNonEmptyString(value.namespace, `${label}.namespace`);
+    assertPositiveSafeInteger(value.schemaVersion, `${label}.schemaVersion`);
+    assertNonEmptyString(value.kind, `${label}.kind`);
+    assertNonEmptyString(value.relationRevision, `${label}.relationRevision`);
+    if (value.targetMemoryId !== undefined && value.targetRef !== undefined) {
+        throw new Error(`${label} must not declare both targetMemoryId and targetRef`);
+    }
+    const targetMemoryId = value.targetMemoryId === undefined ? undefined : value.targetMemoryId;
+    if (targetMemoryId !== undefined)
+        assertNonEmptyString(targetMemoryId, `${label}.targetMemoryId`);
+    const targetRef = value.targetRef === undefined ? undefined : validateSourceRef(value.targetRef, `${label}.targetRef`);
+    if (value.confidence !== undefined)
+        assertUnitInterval(value.confidence, `${label}.confidence`);
+    return detachedFreeze({
+        relationId: value.relationId,
+        namespace: value.namespace,
+        schemaVersion: value.schemaVersion,
+        kind: value.kind,
+        ...(targetMemoryId === undefined ? {} : { targetMemoryId }),
+        ...(targetRef === undefined ? {} : { targetRef }),
+        ...(value.confidence === undefined ? {} : { confidence: value.confidence }),
+        relationRevision: value.relationRevision,
+    });
+}
+function validateTimeRange(value, label) {
+    assertPlainRecord(value, label);
+    // Key order reversed on purpose: in the natural order the boundary-gate
+    // lexical scanner reads this key pair as an import specifier (first key
+    // string, comma, second key string). `assertExactKeys` builds a Set, so the
+    // order is irrelevant to validation.
+    assertExactKeys(value, [], ["to", "from"], label);
+    const from = value.from === undefined ? undefined : value.from;
+    const to = value.to === undefined ? undefined : value.to;
+    if (from !== undefined)
+        assertTimestamp(from, `${label}.from`);
+    if (to !== undefined)
+        assertTimestamp(to, `${label}.to`);
+    return detachedFreeze({
+        ...(from === undefined ? {} : { from }),
+        ...(to === undefined ? {} : { to }),
+    });
+}
+function validateApplicability(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, [], ["scenes", "projects", "tasks", "timeRange", "exceptions"], label);
+    const timeRange = value.timeRange === undefined ? undefined : validateTimeRange(value.timeRange, `${label}.timeRange`);
+    return detachedFreeze({
+        ...(value.scenes === undefined ? {} : { scenes: Object.freeze([...value.scenes]) }),
+        ...(value.projects === undefined ? {} : { projects: Object.freeze([...value.projects]) }),
+        ...(value.tasks === undefined ? {} : { tasks: Object.freeze([...value.tasks]) }),
+        ...(timeRange === undefined ? {} : { timeRange }),
+        ...(value.exceptions === undefined
+            ? {}
+            : { exceptions: Object.freeze([...value.exceptions]) }),
+    });
+}
+function validatePreferenceEnvelope(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["subject", "key", "preferredValue", "scope", "evidence", "applicabilityConfidence"], ["alternatives", "confirmedAt"], label);
+    const subjects = ["user", "project", "task", "environment"];
+    if (!subjects.includes(value.subject)) {
+        throw new Error(`${label}.subject is invalid`);
+    }
+    assertNonEmptyString(value.key, `${label}.key`);
+    assertJsonValue(value.preferredValue, `${label}.preferredValue`);
+    if (value.alternatives !== undefined) {
+        if (!Array.isArray(value.alternatives))
+            throw new Error(`${label}.alternatives must be an array`);
+        for (const [index, item] of value.alternatives.entries()) {
+            assertJsonValue(item, `${label}.alternatives[${index}]`);
+        }
+    }
+    const scope = value.scope;
+    assertPlainRecord(scope, `${label}.scope`);
+    assertExactKeys(scope, ["level"], ["scenes", "projects", "tasks", "timeRange", "exceptions"], `${label}.scope`);
+    const levels = [
+        "task",
+        "project",
+        "scene",
+        "timeRange",
+        "profile-private",
+        "user-default",
+    ];
+    if (!levels.includes(scope.level)) {
+        throw new Error(`${label}.scope.level is invalid`);
+    }
+    // Anchor levels require their anchor to be present (记录模型约束).
+    const anchors = [
+        ["task", "tasks"],
+        ["project", "projects"],
+        ["scene", "scenes"],
+        ["timeRange", "timeRange"],
+    ];
+    for (const [level, field] of anchors) {
+        if (scope.level === level &&
+            (scope[field] === undefined || (Array.isArray(scope[field]) && scope[field].length === 0))) {
+            throw new Error(`${label}.scope.level "${level}" requires non-empty ${field}`);
+        }
+    }
+    const evidence = value.evidence;
+    assertPlainRecord(evidence, `${label}.evidence`);
+    assertExactKeys(evidence, ["class", "sourceRefs", "confidence"], [], `${label}.evidence`);
+    const evidenceClasses = [
+        "explicit",
+        "repeated_behavior",
+        "inferred",
+    ];
+    if (!evidenceClasses.includes(evidence.class)) {
+        throw new Error(`${label}.evidence.class is invalid`);
+    }
+    if (!Array.isArray(evidence.sourceRefs) || evidence.sourceRefs.length === 0) {
+        throw new Error(`${label}.evidence.sourceRefs must not be empty`);
+    }
+    const evidenceSourceRefs = evidence.sourceRefs.map((item, index) => validateSourceRef(item, `${label}.evidence.sourceRefs[${index}]`));
+    assertUnitInterval(evidence.confidence, `${label}.evidence.confidence`);
+    assertUnitInterval(value.applicabilityConfidence, `${label}.applicabilityConfidence`);
+    if (value.confirmedAt !== undefined)
+        assertTimestamp(value.confirmedAt, `${label}.confirmedAt`);
+    return detachedFreeze({
+        subject: value.subject,
+        key: value.key,
+        preferredValue: value.preferredValue,
+        ...(value.alternatives === undefined ? {} : { alternatives: Object.freeze([...value.alternatives]) }),
+        scope: detachedFreeze({
+            level: scope.level,
+            ...(scope.scenes === undefined ? {} : { scenes: Object.freeze([...scope.scenes]) }),
+            ...(scope.projects === undefined
+                ? {}
+                : { projects: Object.freeze([...scope.projects]) }),
+            ...(scope.tasks === undefined ? {} : { tasks: Object.freeze([...scope.tasks]) }),
+            ...(scope.timeRange === undefined
+                ? {}
+                : { timeRange: validateTimeRange(scope.timeRange, `${label}.scope.timeRange`) }),
+            ...(scope.exceptions === undefined
+                ? {}
+                : { exceptions: Object.freeze([...scope.exceptions]) }),
+        }),
+        evidence: detachedFreeze({
+            class: evidence.class,
+            sourceRefs: Object.freeze(evidenceSourceRefs),
+            confidence: evidence.confidence,
+        }),
+        applicabilityConfidence: value.applicabilityConfidence,
+        ...(value.confirmedAt === undefined ? {} : { confirmedAt: value.confirmedAt }),
+    });
+}
+function validateProvenance(value, label) {
+    assertPlainRecord(value, label);
+    assertExactKeys(value, ["sourceMemoryIds", "purgeGroupId", "containsSourceContent"], [], label);
+    assertStringArray(value.sourceMemoryIds, `${label}.sourceMemoryIds`);
+    if (value.sourceMemoryIds.length === 0)
+        throw new Error(`${label}.sourceMemoryIds must not be empty`);
+    assertNonEmptyString(value.purgeGroupId, `${label}.purgeGroupId`);
+    if (typeof value.containsSourceContent !== "boolean") {
+        throw new Error(`${label}.containsSourceContent must be boolean`);
+    }
+    return detachedFreeze({
+        sourceMemoryIds: Object.freeze([...value.sourceMemoryIds]),
+        purgeGroupId: value.purgeGroupId,
+        containsSourceContent: value.containsSourceContent,
+    });
+}
+/**
+ * Validates a canonical memory atom and returns a detached, deep-frozen
+ * snapshot. Unknown fields, wrong enums, non-JSON payloads, preference-kind
+ * atoms without a preference envelope, and identity fields (memoryId,
+ * observationId, contentRevision, owner) that are not non-empty strings are
+ * rejected.
+ */
+export function validateMemoryAtomV1(value) {
+    assertPlainRecord(value, "Memory atom");
+    assertExactKeys(value, [
+        "memoryId",
+        "contractVersion",
+        "schemaVersion",
+        "scope",
+        "retentionMode",
+        "owner",
+        "profileId",
+        "retentionPolicyVersion",
+        "memoryKind",
+        "payload",
+        "occurredAt",
+        "recordedAt",
+        "sourceRefs",
+        "observationId",
+        "sessionRefs",
+        "agentInstanceRefs",
+        "projectRefs",
+        "subjectRefs",
+        "facets",
+        "relations",
+        "confidence",
+        "importance",
+        "evidenceClass",
+        "contentRevision",
+        "writeReason",
+    ], ["tenantId", "shareGroupId", "suiteId", "preference", "provenance", "applicability"], "Memory atom");
+    assertNonEmptyString(value.memoryId, "Memory atom.memoryId");
+    assertNonEmptyString(value.contractVersion, "Memory atom.contractVersion");
+    assertPositiveSafeInteger(value.schemaVersion, "Memory atom.schemaVersion");
+    if (!MEMORY_SCOPES_V1.includes(value.scope))
+        throw new Error("Memory atom.scope is invalid");
+    assertNonEmptyString(value.retentionMode, "Memory atom.retentionMode");
+    assertNonEmptyString(value.owner, "Memory atom.owner");
+    assertNonEmptyString(value.profileId, "Memory atom.profileId");
+    if (value.shareGroupId !== undefined)
+        assertNonEmptyString(value.shareGroupId, "Memory atom.shareGroupId");
+    // Legacy (pre-M5) atoms may carry protocol-level `null` for "no suite"; it
+    // is tolerated here and normalized to an absent field (存量语义), while a
+    // present suiteId must be a non-empty string.
+    if (value.suiteId !== undefined && value.suiteId !== null) {
+        assertNonEmptyString(value.suiteId, "Memory atom.suiteId");
+    }
+    assertNonEmptyString(value.retentionPolicyVersion, "Memory atom.retentionPolicyVersion");
+    if (!MEMORY_KINDS_V1.includes(value.memoryKind))
+        throw new Error("Memory atom.memoryKind is invalid");
+    assertJsonValue(value.payload, "Memory atom.payload");
+    if (value.memoryKind === "preference" && value.preference === undefined) {
+        throw new Error("Memory atom.memoryKind preference requires a preference envelope");
+    }
+    const preference = value.preference === undefined
+        ? undefined
+        : validatePreferenceEnvelope(value.preference, "Memory atom.preference");
+    assertTimestamp(value.occurredAt, "Memory atom.occurredAt");
+    assertTimestamp(value.recordedAt, "Memory atom.recordedAt");
+    if (!Array.isArray(value.sourceRefs))
+        throw new Error("Memory atom.sourceRefs must be an array");
+    const sourceRefs = value.sourceRefs.map((item, index) => validateSourceRef(item, `Memory atom.sourceRefs[${index}]`));
+    assertNonEmptyString(value.observationId, "Memory atom.observationId");
+    assertStringArray(value.sessionRefs, "Memory atom.sessionRefs");
+    assertStringArray(value.agentInstanceRefs, "Memory atom.agentInstanceRefs");
+    assertStringArray(value.projectRefs, "Memory atom.projectRefs");
+    assertStringArray(value.subjectRefs, "Memory atom.subjectRefs");
+    if (!Array.isArray(value.facets))
+        throw new Error("Memory atom.facets must be an array");
+    const facets = value.facets.map((item, index) => validateFacet(item, `Memory atom.facets[${index}]`));
+    if (!Array.isArray(value.relations))
+        throw new Error("Memory atom.relations must be an array");
+    const relations = value.relations.map((item, index) => validateRelation(item, `Memory atom.relations[${index}]`));
+    const provenance = value.provenance === undefined ? undefined : validateProvenance(value.provenance, "Memory atom.provenance");
+    assertUnitInterval(value.confidence, "Memory atom.confidence");
+    assertUnitInterval(value.importance, "Memory atom.importance");
+    const applicability = value.applicability === undefined
+        ? undefined
+        : validateApplicability(value.applicability, "Memory atom.applicability");
+    if (!MEMORY_EVIDENCE_CLASSES_V1.includes(value.evidenceClass)) {
+        throw new Error("Memory atom.evidenceClass is invalid");
+    }
+    assertNonEmptyString(value.contentRevision, "Memory atom.contentRevision");
+    assertNonEmptyString(value.writeReason, "Memory atom.writeReason");
+    return detachedFreeze({
+        memoryId: value.memoryId,
+        contractVersion: value.contractVersion,
+        schemaVersion: value.schemaVersion,
+        scope: value.scope,
+        retentionMode: value.retentionMode,
+        owner: value.owner,
+        profileId: value.profileId,
+        ...(value.shareGroupId === undefined ? {} : { shareGroupId: value.shareGroupId }),
+        ...(value.suiteId === undefined || value.suiteId === null ? {} : { suiteId: value.suiteId }),
+        retentionPolicyVersion: value.retentionPolicyVersion,
+        memoryKind: value.memoryKind,
+        payload: value.payload,
+        ...(preference === undefined ? {} : { preference }),
+        occurredAt: value.occurredAt,
+        recordedAt: value.recordedAt,
+        sourceRefs: Object.freeze(sourceRefs),
+        observationId: value.observationId,
+        sessionRefs: Object.freeze([...value.sessionRefs]),
+        agentInstanceRefs: Object.freeze([...value.agentInstanceRefs]),
+        projectRefs: Object.freeze([...value.projectRefs]),
+        subjectRefs: Object.freeze([...value.subjectRefs]),
+        facets: Object.freeze(facets),
+        relations: Object.freeze(relations),
+        ...(provenance === undefined ? {} : { provenance }),
+        confidence: value.confidence,
+        importance: value.importance,
+        ...(applicability === undefined ? {} : { applicability }),
+        evidenceClass: value.evidenceClass,
+        contentRevision: value.contentRevision,
+        writeReason: value.writeReason,
+    });
+}
+/** Builds a detached, frozen canonical atom (validate + freeze). */
+export function buildMemoryAtomV1(atom) {
+    return validateMemoryAtomV1(atom);
+}
+/** FNV-1a 64-bit digest over the stable JSON serialization of `value`. */
+export function memoryContentDigest(value) {
+    const serialized = stableStringify(value);
+    let digest = 14695981039346656037n;
+    for (const byte of new TextEncoder().encode(serialized)) {
+        digest ^= BigInt(byte);
+        digest = BigInt.asUintN(64, digest * 1099511628211n);
+    }
+    return digest.toString(16).padStart(16, "0");
+}
+/** Idempotent submission identity: the same (owner, observationId) is one observation. */
+export function memoryObservationKey(owner, observationId) {
+    assertNonEmptyString(owner, "owner");
+    assertNonEmptyString(observationId, "observationId");
+    return `${owner}\u0000${observationId}`;
+}
+/**
+ * Suite-scoped visibility of one atom (方案系统设计 §6.1/§11):
+ * - `atom.suiteId === suiteId` → visible;
+ * - an explicitly promoted user-default preference (scope.level
+ *   "user-default" WITH `confirmedAt` — the canonical explicit-confirmation
+ *   marker set only by the explicit promotion channel) ignores the suiteId
+ *   filter and is visible in every suite (§6.1 跨方案偏好);
+ * - absent suiteId (legacy/存量) → invisible to every suite (fail-safe
+ *   default), counted via {@link MemorySuiteFilterStatsV1};
+ * - any other suiteId → invisible.
+ */
+export function memorySuiteVisibility(atom, suiteId) {
+    assertNonEmptyString(suiteId, "suiteId");
+    if (atom.memoryKind === "preference" &&
+        atom.preference?.scope.level === "user-default" &&
+        atom.preference.confirmedAt !== undefined) {
+        return "visible";
+    }
+    if (atom.suiteId === undefined)
+        return "legacy";
+    if (atom.suiteId === suiteId)
+        return "visible";
+    return "foreign-suite";
+}
+//# sourceMappingURL=foundation.js.map