@weiliang0121/capix-memory 0.0.0-stage → 0.1.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,19 @@
-# 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.
+Versioned memory entities and controlled resource access for CAPiX.
+
+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.
+
+## License
+
+MIT. Copyright (c) 2026 wei.liang. See [LICENSE](./LICENSE).

package/dist/apply.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryChange } from './change.js';
+export interface MemoryFixedApply {
+    readonly contract: {
+        readonly key: 'memories.apply';
+        readonly version: 1;
+    };
+    readonly operation: {
+        readonly contextId: string;
+        readonly position: string;
+    };
+    readonly memoriesId: string;
+    readonly changes: readonly MemoryChange[];
+}
+export interface MemoryApplyReceipt {
+    readonly memoriesId: string;
+    readonly startSequence: number;
+    readonly sequence: number;
+    readonly memoryIds: readonly string[];
+}
+export interface MemoryApplyState {
+    readonly request: MemoryFixedApply;
+    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,15 @@
+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;
+} & ({
+    readonly action: 'create';
+    readonly memoryId: null;
+} | {
+    readonly action: 'update';
+    readonly memoryId: string;
+});
+export declare function prepareMemoryChanges(transcript: Transcript, changes: readonly MemoryChange[]): readonly MemoryChange[];

package/dist/change.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{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/index.d.ts

@@ -0,0 +1,7 @@
+export { Memory } from './memory.js';
+export { Memories, type MemoriesOptions } from './memories.js';
+export type { MemoryChange } 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';

package/dist/index.js

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

package/dist/memories.d.ts

@@ -0,0 +1,40 @@
+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 { MemoriesPersistence, MemoriesState } from './persistence.js';
+import type { MemoryFixedApply, MemoryApplyReceipt } from './apply.js';
+export interface MemoriesOptions {
+    observation?: EventConsumer<MemoryEvent>;
+    changes?: ChangeCapture<MemoryEvent>;
+    persistence?: MemoriesPersistence;
+}
+export declare class Memories {
+    #private;
+    readonly transcript: Transcript;
+    get id(): string;
+    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;
+    private acceptFixed;
+    private confirmAccepted;
+    private applyPrepared;
+    private commit;
+}

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{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};

package/dist/memory.d.ts

@@ -0,0 +1,23 @@
+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;
+}
+export declare function updateMemory(memory: Memory, content: MemoryContent): void;
+export declare function restoreMemory(transcript: Transcript, state: MemoryState): Memory;

package/dist/memory.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{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

@@ -0,0 +1,23 @@
+import type { MemoryContent } from '@weiliang0121/capix-protocol';
+import type { MemoryApplyState } from './apply.js';
+export interface MemoryState extends MemoryContent {
+    readonly id: string;
+}
+export interface MemoriesState {
+    readonly id: string;
+    readonly transcriptId: string;
+    readonly sequence: number;
+    readonly items: readonly MemoryState[];
+    readonly applies?: readonly MemoryApplyState[];
+}
+export interface MemoriesCommit {
+    readonly memoriesId: string;
+    readonly transcriptId: string;
+    readonly expectedSequence: number;
+    readonly sequence: number;
+    readonly upserts: readonly MemoryState[];
+    readonly fixed?: MemoryApplyState;
+}
+export interface MemoriesPersistence {
+    commit(change: MemoriesCommit): 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,36 @@
+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;
+        applyFixed(input: {
+            readonly position: string;
+            readonly changes: readonly MemoryChange[];
+        }, expected?: MemoryBasis): import("./apply.js").MemoryApplyReceipt;
+    }>, Memories, never>;
+}>;
+export {};

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{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};

package/dist/source.d.ts

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

@@ -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{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};

package/dist/validation.d.ts

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

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});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};

package/dist/view.d.ts

@@ -0,0 +1,23 @@
+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 {
+    #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']>;
+    check(expected: SourceStamp): boolean;
+    private stamp;
+    private requireCurrent;
+    private acceptKeys;
+    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: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};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@weiliang0121/capix-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "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"
+  },
+  "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": "server/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"
+  }
 }