@weiliang0121/capix-memory 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @weiliang0121/capix-memory
 
-Versioned memory entities and controlled resource access for CAPiX.
+Independent, revisable summaries and controlled resource access for CAPiX. A collection does not require a Transcript, topic, message sources, or file receipts.
 
 ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
 
@@ -14,6 +14,58 @@ npm install @weiliang0121/capix-memory
 
 This package is part of CAPiX. The npm distribution contains compiled JavaScript, type declarations, and this package's MIT license. Reference services and client applications are not included in this package or the initial npm release.
 
+## Content and current reads
+
+`Memories<Metadata = never>` is the only write owner. Each immutable `MemoryItem` has an independent UUID and a `value: { content: string; metadata?: Metadata }`. Updating an item preserves its ID and replaces the entire value, including optional metadata. Selection, extraction, source validation, and retention belong to the application.
+
+```ts
+import { Memories, memoryResources } from '@weiliang0121/capix-memory';
+import { Resource, Resources } from '@weiliang0121/capix-resources';
+
+const memories = new Memories<{ topic?: string }>();
+const created = memories.apply([{ action: 'create', value: { content: 'Prefer concise answers', metadata: { topic: 'preference' } } }]);
+const first = memories.read(created.changed[0].id)!;
+memories.apply([{ action: 'update', memoryId: first.id, value: { content: 'Explain complex questions in detail' }, reason: 'Clarified preference' }], { expected: first.basis });
+// first remains the original fixed material; the current item has no metadata.
+
+const memory = memoryResources<{ topic?: string }>();
+const resource = new Resource(memories);
+const resources = new Resources().register(resource, memory.read).register(resource, memory.apply);
+// Share these Offer objects with authors: memory.read.request() / memory.apply.request().
+```
+
+`read(id)` returns `{id,basis:{memoriesId,sequence},value}` or undefined. `values()` explicitly enumerates fixed items; `snapshot()` returns `{basis,items}`. `apply(changes, {expected?})` returns `{before,after,changed}`, containing only actual content changes. An omitted expected basis provides no stale-write protection. Optional reason describes the operation; changing only reason does not change content or advance sequence.
+
+`memoryResources<Metadata>()` creates a typed pair of Offers. The read endpoint provides `read(id)` and explicit `snapshot()`; apply provides `apply(changes, expected?)` and `applyFixed({position,changes}, expected?)`. Binding does not capture the collection. `MemoryViewSource<Metadata>` supplies whole or fixed ordered subsets, checks collection sequence, returns fixed `{id,value}`, and uses undefined summaries. Entity updates and View membership remain separate operations.
+
+## Fixed effects and persistence
+
+`applyFixed(request)` and `confirmFixed(request)` use `memories.apply` v2 requests with content contract, memoriesId, accurate `operation: {contextId}`, author `command: {position,changes}` with optional per-change reason, and original expected basis. The entire command and basis are fixed inside the entity write guard. Resource writes derive contextId from the actual calling operation; the application supplies position. The receipt contains `{memoriesId,startSequence,sequence,changes:[{commandIndex,memoryId}]}`. The same operation must match the entire original request, and confirmation returns the original receipt even after later content changes. First fixed no-ops persist confirmation without a content event.
+
+```ts
+const request = {
+  contract: { key: 'memories.apply', version: 2 } as const,
+  contentContract: memories.contentContract,
+  memoriesId: memories.id,
+  operation: { contextId },
+  command: { position: 'remember-answer', changes },
+  expected,
+};
+const receipt = memories.applyFixed(request);
+```
+
+`exportState()` and `Memories.restore(state, options?)` use current format v2. Restore is silent, preserves identities and confirmations, and rejects old formats. Optional `contentContract: {key,version,check?}` validates fixed content synchronously; TypeScript metadata types alone do not validate runtime input.
+
+Exported state, commit payloads, events, and reads contain Stable values, not an automatic JSON representation. An adapter that supports undefined, negative zero, or null-prototype records must explicitly encode and decode those distinctions, including fixed requests and receipts. Check encoding and capacity before external writes. Checkpoint authors likewise supply faithful codecs; a display projection cannot replace recovery material.
+
+`persistence.commit` synchronously commits incremental upserts and any fixed confirmation together. If it throws or violates the synchronous return contract, the instance treats the outcome as uncertain: reload from authoritative storage before current reads or further writes. Previously delivered material remains valid, and known exact receipts remain confirmable; an unknown receipt cannot establish that an operation did not execute. Publication failure occurs after installation and does not undo content or confirmation.
+
+## Domain events and display projections
+
+`MemoryEvent<Metadata>` and `MemoryFacts` belong to this package. Each event identifies memoriesId, sequence, time, optional origin, and `{action,memoryId,value,reason?}`. Forwarding uses typed facts; an independent change without origin does not acquire an inferred calling identity.
+
+Default records deliberately project only content and optional reason, omitting unknown metadata. The framework protocol package does not define Memory wire DTOs. Baseline and incremental display values use the same projection. Applications that need topic, source links, or other metadata must define their own projection and encoding. Applications own their persistence adapters and wire DTOs; display projections are not complete entity snapshots or recovery material.
+
 ## License
 
-MIT. Copyright (c) 2026 wei.liang. See [LICENSE](./LICENSE).
+MIT. Copyright (c) 2026 wei.liang. See [LICENSE](LICENSE).

package/dist/apply.d.ts

