@weiliang0121/capix-memory 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei.liang (https://github.com/weiliang0121)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @weiliang0121/capix-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```sh
+npm install @weiliang0121/capix-memory
+```
+
+## Public entry points
+
+- `@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).

package/dist/apply.d.ts

@@ -0,0 +1,31 @@
+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: 2;
+    };
+    readonly contentContract: MemoryContentContractIdentity;
+    readonly operation: {
+        readonly contextId: string;
+    };
+    readonly memoriesId: string;
+    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 changes: readonly {
+        readonly commandIndex: number;
+        readonly memoryId: string;
+    }[];
+}
+export interface MemoryApplyState<Metadata = never> {
+    readonly request: MemoryFixedApply<Metadata>;
+    readonly receipt: MemoryApplyReceipt;
+}

package/dist/apply.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/change.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryContent } from './memory.js';
+export type MemoryMutation<Metadata = never> = ({
+    readonly action: 'create';
+} | {
+    readonly action: 'update';
+    readonly memoryId: string;
+}) & {
+    readonly value: MemoryContent<Metadata>;
+    readonly reason?: string;
+};

package/dist/change.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

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

@@ -0,0 +1,8 @@
+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 { 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

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+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

@@ -0,0 +1,44 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
+import { type ChangeProvenance, type EventConsumer, type ChangeCapture } from '@weiliang0121/capix-changes';
+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<Metadata = never> {
+    readonly contentContract?: MemoryContentContract<Metadata>;
+    readonly observation?: EventConsumer<MemoryEvent<Metadata>>;
+    readonly changes?: ChangeCapture<MemoryEvent<Metadata>>;
+    readonly persistence?: MemoriesPersistence<Metadata>;
+}
+export interface MemoryApplyOptions<Metadata = never> extends ChangeProvenance<MemoryEvent<Metadata>> {
+    readonly expected?: MemoryBasis;
+}
+export declare class Memories<Metadata = never> {
+    #private;
+    constructor(options?: MemoriesOptions<Metadata>);
+    get id(): string;
+    get contentContract(): Stable<MemoryContentContractIdentity>;
+    get sequence(): number;
+    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

@@ -0,0 +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{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

@@ -0,0 +1,32 @@
+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;
+}

package/dist/memory.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/persistence.d.ts

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

package/dist/persistence.js

@@ -0,0 +1 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */

package/dist/resource.d.ts

@@ -0,0 +1,59 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
+import { ResourceOffer } from '@weiliang0121/capix-resources';
+import type { Memories } from './memories.js';
+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 MemoryMutation<Metadata>[];
+        } | Stable<{
+            readonly position: string;
+            readonly changes: readonly MemoryMutation<Metadata>[];
+        }>, expected?: MemoryBasis): unknown;
+    }>, Memories<Metadata>, never>;
+}>;

package/dist/resource.js

@@ -0,0 +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{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

@@ -0,0 +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 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

@@ -0,0 +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});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

@@ -0,0 +1,22 @@
+import { type Stable } from '@weiliang0121/capix-contracts';
+import type { SyncViewSource } from '@weiliang0121/capix-view';
+import type { Memories } from './memories.js';
+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<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

@@ -0,0 +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: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,47 @@
 {
   "name": "@weiliang0121/capix-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@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",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "packages/memory"
+  },
+  "engines": {
+    "node": ">=22.23.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/test/run.mjs --package ."
+  }
 }