@@ -1,23 +1,31 @@
-import type { MemoryChange } from './change.js';
-export interface MemoryFixedApply {
+import type { MemoryMutation } from './change.js';
+import type { MemoryBasis, MemoryContentContractIdentity } from './memory.js';
+export interface MemoryFixedApply<Metadata = never> {
     readonly contract: {
         readonly key: 'memories.apply';
-        readonly version: 1;
+        readonly version: 2;
     };
+    readonly contentContract: MemoryContentContractIdentity;
     readonly operation: {
         readonly contextId: string;
-        readonly position: string;
     };
     readonly memoriesId: string;
-    readonly changes: readonly MemoryChange[];
+    readonly command: {
+        readonly position: string;
+        readonly changes: readonly MemoryMutation<Metadata>[];
+    };
+    readonly expected?: MemoryBasis;
 }
 export interface MemoryApplyReceipt {
     readonly memoriesId: string;
     readonly startSequence: number;
     readonly sequence: number;
-    readonly memoryIds: readonly string[];
+    readonly changes: readonly {
+        readonly commandIndex: number;
+        readonly memoryId: string;
+    }[];
 }
-export interface MemoryApplyState {
-    readonly request: MemoryFixedApply;
+export interface MemoryApplyState<Metadata = never> {
+    readonly request: MemoryFixedApply<Metadata>;
     readonly receipt: MemoryApplyReceipt;
 }

package/dist/change.d.ts

@@ -1,15 +1,10 @@
-import type { MemoryContent, MemoryResultSource } from '@weiliang0121/capix-protocol';
-import type { Transcript } from '@weiliang0121/capix-transcript';
-export type MemoryChange = {
-    readonly change: string;
-    readonly sourceIndexes: readonly number[];
-    readonly sourceResults?: readonly MemoryResultSource[];
-    readonly result: MemoryContent;
-} & ({
+import type { MemoryContent } from './memory.js';
+export type MemoryMutation<Metadata = never> = ({
     readonly action: 'create';
-    readonly memoryId: null;
 } | {
     readonly action: 'update';
     readonly memoryId: string;
-});
-export declare function prepareMemoryChanges(transcript: Transcript, changes: readonly MemoryChange[]): readonly MemoryChange[];
+}) & {
+    readonly value: MemoryContent<Metadata>;
+    readonly reason?: string;
+};

package/dist/change.js

@@ -1,2 +1 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isEqual}from"es-toolkit/predicate";import{isArray}from"es-toolkit/compat";import{Memory}from"./memory.js";import{prepareMemoryResultSources}from"./source.js";import{hasUniqueItems,isNonBlankString,isNonEmptyArray,isObject}from"./validation.js";function prepareMemoryChanges(transcript,changes){if(!isArray(changes))throw new TypeError("Memory changes must be an array");return Object.freeze(Array.from(changes,change=>prepareMemoryChange(transcript,change)))}__name(prepareMemoryChanges,"prepareMemoryChanges");function prepareMemoryChange(transcript,value){if(!isObject(value))throw new TypeError("Memory change requires an explanation and unique evidence");const action=value.action,memoryId=value.memoryId,change=value.change,evidence=value.sourceIndexes;if(!isNonBlankString(change)||!isNonEmptyArray(evidence))throw new TypeError("Memory change requires an explanation and unique evidence");const sourceIndexes=Object.freeze([...evidence]);if(!isNonEmptyArray(sourceIndexes)||!hasUniqueItems(sourceIndexes))throw new TypeError("Memory change requires an explanation and unique evidence");for(const index of sourceIndexes)transcript.ref(index);const sourceResults=prepareMemoryResultSources(transcript,value.sourceResults),result=Memory.prepare(transcript,value.result);if(!sourceIndexes.every(index=>result.sourceIndexes.includes(index)))throw new Error("Memory result must include change evidence");if(sourceResults?.some(source=>!result.sourceResults?.some(candidate=>isEqual(source,candidate))))throw new Error("Memory result must include the unchanged result sources of this change");if(action==="create"){if(memoryId!==null)throw new Error("Creating memory cannot specify an existing identity");return Object.freeze({action,memoryId,change,sourceIndexes,...sourceResults?{sourceResults}:{},result})}if(action!=="update")throw new Error("Unknown memory change action");if(!isNonBlankString(memoryId))throw new TypeError("Memory update requires an identity");return Object.freeze({action,memoryId,change,sourceIndexes,...sourceResults?{sourceResults}:{},result})}__name(prepareMemoryChange,"prepareMemoryChange");export{prepareMemoryChanges};

package/dist/event.d.ts

@@ -0,0 +1,17 @@
+import { FactType } from '@weiliang0121/capix-changes';
+import type { InvocationOrigin, Stable } from '@weiliang0121/capix-contracts';
+import type { MemoryContent } from './memory.js';
+export interface MemoryEvent<Metadata = never> {
+    readonly type: 'memory';
+    readonly memoriesId: string;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly origin?: InvocationOrigin;
+    readonly change: {
+        readonly action: 'create' | 'update';
+        readonly memoryId: string;
+        readonly value: Stable<MemoryContent<Metadata>>;
+        readonly reason?: string;
+    };
+}
+export declare const MemoryFacts: FactType<MemoryEvent<unknown>>;

package/dist/event.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{FactType}from"@weiliang0121/capix-changes";const MemoryFacts=new FactType("memory");export{MemoryFacts};

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { Memory } from './memory.js';
-export { Memories, type MemoriesOptions } from './memories.js';
-export type { MemoryChange } from './change.js';
+export { Memories, type MemoriesOptions, type MemoryApplyOptions } from './memories.js';
+export type { MemoryContent, MemoryItem, MemoryBasis, MemoryRead, MemorySnapshot, MemoryApplication, MemoryContentContract, MemoryContentContractIdentity } from './memory.js';
+export type { MemoryMutation } from './change.js';
 export type { MemoryFixedApply, MemoryApplyReceipt, MemoryApplyState } from './apply.js';
-export type { MemoryState, MemoriesState, MemoriesCommit, MemoriesPersistence } from './persistence.js';
-export { MemoryResource, type CapturedMemories, type MemoryBasis, type MemoryApplication } from './resource.js';
-export { MemoryViewSource, type MemoryViewSummary } from './view.js';
+export type { MemoriesState, MemoriesCommit, MemoriesPersistence } from './persistence.js';
+export { memoryResources } from './resource.js';
+export { MemoryViewSource } from './view.js';
+export { MemoryFacts, type MemoryEvent } from './event.js';

package/dist/index.js

@@ -1,2 +1,2 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-import{Memory}from"./memory.js";import{Memories}from"./memories.js";import{MemoryResource}from"./resource.js";import{MemoryViewSource}from"./view.js";export{Memories,Memory,MemoryResource,MemoryViewSource};
+import{Memories}from"./memories.js";import{memoryResources}from"./resource.js";import{MemoryViewSource}from"./view.js";import{MemoryFacts}from"./event.js";export{Memories,MemoryFacts,MemoryViewSource,memoryResources};

package/dist/memories.d.ts

@@ -1,40 +1,44 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
 import { type ChangeProvenance, type EventConsumer, type ChangeCapture } from '@weiliang0121/capix-changes';
-import type { MemoryEvent } from '@weiliang0121/capix-protocol';
-import { Memory } from './memory.js';
-import { type MemoryChange } from './change.js';
-import type { Transcript } from '@weiliang0121/capix-transcript';
+import type { MemoryEvent } from './event.js';
+import type { MemoryMutation } from './change.js';
+import type { MemoryApplication, MemoryBasis, MemoryContentContract, MemoryContentContractIdentity, MemoryItem, MemoryRead, MemorySnapshot } from './memory.js';
 import type { MemoriesPersistence, MemoriesState } from './persistence.js';
 import type { MemoryFixedApply, MemoryApplyReceipt } from './apply.js';
-export interface MemoriesOptions {
-    observation?: EventConsumer<MemoryEvent>;
-    changes?: ChangeCapture<MemoryEvent>;
-    persistence?: MemoriesPersistence;
+export interface MemoriesOptions<Metadata = never> {
+    readonly contentContract?: MemoryContentContract<Metadata>;
+    readonly observation?: EventConsumer<MemoryEvent<Metadata>>;
+    readonly changes?: ChangeCapture<MemoryEvent<Metadata>>;
+    readonly persistence?: MemoriesPersistence<Metadata>;
 }
-export declare class Memories {
+export interface MemoryApplyOptions<Metadata = never> extends ChangeProvenance<MemoryEvent<Metadata>> {
+    readonly expected?: MemoryBasis;
+}
+export declare class Memories<Metadata = never> {
     #private;
-    readonly transcript: Transcript;
+    constructor(options?: MemoriesOptions<Metadata>);
     get id(): string;
+    get contentContract(): Stable<MemoryContentContractIdentity>;
     get sequence(): number;
-    private readonly observation?;
-    private readonly changes?;
-    private readonly persistence?;
-    constructor(transcript: Transcript, options?: MemoriesOptions);
-    static restore(state: MemoriesState, transcript: Transcript, options?: MemoriesOptions): Memories;
-    exportState(): MemoriesState;
-    get(id: string): Memory | undefined;
-    values(): readonly Memory[];
-    snapshot(): {
-        topic: string;
-        content: string;
-        sourceIndexes: readonly number[];
-        sourceResults?: readonly import("@weiliang0121/capix-protocol").MemoryResultSource[];
-        id: string;
-    }[];
-    apply(changes: readonly MemoryChange[], provenance?: ChangeProvenance<MemoryEvent>): readonly Memory[];
-    confirmFixed(value: MemoryFixedApply): MemoryApplyReceipt | undefined;
-    applyFixed(value: MemoryFixedApply, provenance?: ChangeProvenance<MemoryEvent>): MemoryApplyReceipt;
+    read(id: string): MemoryRead<Metadata> | undefined;
+    values(): Stable<readonly MemoryItem<Metadata>[]>;
+    snapshot(): Stable<MemorySnapshot<Metadata>>;
+    exportState(): Stable<MemoriesState<Metadata>>;
+    static restore<Metadata = never>(value: MemoriesState<Metadata> | Stable<MemoriesState<Metadata>>, options?: MemoriesOptions<Metadata>): Memories<Metadata>;
+    apply(changes: readonly MemoryMutation<Metadata>[] | Stable<readonly MemoryMutation<Metadata>[]>, options?: MemoryApplyOptions<Metadata>): Stable<MemoryApplication<Metadata>>;
+    confirmFixed(value: MemoryFixedApply<Metadata> | Stable<MemoryFixedApply<Metadata>>): Stable<MemoryApplyReceipt> | undefined;
+    applyFixed(value: MemoryFixedApply<Metadata> | Stable<MemoryFixedApply<Metadata>>, provenance?: ChangeProvenance<MemoryEvent<Metadata>>): Stable<MemoryApplyReceipt>;
+    private protect;
+    private requireCertain;
+    private basis;
+    private validateBasis;
+    private validateContent;
+    private acceptChanges;
     private acceptFixed;
     private confirmAccepted;
+    private acceptProvenance;
     private applyPrepared;
     private commit;
+    private acceptReceipt;
+    private validateTimeline;
 }

package/dist/memories.js

@@ -1,2 +1,2 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{publishFact,combineFaults}from"@weiliang0121/capix-changes";import{randomUUID}from"node:crypto";import{isEqual}from"es-toolkit/predicate";import{Memory,restoreMemory,updateMemory}from"./memory.js";import{prepareMemoryChanges}from"./change.js";import{isNonBlankString,hasUniqueItems,isObject}from"./validation.js";import{isArray,isSafeInteger}from"es-toolkit/compat";import{RuntimeError}from"@weiliang0121/capix-contracts";import{PersistenceError}from"@weiliang0121/capix-diagnostics";class Memories{static{__name(this,"Memories")}transcript;#id=randomUUID();#sequence=0;#mutating=!1;get id(){return this.#id}get sequence(){return this.#sequence}#items=new Map;#applies=new Map;observation;changes;persistence;constructor(transcript,options={}){this.transcript=transcript,this.observation=options.observation,this.changes=options.changes,this.persistence=options.persistence}static restore(state,transcript,options={}){if(!isObject(state)||!isNonBlankString(state.id)||state.transcriptId!==transcript.id||!isArray(state.items))throw new TypeError("Invalid persisted memory collection");if(!isSafeInteger(state.sequence)||state.sequence<state.items.length||!state.items.length&&state.sequence!==0)throw new TypeError("Invalid persisted memory sequence");const restored=new Memories(transcript,options);for(const item of state.items){const memory=restoreMemory(transcript,item);if(restored.#items.has(memory.id))throw new TypeError("Duplicate persisted memory identity");restored.#items.set(memory.id,memory)}if(restored.#id=state.id,restored.#sequence=state.sequence,state.applies!==void 0){if(!isArray(state.applies))throw new TypeError("Invalid persisted memory applies");let previousSequence=0;for(const saved of state.applies){const request=restored.acceptFixed(saved.request),receipt=saved.receipt;if(!isObject(receipt)||receipt.memoriesId!==restored.id||!isSafeInteger(receipt.startSequence)||receipt.startSequence<previousSequence||!isSafeInteger(receipt.sequence)||receipt.sequence<receipt.startSequence||receipt.sequence>state.sequence||!isArray(receipt.memoryIds)||!hasUniqueItems(receipt.memoryIds)||receipt.memoryIds.length!==receipt.sequence-receipt.startSequence||receipt.memoryIds.some(id=>!restored.#items.has(id)))throw new TypeError("Invalid persisted memory apply receipt");const key=applyKey(request);if(restored.#applies.has(key))throw new TypeError("Duplicate persisted memory apply operation");restored.#applies.set(key,Object.freeze({request,receipt:Object.freeze({memoriesId:restored.id,startSequence:receipt.startSequence,sequence:receipt.sequence,memoryIds:Object.freeze([...receipt.memoryIds])})})),previousSequence=receipt.sequence}}return restored}exportState(){return Object.freeze({id:this.id,transcriptId:this.transcript.id,sequence:this.#sequence,items:Object.freeze(this.values().map(memory=>Object.freeze(memory.toJSON()))),...this.#applies.size?{applies:Object.freeze([...this.#applies.values()])}:{}})}get(id){return this.#items.get(id)}values(){return[...this.#items.values()]}snapshot(){return this.values().map(memory=>memory.toJSON())}apply(changes,provenance={}){if(this.#mutating)throw new Error("Memory persistence or change publication cannot reenter mutation");this.#mutating=!0;try{return this.applyPrepared(prepareMemoryChanges(this.transcript,changes),provenance)}finally{this.#mutating=!1}}confirmFixed(value){return this.confirmAccepted(this.acceptFixed(value))}applyFixed(value,provenance={}){if(this.#mutating)throw new Error("Memory persistence or change publication cannot reenter mutation");this.#mutating=!0;try{const request=this.acceptFixed(value),receipt=this.confirmAccepted(request);return receipt||(this.applyPrepared(request.changes,provenance,request),this.#applies.get(applyKey(request)).receipt)}finally{this.#mutating=!1}}acceptFixed(value){if(!isObject(value))throw new TypeError("Invalid fixed memory apply request");const contract=value.contract,origin=value.operation;if(contract?.key!=="memories.apply"||contract.version!==1||value.memoriesId!==this.id||!isObject(origin))throw new TypeError("Invalid fixed memory apply request");const operation=Object.freeze({contextId:origin.contextId,position:origin.position});if(!isNonBlankString(operation.contextId)||!isNonBlankString(operation.position))throw new TypeError("Invalid fixed memory apply request");const changes=prepareMemoryChanges(this.transcript,value.changes);return Object.freeze({contract:Object.freeze({key:"memories.apply",version:1}),operation,memoriesId:this.id,changes})}confirmAccepted(request){const saved=this.#applies.get(applyKey(request));if(saved&&!isEqual(saved.request,request))throw new RuntimeError("MEMORY_APPLY_CONFLICT","\u56FA\u5B9A\u8BB0\u5FC6\u6279\u6B21\u4E0E\u539F\u64CD\u4F5C\u4E0D\u4E00\u81F4\u3002");return saved?.receipt}applyPrepared(changes,provenance,request){const targets=new Set,prepared=changes.map(change=>{const result=change.result,sourceResults=change.sourceResults;if(change.action==="create")return{change,result,sourceResults,memory:void 0};const memory=this.#items.get(change.memoryId);if(!memory)throw new Error("Memory update target does not exist in this Runtime");for(const source of result.sourceResults??[]){const previous=memory.sourceResults?.find(candidate=>candidate.id===source.id);if(previous&&!isEqual(previous,source))throw new Error("Memory result source identity cannot change its receipt")}if(targets.has(memory.id))throw new Error("A batch cannot update the same memory twice");return targets.add(memory.id),{change,result,sourceResults,memory}}),mutations=[];for(const{change,result,sourceResults,memory:previous}of prepared){if(previous&&isEqual(previous.snapshot(),result))continue;const memory=previous??new Memory(this.transcript,result),sequence2=this.#sequence+mutations.length+1;if(!isSafeInteger(sequence2))throw new RangeError("Memory sequence is exhausted");const event=Object.freeze({type:"memory",memoriesId:this.id,sequence:sequence2,occurredAt:new Date().toISOString(),...provenance.origin?{origin:Object.freeze({...provenance.origin})}:{},change:Object.freeze({action:change.action,memoryId:memory.id,explanation:change.change,sourceIndexes:Object.freeze([...change.sourceIndexes]),...sourceResults?{sourceResults}:{},result})});mutations.push({memory,event,created:!previous})}if(!mutations.length&&!request)return[];const sequence=mutations.at(-1)?.event.sequence??this.#sequence,upserts=Object.freeze(mutations.map(({memory,event})=>Object.freeze({id:memory.id,...event.change.result}))),fixed=request?Object.freeze({request,receipt:Object.freeze({memoriesId:this.id,startSequence:this.#sequence,sequence,memoryIds:Object.freeze(upserts.map(memory=>memory.id))})}):void 0;this.commit(Object.freeze({memoriesId:this.id,transcriptId:this.transcript.id,expectedSequence:this.#sequence,sequence,upserts,...fixed?{fixed}:{}}));for(const{memory,event,created}of mutations)created?this.#items.set(memory.id,memory):updateMemory(memory,event.change.result);this.#sequence=sequence,fixed&&this.#applies.set(applyKey(fixed.request),fixed);const faults=[];for(const{event}of mutations)try{publishFact(event,this.changes,provenance.observation??this.observation)}catch(error){faults.push(error)}const fault=combineFaults(faults);if(fault!==void 0)throw fault;return mutations.map(({memory})=>memory)}commit(change){try{const result=this.persistence?.commit(change);if(result!==void 0)throw Promise.resolve(result).catch(()=>{}),new TypeError("Memory persistence must complete synchronously and return undefined")}catch(cause){throw cause instanceof PersistenceError?cause:new PersistenceError("memories.commit",cause)}}}function applyKey(request){return JSON.stringify([request.operation.contextId,request.operation.position])}__name(applyKey,"applyKey");export{Memories};
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{randomUUID}from"node:crypto";import{RuntimeError,stableValue}from"@weiliang0121/capix-contracts";import{publishFact,combineFaults}from"@weiliang0121/capix-changes";import{PersistenceError}from"@weiliang0121/capix-diagnostics";import{equalStable,hasOnlyKeys,isNonBlankString,isRecord,isUuid}from"./validation.js";class Memories{static{__name(this,"Memories")}#id=randomUUID();#sequence=0;#mutating=!1;#uncertain;#items=new Map;#applies=new Map;#contentContract;#check;#observation;#changes;#persistence;constructor(options={}){const fields=dataOptions(options,["contentContract","observation","changes","persistence"]),contract=fields.contentContract===void 0?{key:"memory.content",version:1}:dataOptions(fields.contentContract,["key","version","check"]);if(this.#contentContract=stableValue({key:contract.key,version:contract.version}),validateContract(this.#contentContract),contract.check!==void 0&&typeof contract.check!="function")throw new TypeError("Memory content check must be a function");this.#check=contract.check,this.#observation=fields.observation,this.#changes=fields.changes,this.#persistence=fields.persistence}get id(){return this.#id}get contentContract(){return this.#contentContract}get sequence(){return this.requireCertain(),this.#sequence}read(id){this.requireCertain();const item=this.#items.get(id);return item===void 0?void 0:stableValue({id:item.id,basis:this.basis(),value:item.value})}values(){return this.requireCertain(),stableValue([...this.#items.values()])}snapshot(){return this.requireCertain(),stableValue({basis:this.basis(),items:this.values()})}exportState(){return this.requireCertain(),stableValue({version:2,id:this.id,contentContract:this.contentContract,sequence:this.#sequence,items:this.values(),...this.#applies.size?{applies:[...this.#applies.values()]}:{}})}static restore(value,options={}){const restored=new Memories(options);restored.#mutating=!0;try{const state=stableValue(value);if(!isRecord(state)||!hasOnlyKeys(state,["version","id","contentContract","sequence","items"],["applies"])||state.version!==2||!isUuid(state.id)||!Array.isArray(state.items)||!Number.isSafeInteger(state.sequence)||state.sequence<state.items.length||state.items.length===0&&state.sequence!==0)throw new TypeError("Invalid current memory state");if(validateContract(state.contentContract),!equalStable(state.contentContract,restored.contentContract))throw new TypeError("Memory content contract does not match persisted material");restored.#id=state.id,restored.#sequence=state.sequence;for(const item of state.items){if(!isRecord(item)||!hasOnlyKeys(item,["id","value"])||!isUuid(item.id)||restored.#items.has(item.id))throw new TypeError("Invalid or duplicate persisted memory identity");restored.validateContent(item.value),restored.#items.set(item.id,item)}const births=new Map,deadlines=new Map,reserved=new Set;if(state.applies!==void 0){if(!Array.isArray(state.applies))throw new TypeError("Invalid persisted memory applies");let previousSequence=0;for(const saved of state.applies){if(!isRecord(saved)||!hasOnlyKeys(saved,["request","receipt"]))throw new TypeError("Invalid persisted memory apply");const request=restored.acceptFixed(saved.request),receipt=restored.acceptReceipt(saved.receipt,request,previousSequence,births,deadlines,reserved),key=applyKey(request);if(restored.#applies.has(key))throw new TypeError("Duplicate persisted memory apply operation");restored.#applies.set(key,stableValue({request,receipt})),previousSequence=receipt.sequence}}return restored.validateTimeline(births,deadlines,reserved),restored}finally{restored.#mutating=!1}}apply(changes,options={}){return this.protect(()=>{this.requireCertain();const fields=dataOptions(options,["expected","origin","observation"]),input=stableValue({changes,...Object.hasOwn(fields,"expected")?{expected:fields.expected}:{}}),accepted=this.acceptChanges(input.changes);input.expected!==void 0&&this.validateBasis(input.expected);const provenance=this.acceptProvenance(fields);return this.applyPrepared(accepted,input.expected,provenance)})}confirmFixed(value){return this.protect(()=>this.confirmAccepted(this.acceptFixed(value)))}applyFixed(value,provenance={}){return this.protect(()=>{const request=this.acceptFixed(value),receipt=this.confirmAccepted(request);if(receipt!==void 0)return receipt;const acceptedProvenance=this.acceptProvenance(dataOptions(provenance,["origin","observation"]));return this.applyPrepared(request.command.changes,request.expected,acceptedProvenance,request),this.#applies.get(applyKey(request)).receipt})}protect(operation){if(this.#mutating)throw new Error("Memory validation, persistence or publication cannot reenter mutation");this.#mutating=!0;try{return operation()}finally{this.#mutating=!1}}requireCertain(){if(this.#uncertain!==void 0)throw this.#uncertain}basis(){return stableValue({memoriesId:this.id,sequence:this.#sequence})}validateBasis(value){if(!isRecord(value)||!hasOnlyKeys(value,["memoriesId","sequence"])||!isUuid(value.memoriesId)||!Number.isSafeInteger(value.sequence)||value.sequence<0)throw new TypeError("Invalid memory application basis")}validateContent(value){if(!isRecord(value)||!hasOnlyKeys(value,["content"],["metadata"])||!isNonBlankString(value.content))throw new TypeError("Memory content requires a nonblank summary");const result=this.#check?.(value);if(result!==null&&(typeof result=="object"||typeof result=="function")&&typeof result.then=="function")throw Promise.resolve(result).catch(()=>{}),new TypeError("Memory content check must complete synchronously")}acceptChanges(value){if(!Array.isArray(value))throw new TypeError("Memory mutations must be an array");const targets=new Set;for(const mutation of value){if(!isRecord(mutation)||mutation.action!=="create"&&mutation.action!=="update"||!hasOnlyKeys(mutation,mutation.action==="create"?["action","value"]:["action","memoryId","value"],["reason"])||mutation.reason!==void 0&&typeof mutation.reason!="string")throw new TypeError("Invalid memory mutation");if(mutation.action==="update"){if(!isUuid(mutation.memoryId))throw new TypeError("Memory update requires a UUID");if(targets.has(mutation.memoryId))throw new TypeError("A batch cannot update the same memory twice");targets.add(mutation.memoryId)}this.validateContent(mutation.value)}return value}acceptFixed(value){const request=stableValue(value);if(!isRecord(request)||!hasOnlyKeys(request,["contract","contentContract","operation","memoriesId","command"],["expected"])||!isRecord(request.contract)||!hasOnlyKeys(request.contract,["key","version"])||request.contract.key!=="memories.apply"||request.contract.version!==2||request.memoriesId!==this.id||!isRecord(request.operation)||!hasOnlyKeys(request.operation,["contextId"])||!isNonBlankString(request.operation.contextId)||!isRecord(request.command)||!hasOnlyKeys(request.command,["position","changes"])||!isNonBlankString(request.command.position))throw new TypeError("Invalid current fixed memory apply request");if(validateContract(request.contentContract),!equalStable(request.contentContract,this.contentContract))throw new TypeError("Memory content contract does not match fixed apply");return this.acceptChanges(request.command.changes),request.expected!==void 0&&this.validateBasis(request.expected),request}confirmAccepted(request){const saved=this.#applies.get(applyKey(request));if(saved!==void 0&&!equalStable(saved.request,request))throw new RuntimeError("MEMORY_APPLY_CONFLICT","Fixed memory apply differs from its original request");if(saved!==void 0)return saved.receipt;this.requireCertain()}acceptProvenance(fields){const origin=stableValue(fields.origin);if(origin!==void 0&&(!isRecord(origin)||!hasOnlyKeys(origin,["contextId"])||!isNonBlankString(origin.contextId)))throw new TypeError("Invalid memory change origin");return{origin,observation:fields.observation}}applyPrepared(changes,expected,provenance,request){this.requireCertain();const before=this.basis();if(expected!==void 0&&(expected.memoriesId!==this.id||expected.sequence!==this.#sequence))throw new RuntimeError("MEMORY_BASIS_CONFLICT","Memory application basis does not match the current collection");for(const mutation of changes)if(mutation.action==="update"&&!this.#items.has(mutation.memoryId))throw new RangeError("Memory update target does not exist");const changed=[],events=[],correspondence=[],newIds=new Set;for(const[commandIndex,mutation]of changes.entries()){const previous=mutation.action==="update"?this.#items.get(mutation.memoryId):void 0;if(previous!==void 0&&equalStable(previous.value,mutation.value))continue;const sequence2=this.#sequence+changed.length+1;if(!Number.isSafeInteger(sequence2))throw new RangeError("Memory sequence is exhausted");const id=previous?.id??randomUUID();if(previous===void 0&&(this.#items.has(id)||newIds.has(id)))throw new Error("Memory identity collision");previous===void 0&&newIds.add(id);const item=stableValue({id,value:mutation.value}),event=stableValue({type:"memory",memoriesId:this.id,sequence:sequence2,occurredAt:new Date().toISOString(),...provenance.origin!==void 0?{origin:provenance.origin}:{},change:{action:mutation.action,memoryId:id,value:mutation.value,...Object.hasOwn(mutation,"reason")?{reason:mutation.reason}:{}}});changed.push(item),events.push(event),correspondence.push({commandIndex,memoryId:id})}const sequence=this.#sequence+changed.length,result=stableValue({before,after:{memoriesId:this.id,sequence},changed});if(changed.length===0&&request===void 0)return result;const fixed=request===void 0?void 0:stableValue({request,receipt:{memoriesId:this.id,startSequence:this.#sequence,sequence,changes:correspondence}}),commit=stableValue({memoriesId:this.id,contentContract:this.contentContract,expectedSequence:this.#sequence,sequence,upserts:changed,...fixed!==void 0?{fixed}:{}});this.commit(commit);for(const item of changed)this.#items.set(item.id,item);this.#sequence=sequence,fixed!==void 0&&this.#applies.set(applyKey(fixed.request),fixed);const faults=[];for(const event of events)try{publishFact(event,this.#changes,provenance.observation??this.#observation)}catch(error){faults.push(error)}const fault=combineFaults(faults);if(fault!==void 0)throw fault;return result}commit(change){try{const result=this.#persistence?.commit(change);if(result!==void 0)throw Promise.resolve(result).catch(()=>{}),new TypeError("Memory persistence must complete synchronously and return undefined")}catch(cause){let persistenceFailure=!1;try{persistenceFailure=cause instanceof PersistenceError}catch{}throw this.#uncertain=persistenceFailure?cause:new PersistenceError("memories.commit",cause),this.#uncertain}}acceptReceipt(value,request,previousSequence,births,deadlines,reserved){if(!isRecord(value)||!hasOnlyKeys(value,["memoriesId","startSequence","sequence","changes"])||value.memoriesId!==this.id||!Number.isSafeInteger(value.startSequence)||value.startSequence<previousSequence||!Number.isSafeInteger(value.sequence)||value.sequence<value.startSequence||value.sequence>this.#sequence||!Array.isArray(value.changes)||value.changes.length!==value.sequence-value.startSequence)throw new TypeError("Invalid persisted memory apply receipt");const start=value.startSequence;if(request.expected!==void 0&&(request.expected.memoriesId!==this.id||request.expected.sequence!==start))throw new TypeError("Persisted fixed apply has an impossible basis");const seen=new Set,commands=new Set;let previousIndex=-1;for(const[index,entry]of value.changes.entries()){if(!isRecord(entry)||!hasOnlyKeys(entry,["commandIndex","memoryId"])||!Number.isSafeInteger(entry.commandIndex)||entry.commandIndex<=previousIndex||entry.commandIndex>=request.command.changes.length||!isUuid(entry.memoryId)||seen.has(entry.memoryId)||!this.#items.has(entry.memoryId))throw new TypeError("Invalid persisted memory apply correspondence");const commandIndex=entry.commandIndex,mutation=request.command.changes[commandIndex];if(mutation.action==="update"&&mutation.memoryId!==entry.memoryId)throw new TypeError("Persisted update receipt identifies another memory");const sequence=start+index+1;if(mutation.action==="create"){if(births.has(entry.memoryId))throw new TypeError("A memory cannot be created by multiple fixed applies");births.set(entry.memoryId,sequence)}reserved.add(sequence),seen.add(entry.memoryId),commands.add(commandIndex),previousIndex=commandIndex}for(const[index,mutation]of request.command.changes.entries())if(mutation.action==="create"){if(!commands.has(index))throw new TypeError("Persisted create has no corresponding memory")}else{if(!this.#items.has(mutation.memoryId))throw new TypeError("Persisted update target does not exist");deadlines.set(mutation.memoryId,Math.min(deadlines.get(mutation.memoryId)??start,start))}return value}validateTimeline(births,deadlines,reserved){let previousBirth=0;for(const id of this.#items.keys()){const known=births.get(id);let birth=known??previousBirth+1;if(known===void 0)for(;reserved.has(birth);birth++);if(birth<=previousBirth||birth>this.#sequence||previousBirth===0&&birth!==1||birth>(deadlines.get(id)??this.#sequence))throw new TypeError("Persisted memory apply history is impossible");previousBirth=birth}}}function validateContract(value){if(!isRecord(value)||!hasOnlyKeys(value,["key","version"])||!isNonBlankString(value.key)||!Number.isSafeInteger(value.version)||value.version<1)throw new TypeError("Invalid memory content contract")}__name(validateContract,"validateContract");function dataOptions(value,allowed){if(!isRecord(value)||Object.getPrototypeOf(value)!==Object.prototype&&Object.getPrototypeOf(value)!==null)throw new TypeError("Memory options require an ordinary data record");const fields=Object.create(null);for(const key of Reflect.ownKeys(value)){const descriptor=Object.getOwnPropertyDescriptor(value,key);if(typeof key!="string"||!allowed.includes(key)||descriptor===void 0||!descriptor.enumerable||!Object.hasOwn(descriptor,"value"))throw new TypeError("Invalid memory options");fields[key]=descriptor.value}return fields}__name(dataOptions,"dataOptions");function applyKey(request){return JSON.stringify([request.operation.contextId,request.command.position])}__name(applyKey,"applyKey");export{Memories};

package/dist/memory.d.ts

@@ -1,23 +1,32 @@
-import type { MemoryContent } from '@weiliang0121/capix-protocol';
-import type { Transcript } from '@weiliang0121/capix-transcript';
-import type { MemoryState } from './persistence.js';
-export declare class Memory {
-    readonly transcript: Transcript;
-    constructor(transcript: Transcript, content: MemoryContent);
-    get id(): string;
-    get topic(): string;
-    get content(): string;
-    get sourceIndexes(): readonly number[];
-    get sourceResults(): readonly import("@weiliang0121/capix-protocol").MemoryResultSource[] | undefined;
-    snapshot(): MemoryContent;
-    toJSON(): {
-        topic: string;
-        content: string;
-        sourceIndexes: readonly number[];
-        sourceResults?: readonly import("@weiliang0121/capix-protocol").MemoryResultSource[];
-        id: string;
-    };
-    static prepare(transcript: Transcript, content: MemoryContent): MemoryContent;
+import type { Stable } from '@weiliang0121/capix-contracts';
+export interface MemoryContent<Metadata = never> {
+    readonly content: string;
+    readonly metadata?: Metadata;
+}
+export interface MemoryItem<Metadata = never> {
+    readonly id: string;
+    readonly value: MemoryContent<Metadata>;
+}
+export interface MemoryBasis {
+    readonly memoriesId: string;
+    readonly sequence: number;
+}
+export type MemoryRead<Metadata = never> = Stable<MemoryItem<Metadata> & {
+    readonly basis: MemoryBasis;
+}>;
+export interface MemorySnapshot<Metadata = never> {
+    readonly basis: MemoryBasis;
+    readonly items: readonly MemoryItem<Metadata>[];
+}
+export interface MemoryApplication<Metadata = never> {
+    readonly before: MemoryBasis;
+    readonly after: MemoryBasis;
+    readonly changed: readonly MemoryItem<Metadata>[];
+}
+export interface MemoryContentContractIdentity {
+    readonly key: string;
+    readonly version: number;
+}
+export interface MemoryContentContract<Metadata = never> extends MemoryContentContractIdentity {
+    readonly check?: (value: Stable<MemoryContent<Metadata>>) => void;
 }
-export declare function updateMemory(memory: Memory, content: MemoryContent): void;
-export declare function restoreMemory(transcript: Transcript, state: MemoryState): Memory;

package/dist/memory.js

@@ -1,2 +1 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{randomUUID}from"node:crypto";import{isNonBlankString,isNonEmptyArray,hasUniqueItems,isObject}from"./validation.js";import{prepareMemoryResultSources}from"./source.js";const contents=new WeakMap;class Memory{static{__name(this,"Memory")}transcript;constructor(transcript,content){this.transcript=transcript,contents.set(this,{id:randomUUID(),content:Memory.prepare(transcript,content)}),Object.freeze(this)}get id(){return contents.get(this).id}get topic(){return contents.get(this).content.topic}get content(){return contents.get(this).content.content}get sourceIndexes(){return contents.get(this).content.sourceIndexes}get sourceResults(){return contents.get(this).content.sourceResults}snapshot(){return contents.get(this).content}toJSON(){return{id:this.id,...contents.get(this).content}}static prepare(transcript,content){if(!isObject(content))throw new TypeError("Memory requires topic, content and unique source indexes");const topic=content.topic,text=content.content,evidence=content.sourceIndexes;if(!isNonBlankString(topic)||!isNonBlankString(text)||!isNonEmptyArray(evidence))throw new TypeError("Memory requires topic, content and unique source indexes");const sourceIndexes=Object.freeze([...evidence]);if(!isNonEmptyArray(sourceIndexes)||!hasUniqueItems(sourceIndexes))throw new TypeError("Memory requires topic, content and unique source indexes");for(const index of sourceIndexes)transcript.ref(index);const sourceResults=prepareMemoryResultSources(transcript,content.sourceResults);return Object.freeze({topic,content:text,sourceIndexes,...sourceResults?{sourceResults}:{}})}}function updateMemory(memory,content){contents.get(memory).content=content}__name(updateMemory,"updateMemory");function restoreMemory(transcript,state){if(!isObject(state)||!isNonBlankString(state.id))throw new TypeError("Invalid persisted memory identity");const memory=new Memory(transcript,state);return contents.set(memory,{id:state.id,content:memory.snapshot()}),memory}__name(restoreMemory,"restoreMemory");export{Memory,restoreMemory,updateMemory};

package/dist/persistence.d.ts

@@ -1,23 +1,22 @@
-import type { MemoryContent } from '@weiliang0121/capix-protocol';
+import type { Stable } from '@weiliang0121/capix-contracts';
 import type { MemoryApplyState } from './apply.js';
-export interface MemoryState extends MemoryContent {
+import type { MemoryContentContractIdentity, MemoryItem } from './memory.js';
+export interface MemoriesState<Metadata = never> {
+    readonly version: 2;
     readonly id: string;
-}
-export interface MemoriesState {
-    readonly id: string;
-    readonly transcriptId: string;
+    readonly contentContract: MemoryContentContractIdentity;
     readonly sequence: number;
-    readonly items: readonly MemoryState[];
-    readonly applies?: readonly MemoryApplyState[];
+    readonly items: readonly MemoryItem<Metadata>[];
+    readonly applies?: readonly MemoryApplyState<Metadata>[];
 }
-export interface MemoriesCommit {
+export interface MemoriesCommit<Metadata = never> {
     readonly memoriesId: string;
-    readonly transcriptId: string;
+    readonly contentContract: MemoryContentContractIdentity;
     readonly expectedSequence: number;
     readonly sequence: number;
-    readonly upserts: readonly MemoryState[];
-    readonly fixed?: MemoryApplyState;
+    readonly upserts: readonly MemoryItem<Metadata>[];
+    readonly fixed?: MemoryApplyState<Metadata>;
 }
-export interface MemoriesPersistence {
-    commit(change: MemoriesCommit): undefined;
+export interface MemoriesPersistence<Metadata = never> {
+    commit(change: Stable<MemoriesCommit<Metadata>>): undefined;
 }

package/dist/resource.d.ts

@@ -1,36 +1,59 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
 import { ResourceOffer } from '@weiliang0121/capix-resources';
 import type { Memories } from './memories.js';
-import type { MemoryChange } from './change.js';
-import type { MemoryState } from './persistence.js';
-type MemorySnapshot = ReturnType<Memories['snapshot']>;
-export interface CapturedMemories {
-    readonly memoriesId: string;
-    readonly sequence: number;
-    readonly items: Readonly<MemorySnapshot>;
-}
-export interface MemoryBasis {
-    readonly memoriesId: string;
-    readonly transcriptId: string;
-    readonly sequence: number;
-}
-export interface MemoryApplication extends MemoryBasis {
-    readonly startSequence: number;
-    readonly items: readonly Readonly<MemoryState>[];
-}
-export declare const MemoryResource: Readonly<{
-    snapshot: ResourceOffer<Memories | CapturedMemories, readonly {
-        topic: string;
-        content: string;
-        sourceIndexes: readonly number[];
-        sourceResults?: readonly import("@weiliang0121/capix-protocol").MemoryResultSource[];
-        id: string;
-    }[], CapturedMemories, never>;
-    apply: ResourceOffer<Memories, Readonly<{
-        apply(changes: readonly MemoryChange[], expected?: MemoryBasis): MemoryApplication;
+import type { MemoryMutation } from './change.js';
+import type { MemoryBasis } from './memory.js';
+export declare function memoryResources<Metadata = never>(): Readonly<{
+    read: ResourceOffer<Memories<Metadata>, Readonly<{
+        read(id: string): {
+            readonly id: string;
+            readonly value: {
+                readonly content: string;
+                readonly metadata?: Stable<Metadata> | undefined;
+            };
+            readonly basis: {
+                readonly memoriesId: string;
+                readonly sequence: number;
+            };
+        } | undefined;
+        snapshot(): {
+            readonly basis: {
+                readonly memoriesId: string;
+                readonly sequence: number;
+            };
+            readonly items: import("@weiliang0121/capix-contracts").StableArray<{
+                readonly id: string;
+                readonly value: {
+                    readonly content: string;
+                    readonly metadata?: Stable<Metadata> | undefined;
+                };
+            }>;
+        };
+    }>, Memories<Metadata>, never>;
+    apply: ResourceOffer<Memories<Metadata>, Readonly<{
+        apply(changes: readonly MemoryMutation<Metadata>[] | Stable<readonly MemoryMutation<Metadata>[]>, expected?: MemoryBasis): {
+            readonly before: {
+                readonly memoriesId: string;
+                readonly sequence: number;
+            };
+            readonly after: {
+                readonly memoriesId: string;
+                readonly sequence: number;
+            };
+            readonly changed: import("@weiliang0121/capix-contracts").StableArray<{
+                readonly id: string;
+                readonly value: {
+                    readonly content: string;
+                    readonly metadata?: Stable<Metadata> | undefined;
+                };
+            }>;
+        };
         applyFixed(input: {
             readonly position: string;
-            readonly changes: readonly MemoryChange[];
-        }, expected?: MemoryBasis): import("./apply.js").MemoryApplyReceipt;
-    }>, Memories, never>;
+            readonly changes: readonly MemoryMutation<Metadata>[];
+        } | Stable<{
+            readonly position: string;
+            readonly changes: readonly MemoryMutation<Metadata>[];
+        }>, expected?: MemoryBasis): unknown;
+    }>, Memories<Metadata>, never>;
 }>;
-export {};

package/dist/resource.js

@@ -1,2 +1,2 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{ResourceOffer}from"@weiliang0121/capix-resources";import{RuntimeError}from"@weiliang0121/capix-contracts";import{isNonBlankString,isObject}from"./validation.js";function checkBasis(memories,expected,sequence){if(!isObject(expected))throw new TypeError("Invalid memory application basis");if(!isNonBlankString(expected.memoriesId)||!isNonBlankString(expected.transcriptId)||!Number.isSafeInteger(expected.sequence)||expected.sequence<0)throw new TypeError("Invalid memory application basis");if(expected.memoriesId!==memories.id||expected.transcriptId!==memories.transcript.id||expected.sequence!==sequence)throw new RuntimeError("MEMORY_BASIS_CONFLICT","Memory application basis does not match the fixed collection version")}__name(checkBasis,"checkBasis");const MemoryResource=Object.freeze({snapshot:new ResourceOffer({name:"memories.snapshot",expose:__name(captured=>captured.items,"expose"),timing:"binding",capture:__name(memories=>"items"in memories?memories:{memoriesId:memories.id,sequence:memories.sequence,items:Object.freeze(memories.snapshot().map(memory=>Object.freeze(memory)))},"capture"),describe:__name(captured=>({memoriesId:captured.memoriesId,sequence:captured.sequence,memoryIds:captured.items.map(memory=>memory.id)}),"describe")}),apply:new ResourceOffer({name:"memories.apply",expose:__name((memories,activity)=>Object.freeze({apply(changes,expected){return activity.runSync("apply",{input:__name(()=>({count:changes.length}),"input"),output:__name(result=>({memoriesId:result.memoriesId,startSequence:result.startSequence,endSequence:result.sequence,memoryIds:result.items.map(memory=>memory.id)}),"output")},()=>{expected!==void 0&&checkBasis(memories,expected,memories.sequence);const startSequence=memories.sequence,applied=memories.apply(changes,{origin:activity.origin,observation:activity.memoryObservation});return Object.freeze({memoriesId:memories.id,transcriptId:memories.transcript.id,startSequence,sequence:memories.sequence,items:Object.freeze(applied.map(memory=>Object.freeze(memory.toJSON())))})})},applyFixed(input,expected){return activity.runSync("applyFixed",{input:__name(()=>({position:input.position,count:input.changes.length}),"input"),output:__name(receipt=>receipt,"output")},()=>{if(!activity.origin)throw new Error("Fixed memory application requires a calling identity");const request={contract:{key:"memories.apply",version:1},operation:{contextId:activity.origin.contextId,position:input.position},memoriesId:memories.id,changes:input.changes},confirmed=memories.confirmFixed(request);return expected!==void 0&&checkBasis(memories,expected,confirmed?.startSequence??memories.sequence),confirmed??memories.applyFixed(request,{origin:activity.origin,observation:activity.memoryObservation})})}}),"expose"),timing:"access",describe:__name(memories=>({memoriesId:memories.id}),"describe")})});export{MemoryResource};
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{MemoryFacts}from"./event.js";import"@weiliang0121/capix-contracts";import{ResourceOffer}from"@weiliang0121/capix-resources";function memoryResources(){return Object.freeze({read:new ResourceOffer({name:"memories.read",expose:__name((memories,activity)=>Object.freeze({read(id){return activity.runSync("read",{input:__name(()=>({memoryId:id}),"input"),output:__name(result=>({memoriesId:memories.id,memoryId:id,found:result!==void 0}),"output")},()=>memories.read(id))},snapshot(){return activity.runSync("snapshot",{output:__name(result=>({memoriesId:result.basis.memoriesId,sequence:result.basis.sequence,count:result.items.length}),"output")},()=>memories.snapshot())}}),"expose"),timing:"access",describe:__name(memories=>({memoriesId:memories.id}),"describe")}),apply:new ResourceOffer({name:"memories.apply",expose:__name((memories,activity)=>Object.freeze({apply(changes,expected){return activity.runSync("apply",{output:__name(result=>({memoriesId:result.after.memoriesId,startSequence:result.before.sequence,endSequence:result.after.sequence,memoryIds:result.changed.map(item=>item.id)}),"output")},operation=>memories.apply(changes,{expected,origin:operation.origin,observation:operation.facts(MemoryFacts)}))},applyFixed(input,expected){return activity.runSync("applyFixed",{output:__name(receipt=>receipt,"output")},operation=>{if(!activity.origin)throw new Error("Fixed memory application requires a calling identity");const request={contract:{key:"memories.apply",version:2},contentContract:memories.contentContract,operation:{contextId:activity.origin.contextId},memoriesId:memories.id,command:input,...expected===void 0?{}:{expected}};return memories.applyFixed(request,{origin:operation.origin,observation:operation.facts(MemoryFacts)})})}}),"expose"),timing:"access",describe:__name(memories=>({memoriesId:memories.id}),"describe")})})}__name(memoryResources,"memoryResources");export{memoryResources};

package/dist/validation.d.ts

@@ -1,4 +1,5 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function isNonBlankString(value: unknown): value is string;
-export declare function isNonEmptyArray(value: unknown): value is [unknown, ...unknown[]];
-export declare function hasUniqueItems(values: readonly unknown[]): boolean;
-export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isUuid(value: unknown): value is string;
+export declare function hasOnlyKeys(value: Record<string, unknown>, required: readonly string[], optional?: readonly string[]): boolean;
+export declare function equalStable(left: unknown, right: unknown): boolean;

package/dist/validation.js

@@ -1,2 +1,2 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isString}from"es-toolkit/predicate";import{isArray}from"es-toolkit/compat";function isNonBlankString(value){return isString(value)&&/\S/.test(value)}__name(isNonBlankString,"isNonBlankString");function isNonEmptyArray(value){return isArray(value)&&value.length>0}__name(isNonEmptyArray,"isNonEmptyArray");function hasUniqueItems(values){return new Set(values).size===values.length}__name(hasUniqueItems,"hasUniqueItems");function isObject(value){return typeof value=="object"&&value!==null&&!isArray(value)}__name(isObject,"isObject");export{hasUniqueItems,isNonBlankString,isNonEmptyArray,isObject};
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}__name(isRecord,"isRecord");function isNonBlankString(value){return typeof value=="string"&&/\S/u.test(value)}__name(isNonBlankString,"isNonBlankString");function isUuid(value){return typeof value=="string"&&/^[\da-f]{8}-[\da-f]{4}-[1-8][\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/iu.test(value)}__name(isUuid,"isUuid");function hasOnlyKeys(value,required,optional=[]){return required.every(key=>Object.hasOwn(value,key))&&Object.keys(value).every(key=>required.includes(key)||optional.includes(key))}__name(hasOnlyKeys,"hasOnlyKeys");function equalStable(left,right){if(Object.is(left,right))return!0;if(left===null||right===null||typeof left!="object"||typeof right!="object"||Object.getPrototypeOf(left)!==Object.getPrototypeOf(right))return!1;if(Array.isArray(left))return!Array.isArray(right)||left.length!==right.length?!1:left.every((value,index)=>equalStable(value,right[index]));const keys=Object.keys(left);return keys.length!==Object.keys(right).length?!1:keys.every(key=>Object.hasOwn(right,key)&&equalStable(left[key],right[key]))}__name(equalStable,"equalStable");export{equalStable,hasOnlyKeys,isNonBlankString,isRecord,isUuid};

package/dist/view.d.ts

@@ -1,23 +1,22 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
 import type { SyncViewSource } from '@weiliang0121/capix-view';
 import type { Memories } from './memories.js';
-import type { MemoryState } from './persistence.js';
-export interface MemoryViewSummary {
-    readonly topic: string;
-}
-type MemoryViewContract = SyncViewSource<string, MemoryViewSummary, MemoryState>;
-type SourceStamp = Parameters<MemoryViewContract['read']>[1];
-export declare class MemoryViewSource implements MemoryViewContract {
+import type { MemoryItem } from './memory.js';
+type MemoryViewContract<Metadata> = SyncViewSource<string, undefined, Stable<MemoryItem<Metadata>>>;
+type SourceStamp = Parameters<MemoryViewContract<never>['read']>[1];
+export declare class MemoryViewSource<Metadata = never> implements MemoryViewContract<Metadata> {
     #private;
     readonly id: string;
     readonly scope: string;
-    constructor(memories: Memories, keys?: readonly string[]);
-    index(): ReturnType<MemoryViewContract['index']>;
-    inspect(keys: readonly string[]): ReturnType<MemoryViewContract['inspect']>;
-    read(keys: readonly string[], expected: SourceStamp): ReturnType<MemoryViewContract['read']>;
+    constructor(memories: Memories<Metadata>, keys?: readonly string[]);
+    index(): ReturnType<MemoryViewContract<Metadata>['index']>;
+    inspect(keys: readonly string[]): ReturnType<MemoryViewContract<Metadata>['inspect']>;
+    read(keys: readonly string[], expected: SourceStamp): ReturnType<MemoryViewContract<Metadata>['read']>;
     check(expected: SourceStamp): boolean;
     private stamp;
     private requireCurrent;
     private acceptKeys;
+    private summary;
     private requireMemory;
 }
 export {};

package/dist/view.js

@@ -1,2 +1,2 @@
 /*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{RuntimeError}from"@weiliang0121/capix-contracts";class MemoryViewSource{static{__name(this,"MemoryViewSource")}id;scope;#memories;#keys;#allowed;constructor(memories,keys){if(this.#memories=memories,this.id=memories.id,keys!==void 0){this.#keys=this.acceptKeys(keys);for(const key of this.#keys)this.requireMemory(key);this.#allowed=new Set(this.#keys)}this.scope=this.#keys===void 0?"whole":`keys:${JSON.stringify(this.#keys)}`,Object.freeze(this)}index(){const stamp=this.stamp(),keys=this.#keys??this.#memories.values().map(memory=>memory.id),entries=Object.freeze(keys.map(key=>Object.freeze({key,summary:Object.freeze({topic:this.requireMemory(key).topic})})));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}inspect(keys){const stamp=this.stamp(),selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Memory is outside the view source scope");return Object.freeze({key,summary:Object.freeze({topic:this.requireMemory(key).topic})})}));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}read(keys,expected){const basis=Object.freeze({id:expected.id,scope:expected.scope,version:expected.version});this.requireCurrent(basis);const selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Memory is outside the view source scope");return Object.freeze({key,value:Object.freeze(this.requireMemory(key).toJSON())})}));return this.requireCurrent(basis),Object.freeze({stamp:this.stamp(),entries})}check(expected){return expected?.id===this.id&&expected.scope===this.scope&&expected.version===String(this.#memories.sequence)}stamp(){return Object.freeze({id:this.id,scope:this.scope,version:String(this.#memories.sequence)})}requireCurrent(expected){if(!this.check(expected))throw new RuntimeError("VIEW_SOURCE_CONFLICT","Memory view source has changed")}acceptKeys(keys){if(!Array.isArray(keys))throw new TypeError("Memory view keys must be an array");const accepted=Array.from(keys);if(accepted.some(key=>typeof key!="string"||!key)||new Set(accepted).size!==accepted.length)throw new TypeError("Memory view requires unique nonempty string keys");return Object.freeze(accepted)}requireMemory(key){const memory=this.#memories.get(key);if(!memory)throw new RangeError("Memory view member does not exist");return memory}}export{MemoryViewSource};
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{RuntimeError}from"@weiliang0121/capix-contracts";class MemoryViewSource{static{__name(this,"MemoryViewSource")}id;scope;#memories;#keys;#allowed;constructor(memories,keys){if(this.#memories=memories,this.id=memories.id,keys!==void 0){this.#keys=this.acceptKeys(keys);for(const key of this.#keys)this.requireMemory(key);this.#allowed=new Set(this.#keys)}this.scope=this.#keys===void 0?"whole":`keys:${JSON.stringify(this.#keys)}`,Object.freeze(this)}index(){const stamp=this.stamp(),keys=this.#keys??this.#memories.values().map(memory=>memory.id),entries=Object.freeze(keys.map(key=>Object.freeze({key,summary:this.summary(key)})));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}inspect(keys){const stamp=this.stamp(),selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Memory is outside the view source scope");return Object.freeze({key,summary:this.summary(key)})}));return this.requireCurrent(stamp),Object.freeze({stamp,entries})}read(keys,expected){const basis=Object.freeze({id:expected.id,scope:expected.scope,version:expected.version});this.requireCurrent(basis);const selected=this.acceptKeys(keys),entries=Object.freeze(selected.map(key=>{if(this.#allowed&&!this.#allowed.has(key))throw new RangeError("Memory is outside the view source scope");return Object.freeze({key,value:this.requireMemory(key)})}));return this.requireCurrent(basis),Object.freeze({stamp:this.stamp(),entries})}check(expected){return expected?.id===this.id&&expected.scope===this.scope&&expected.version===String(this.#memories.sequence)}stamp(){return Object.freeze({id:this.id,scope:this.scope,version:String(this.#memories.sequence)})}requireCurrent(expected){if(!this.check(expected))throw new RuntimeError("VIEW_SOURCE_CONFLICT","Memory view source has changed")}acceptKeys(keys){if(!Array.isArray(keys))throw new TypeError("Memory view keys must be an array");const accepted=Array.from(keys);if(accepted.some(key=>typeof key!="string"||!key)||new Set(accepted).size!==accepted.length)throw new TypeError("Memory view requires unique nonempty string keys");return Object.freeze(accepted)}summary(key){this.requireMemory(key)}requireMemory(key){const memory=this.#memories.read(key);if(!memory)throw new RangeError("Memory view member does not exist");return Object.freeze({id:memory.id,value:memory.value})}}export{MemoryViewSource};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weiliang0121/capix-memory",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -10,14 +10,11 @@
     }
   },
   "dependencies": {
-    "es-toolkit": "1.52.0",
-    "@weiliang0121/capix-transcript": "0.1.0",
-    "@weiliang0121/capix-changes": "0.1.0",
-    "@weiliang0121/capix-resources": "0.1.0",
-    "@weiliang0121/capix-view": "0.1.0",
-    "@weiliang0121/capix-protocol": "0.1.0",
-    "@weiliang0121/capix-contracts": "0.1.0",
-    "@weiliang0121/capix-diagnostics": "0.1.0"
+    "@weiliang0121/capix-contracts": "0.2.0",
+    "@weiliang0121/capix-diagnostics": "0.2.0",
+    "@weiliang0121/capix-changes": "0.2.0",
+    "@weiliang0121/capix-resources": "0.2.0",
+    "@weiliang0121/capix-view": "0.2.0"
   },
   "description": "Versioned memory entities and controlled resource access for CAPiX.",
   "license": "MIT",
@@ -25,7 +22,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/weiliang0121/capix.git",
-    "directory": "server/memory"
+    "directory": "packages/memory"
   },
   "engines": {
     "node": ">=22.23.2"
@@ -44,6 +41,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/test/run.mjs --package ."
   }
 }

package/dist/source.d.ts

@@ -1,3 +0,0 @@
-import type { MemoryResultSource } from '@weiliang0121/capix-protocol';
-import type { Transcript } from '@weiliang0121/capix-transcript';
-export declare function prepareMemoryResultSources(transcript: Transcript, sources: readonly MemoryResultSource[] | undefined): readonly MemoryResultSource[] | undefined;

package/dist/source.js

@@ -1,2 +0,0 @@
-/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
-var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isPlainObject}from"es-toolkit/predicate";import{isArray}from"es-toolkit/compat";import{isNonBlankString}from"./validation.js";function prepareMemoryResultSources(transcript,sources){if(sources===void 0)return;if(!isArray(sources))throw new TypeError("Memory result sources must be an array");const ids=new Set,prepared=Array.from(sources,source=>{if(!isPlainObject(source))throw new TypeError("Memory result source requires a known kind and unique identity");const id=source.id,kind=source.kind,answerIndex=source.answerIndex;if(kind!=="file-created"||!isNonBlankString(id)||ids.has(id))throw new TypeError("Memory result source requires a known kind and unique identity");if(ids.add(id),transcript.ref(answerIndex).read().role!=="assistant")throw new TypeError("Memory result source must locate an assistant answer");const receipt=source.receipt;if(!isPlainObject(receipt))throw new TypeError("Memory result source requires a valid file creation receipt");const path=receipt.path,bytes=receipt.bytes,digest=receipt.digest;if(!isNonBlankString(path)||!Number.isSafeInteger(bytes)||bytes<0||typeof digest!="string"||!/^[a-f0-9]{64}$/u.test(digest))throw new TypeError("Memory result source requires a valid file creation receipt");return Object.freeze({id,kind,answerIndex,receipt:Object.freeze({path,bytes,digest})})});return prepared.length?Object.freeze(prepared):void 0}__name(prepareMemoryResultSources,"prepareMemoryResultSources");export{prepareMemoryResultSources};