@weiliang0121/capix-records 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,29 @@
-# Temporary Holding Version
+# @weiliang0121/capix-records
 
-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.
+Optional recording entities and resource packages/contracts for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-records
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-records`
+- `@weiliang0121/capix-records/construction`
+- `@weiliang0121/capix-records/data`
+
+The root entry exports live record entities and recording helpers. The `data` entry owns their plain record shapes, archive identities, change records, output resolution, and full subtree/body validation. It has no Node.js or live-entity imports and is suitable for browser and wire consumers. Identically named data interfaces and entity classes are deliberately separated by these entries.
+
+`CallableRecordHelper.snapshot` reads the caller-selected invocation subtree and its actual ancestor path; selecting a business task, Observer overview, and environment aggregation remain application responsibilities. `ExecutionRecordHelper.snapshot` and the corresponding legacy-named validators retain their existing record representation and validation; these APIs do not upgrade old data or resume execution. Memory recording and `observeMemory` expose only `MemoryRecordContent` (`content`) and available records, not arbitrary metadata or recovery material.
+
+This ownership change removes the dependency on `capix-protocol`. Consumers of the former protocol recording/archive exports must import `capix-records/data`; shared invocation vocabulary belongs to `capix-contracts`.
+
+`ResourceRecord.sequence` retains the owning call's shared resource order, which also numbers forwarded domain facts. Because those facts are projected separately or intentionally left uninterpreted, resource record numbers may have gaps. Subtree validation and record-book restoration require positive safe integers in strictly increasing order per owner; identity, binding phases, and started/returned/threw pairing remain checked. Missing numbers do not establish missing effects or authorize replay.
+
+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/attempt/helper.d.ts

@@ -0,0 +1,12 @@
+import type { InvocationFailureFact, RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+import type { Recorder } from '../recorder.js';
+import type { RecordBook } from '../book.js';
+import { AttemptRecord, type AttemptRecordOptions } from './record.js';
+export declare class AttemptRecordHelper {
+    static create(recorder: Recorder, options: AttemptRecordOptions, input: unknown): AttemptRecord;
+    static get(book: RecordBook, id: string): AttemptRecord;
+    static findByOperation(recorder: Recorder, operationId: string): readonly AttemptRecord[];
+    static complete(recorder: Recorder, id: string, output: unknown, resultOf?: number): void;
+    static fail(recorder: Recorder, id: string, error: RuntimeErrorValue, failure?: InvocationFailureFact): void;
+    private static owner;
+}

package/dist/attempt/helper.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{InvocationRecordHelper}from"../invocation/helper.js";import{ExecutionRecord}from"../execution/record.js";import{OperationRecord}from"../operation/record.js";import{AttemptRecord}from"./record.js";class AttemptRecordHelper{static{__name(this,"AttemptRecordHelper")}static create(recorder,options,input){const book=recorder.book,operation=this.owner(book,options.operationId),execution=book.get(operation.executionId);if(!(execution instanceof ExecutionRecord))throw new Error("Execution does not exist");if(execution.status!=="running"||operation.status!=="running")throw new Error("Record has already ended");const record=new AttemptRecord(options,input);return recorder.add(record)}static get(book,id){const record=book.get(id);if(!(record instanceof AttemptRecord))throw new Error("Attempt does not exist");return record}static findByOperation(recorder,operationId){return this.owner(recorder.book,operationId),recorder.tree.children(operationId).filter(record=>record instanceof AttemptRecord)}static complete(recorder,id,output,resultOf){InvocationRecordHelper.finish(recorder,this.get(recorder.book,id),record=>record.complete(output,resultOf))}static fail(recorder,id,error,failure){InvocationRecordHelper.finish(recorder,this.get(recorder.book,id),record=>record.fail(error,failure))}static owner(book,id){const operation=book.get(id);if(!(operation instanceof OperationRecord))throw new Error("Operation does not exist");return operation}}export{AttemptRecordHelper};

package/dist/attempt/record.d.ts

@@ -0,0 +1,15 @@
+import type { AttemptRecord as AttemptData, AttemptValue } from '../data/index.js';
+import { InvocationRecord } from '../invocation/record.js';
+export type AttemptRecordOptions = Omit<AttemptData, 'id' | 'value' | 'status' | 'parentId' | 'childIds'>;
+export declare class AttemptRecord extends InvocationRecord<AttemptValue> implements AttemptData {
+    readonly kind: "attempt";
+    readonly contextId: string;
+    readonly operationId: string;
+    readonly name: string;
+    readonly label: string;
+    readonly source: string;
+    readonly caller: string;
+    readonly callee: string;
+    constructor(options: AttemptRecordOptions, input: unknown);
+    toJSON(): AttemptData;
+}

package/dist/attempt/record.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{pick}from"es-toolkit/object";import{InvocationRecord}from"../invocation/record.js";import{snapshotValue}from"../value/snapshot.js";class AttemptRecord extends InvocationRecord{static{__name(this,"AttemptRecord")}kind="attempt";contextId;operationId;name;label;source;caller;callee;constructor(options,input){super(snapshotValue({input,processes:[],relationChanges:[]}),options.operationId),this.contextId=options.contextId,this.operationId=options.operationId,this.name=options.name,this.label=options.label,this.source=options.source,this.caller=options.caller,this.callee=options.callee,Object.freeze(this)}toJSON(){return{...super.toJSON(),status:this.status,...pick(this,["contextId","operationId","name","label","source","caller","callee"])}}}export{AttemptRecord};

package/dist/book.d.ts

@@ -0,0 +1,15 @@
+import type { BaseRecord } from './record.js';
+import { removeRegistration } from './tree/access.js';
+import type { RecordEntry } from './data/index.js';
+export interface RecordBookState {
+    readonly entries: readonly RecordEntry[];
+}
+export declare class RecordBook {
+    #private;
+    static restore(state: RecordBookState): RecordBook;
+    exportState(): RecordBookState;
+    add<RecordType extends BaseRecord<unknown>>(record: RecordType): RecordType;
+    [removeRegistration](record: BaseRecord<unknown>): void;
+    get(id: string): BaseRecord<unknown> | undefined;
+    values(): IterableIterator<BaseRecord<unknown>>;
+}

package/dist/book.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{removeRegistration}from"./tree/access.js";import{isPlainObject}from"es-toolkit/predicate";import{snapshotValue}from"./value/snapshot.js";import{restoreEntry}from"./restoration/entry.js";import{checkRestoredTree}from"./restoration/tree.js";import{sealHistorical}from"./restoration/access.js";class RecordBook{static{__name(this,"RecordBook")}#records=new Map;static restore(state){if(!isPlainObject(state)||!Array.isArray(state.entries)||Object.keys(state).length!==1)throw new Error("Invalid stored record book");const captured=snapshotValue(state),book=new RecordBook;for(const entry of captured.entries)book.add(restoreEntry(entry));checkRestoredTree(book);for(const record of book.values())record[sealHistorical]();return book}exportState(){return snapshotValue({entries:[...this.#records.values()].map(record=>({kind:record.kind,data:record.toJSON()}))})}add(record){if(this.#records.has(record.id))throw new Error("Record ID already exists");return this.#records.set(record.id,record),record}[removeRegistration](record){this.#records.get(record.id)===record&&this.#records.delete(record.id)}get(id){return this.#records.get(id)}values(){return this.#records.values()}}export{RecordBook};

package/dist/callable/helper.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutionRecordSnapshot } from '../data/index.js';
+import type { Recorder } from '../recorder.js';
+export declare class CallableRecordHelper {
+    static snapshot(recorder: Recorder, id: string): ExecutionRecordSnapshot;
+}

package/dist/callable/helper.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{InvocationBoundaryRecord}from"../invocation/boundary/record.js";import{MemoryRecord}from"../memory/record.js";import{ResourceRecord}from"../resource/record.js";import{TranscriptRecord}from"../transcript/record.js";import{CallableRecord}from"./record.js";class CallableRecordHelper{static{__name(this,"CallableRecordHelper")}static snapshot(recorder,id){const selected=recorder.book.get(id);if(!(selected instanceof CallableRecord))throw new Error("Callable record does not exist");const records=[selected,...recorder.tree.descendants(id)];let root=selected;const ancestry=[],visited=new Set([selected.id]);let parent=root.parentId?recorder.book.get(root.parentId):void 0;for(;parent instanceof CallableRecord;){if(visited.has(parent.id)||!parent.childIds.includes(root.id))throw new Error("Inconsistent callable record ancestry");visited.add(parent.id),ancestry.unshift(parent),root=parent,parent=root.parentId?recorder.book.get(root.parentId):void 0}const ancestorDetails=ancestry.flatMap(ancestor=>recorder.tree.children(ancestor.id)),boundaries=[...ancestorDetails.filter(record=>record instanceof InvocationBoundaryRecord),...records.filter(record=>record instanceof InvocationBoundaryRecord)];return boundaries.sort((left,right)=>left.scopeId===right.scopeId?left.sequence-right.sequence:Date.parse(left.occurredAt)-Date.parse(right.occurredAt)),{execution:selected.toJSON(),calls:records.filter(record=>record instanceof CallableRecord).map(record=>record.toJSON()),...root===selected?{}:{rootCall:root.toJSON()},...ancestry.length>1?{ancestors:ancestry.slice(1).map(record=>record.toJSON())}:{},boundaries:boundaries.map(record=>record.toJSON()),resources:[...ancestorDetails,...records].filter(record=>record instanceof ResourceRecord).map(record=>record.toJSON()),transcripts:records.filter(record=>record instanceof TranscriptRecord).map(record=>record.toJSON()),memories:records.filter(record=>record instanceof MemoryRecord).map(record=>record.toJSON())}}}export{CallableRecordHelper};

package/dist/callable/record.d.ts

@@ -0,0 +1,18 @@
+import type { CallableRecord as CallableRecordData, CallableValue } from '../data/index.js';
+import { InvocationRecord } from '../invocation/record.js';
+export type CallableRecordOptions = Omit<CallableRecordData, 'id' | 'value' | 'status' | 'childIds'>;
+export declare class CallableRecord extends InvocationRecord<CallableValue> implements CallableRecordData {
+    readonly kind: "invocation";
+    readonly contextId: string;
+    readonly structureKind: CallableRecordData['structureKind'];
+    readonly structureId?: string;
+    readonly name?: string;
+    readonly label?: string;
+    readonly source?: string;
+    readonly callee?: string;
+    readonly role?: string;
+    constructor(options: CallableRecordOptions, value: Omit<CallableValue, 'processes' | 'relationChanges'> & {
+        startedAt: string;
+    });
+    toJSON(): CallableRecordData;
+}

package/dist/callable/record.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{InvocationRecord}from"../invocation/record.js";import{snapshotValue}from"../value/snapshot.js";class CallableRecord extends InvocationRecord{static{__name(this,"CallableRecord")}kind="invocation";contextId;structureKind;structureId;name;label;source;callee;role;constructor(options,value){super(snapshotValue({...value,processes:[],relationChanges:[]}),options.parentId),this.contextId=options.contextId,this.structureKind=options.structureKind,this.structureId=options.structureId,this.name=options.name,this.label=options.label,this.source=options.source,this.callee=options.callee,this.role=options.role,Object.freeze(this)}toJSON(){return{...super.toJSON(),contextId:this.contextId,structureKind:this.structureKind,status:this.status,...this.structureId!==void 0?{structureId:this.structureId}:{},...this.name!==void 0?{name:this.name}:{},...this.label!==void 0?{label:this.label}:{},...this.source!==void 0?{source:this.source}:{},...this.callee!==void 0?{callee:this.callee}:{},...this.role!==void 0?{role:this.role}:{}}}}export{CallableRecord};

package/dist/composite.d.ts

@@ -0,0 +1,13 @@
+import { BaseRecord } from './record.js';
+import { replaceChildren } from './tree/access.js';
+export declare abstract class CompositeRecord<Value> extends BaseRecord<Value> {
+    #private;
+    get childIds(): readonly string[];
+    [replaceChildren](ids: readonly string[]): void;
+    toJSON(): {
+        childIds: readonly string[];
+        id: string;
+        parentId?: string;
+        value: Value;
+    };
+}

package/dist/composite.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{BaseRecord}from"./record.js";import{replaceChildren}from"./tree/access.js";class CompositeRecord extends BaseRecord{static{__name(this,"CompositeRecord")}#childIds=Object.freeze([]);get childIds(){return this.#childIds}[replaceChildren](ids){this.requireWritable(),this.#childIds=ids}toJSON(){return{...super.toJSON(),childIds:this.childIds}}}export{CompositeRecord};

package/dist/construction.d.ts

@@ -0,0 +1,14 @@
+import { ResourceOffer } from '@weiliang0121/capix-resources';
+import type { InvocationBoundaryValue, RecordMutation } from './data/index.js';
+import type { BaseRecord } from './record.js';
+import type { Recorder } from './recorder.js';
+import { InvocationBoundaryRecordHelper } from './invocation/boundary/helper.js';
+import type { InvocationBoundaryRecord } from './invocation/boundary/record.js';
+import type { RecordingRootRecord } from './root/record.js';
+export interface RecordWriter {
+    root(): RecordingRootRecord;
+    add<RecordType extends BaseRecord<unknown>>(record: RecordType): RecordType;
+    update<RecordType extends BaseRecord<unknown>>(record: RecordType, apply: (record: RecordType) => void, describe?: (record: RecordType) => RecordMutation): void;
+    boundary(location: Parameters<typeof InvocationBoundaryRecordHelper.create>[1], type: InvocationBoundaryValue['type']): InvocationBoundaryRecord;
+}
+export declare const RecordWriterResource: ResourceOffer<Recorder, RecordWriter, Recorder, never>;

package/dist/construction.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{InvocationBoundaryRecordHelper}from"./invocation/boundary/helper.js";import{RecordingRootHelper}from"./root/helper.js";const RecordWriterResource=new ResourceOffer({name:"records.construct",expose:__name((recorder,activity)=>Object.freeze({root(){return activity.runSync("root",{output:__name(record=>({id:record.id,kind:record.kind}),"output")},()=>RecordingRootHelper.create(recorder))},add(record){return activity.runSync("add",{input:__name(()=>({id:record.id,kind:record.kind}),"input"),output:__name(added=>({id:added.id,kind:added.kind}),"output")},()=>recorder.add(record))},update(record,apply,describe){activity.runSync("update",{input:__name(()=>({id:record.id,kind:record.kind}),"input")},()=>recorder.update(record,apply,describe))},boundary(location,type){return activity.runSync("boundary",{input:__name(()=>({callId:location.callId,type}),"input"),output:__name(record=>({id:record.id,callId:record.callId,type}),"output")},()=>InvocationBoundaryRecordHelper.create(recorder,location,type))}}),"expose"),timing:"access",describe:__name(recorder=>({recorderId:recorder.id}),"describe")});export{RecordWriterResource};

package/dist/content.d.ts

@@ -0,0 +1,10 @@
+import { type TranscriptEvent } from '@weiliang0121/capix-transcript';
+import { type MemoryEvent } from '@weiliang0121/capix-memory';
+import type { ResourceFact } from '@weiliang0121/capix-resources';
+import type { RecordWriter } from './construction.js';
+import type { RecordChangeSource } from './source.js';
+import { TranscriptRecord } from './transcript/record.js';
+import { MemoryRecord } from './memory/record.js';
+export declare function transcriptRecord(event: TranscriptEvent, source?: RecordChangeSource): TranscriptRecord;
+export declare function memoryRecord(event: MemoryEvent<unknown>, source?: RecordChangeSource): MemoryRecord;
+export declare function recordContentFact(fact: ResourceFact, source: RecordChangeSource, writer: RecordWriter): void;

package/dist/content.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{TranscriptFacts}from"@weiliang0121/capix-transcript";import{MemoryFacts}from"@weiliang0121/capix-memory";import{TranscriptRecord}from"./transcript/record.js";import{MemoryRecord}from"./memory/record.js";function transcriptRecord(event,source){const change=event.change;return new TranscriptRecord({transcriptId:event.transcriptId,revision:event.revision,occurredAt:event.occurredAt,...source?{source}:{}},change.kind==="messages-appended"?{action:"append",start:change.start,end:change.start+change.messages.length}:{action:"segment",previousStart:change.previousStart,start:change.start,end:change.end})}__name(transcriptRecord,"transcriptRecord");function memoryRecord(event,source){return new MemoryRecord({memoriesId:event.memoriesId,memoryId:event.change.memoryId,sequence:event.sequence,...source?{source}:{}},{action:event.change.action,...event.change.reason!==void 0?{reason:event.change.reason}:{},result:{content:event.change.value.content}})}__name(memoryRecord,"memoryRecord");function recordContentFact(fact,source,writer){if(fact.contextId!==source.contextId)throw new Error("Content fact forwarding context does not match record source");TranscriptFacts.match(fact.fact,event=>{if(event.origin?.contextId!==source.contextId)throw new Error("Transcript fact origin does not match record source");writer.add(transcriptRecord(event,source))})||MemoryFacts.match(fact.fact,event=>{if(event.origin?.contextId!==source.contextId)throw new Error("Memory fact origin does not match record source");writer.add(memoryRecord(event,source))})}__name(recordContentFact,"recordContentFact");export{memoryRecord,recordContentFact,transcriptRecord};

package/dist/data/archive.d.ts

@@ -0,0 +1,9 @@
+export interface RecordingArchive {
+    readonly sourceId: string;
+    readonly rootIds: readonly string[];
+    readonly revision: number;
+    readonly state: 'open' | 'sealed' | 'incomplete';
+}
+export type RecordingArchiveOrigin = Omit<RecordingArchive, 'rootIds'>;
+export declare function validateRecordingArchiveOrigin(value: unknown): asserts value is RecordingArchiveOrigin;
+export declare function validateRecordingArchives(value: unknown): asserts value is readonly RecordingArchive[];

package/dist/data/archive.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 validateRecordingArchiveOrigin(value){if(!value||typeof value!="object")throw new Error("\u5386\u53F2\u8BB0\u5F55\u6765\u6E90\u683C\u5F0F\u65E0\u6548\u3002");const source=value;if(typeof source.sourceId!="string"||!source.sourceId||!Number.isSafeInteger(source.revision)||source.revision<0||!["open","sealed","incomplete"].includes(source.state))throw new Error("\u5386\u53F2\u8BB0\u5F55\u6765\u6E90\u683C\u5F0F\u65E0\u6548\u3002")}__name(validateRecordingArchiveOrigin,"validateRecordingArchiveOrigin");function validateRecordingArchives(value){if(!Array.isArray(value))throw new Error("\u5386\u53F2\u8BB0\u5F55\u6765\u6E90\u683C\u5F0F\u65E0\u6548\u3002");const sources=new Set,roots=new Set;for(const archive of value){validateRecordingArchiveOrigin(archive);const source=archive;if(sources.has(source.sourceId)||!Array.isArray(source.rootIds)||source.rootIds.some(id=>typeof id!="string"||!id||roots.has(id)))throw new Error("\u5386\u53F2\u8BB0\u5F55\u6765\u6E90\u5F52\u5C5E\u65E0\u6548\u3002");sources.add(source.sourceId);for(const id of source.rootIds){if(roots.has(id))throw new Error("\u5386\u53F2\u8BB0\u5F55\u6765\u6E90\u5F52\u5C5E\u65E0\u6548\u3002");roots.add(id)}}}__name(validateRecordingArchives,"validateRecordingArchives");export{validateRecordingArchiveOrigin,validateRecordingArchives};

package/dist/data/changes.d.ts

@@ -0,0 +1,43 @@
+import type { BaseRecord, ProcessRecord, RelationChangeRecord } from './types.js';
+import type { RuntimeErrorValue, InvocationFailureFact } from '@weiliang0121/capix-contracts';
+export type RecordKind = 'invocation' | 'runtime' | 'runtime-call' | 'execution' | 'operation' | 'attempt' | 'invocation-boundary' | 'transcript' | 'memory' | 'resource' | 'custom';
+export interface RecordEntry {
+    readonly kind: RecordKind;
+    readonly data: BaseRecord;
+}
+export type RecordMutation = Readonly<{
+    kind: 'added';
+    entry: RecordEntry;
+    parent?: Readonly<{
+        id: string;
+        childId: string;
+    }>;
+}> | Readonly<{
+    kind: 'process-appended';
+    id: string;
+    process: ProcessRecord;
+}> | Readonly<{
+    kind: 'relation-appended';
+    id: string;
+    relation: RelationChangeRecord;
+}> | Readonly<{
+    kind: 'finished';
+    id: string;
+    status: 'succeeded' | 'failed';
+    result: Readonly<{
+        output?: unknown;
+        resultOf?: number;
+        error?: RuntimeErrorValue;
+        failure?: InvocationFailureFact;
+    }>;
+}> | Readonly<{
+    kind: 'replaced';
+    entry: RecordEntry;
+}>;
+export type RecordChangeEvent = Readonly<{
+    type: 'record';
+    recorderId: string;
+    revision: number;
+    occurredAt: string;
+    change: RecordMutation;
+}>;

package/dist/data/changes.js

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

package/dist/data/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './invocation.js';
+export * from './memory.js';
+export * from './transcript.js';
+export * from './resource.js';
+export * from './changes.js';
+export * from './archive.js';
+export * from './validate.js';

package/dist/data/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+export*from"./types.js";export*from"./invocation.js";export*from"./memory.js";export*from"./transcript.js";export*from"./resource.js";export*from"./changes.js";export*from"./archive.js";export*from"./validate.js";

package/dist/data/invocation.d.ts

@@ -0,0 +1,10 @@
+import type { InvocationValue, ProcessRecord } from './types.js';
+type OutputProcess = Extract<ProcessRecord, {
+    type: 'return';
+    output: unknown;
+}>;
+export declare function outputProcess(value: Pick<InvocationValue, 'processes'>, sequence: number, before?: number): OutputProcess;
+export declare function hasOutput(value: InvocationValue): boolean;
+export declare function finalOutputProcess(value: Pick<InvocationValue, 'processes'>, sequence: number): OutputProcess;
+export declare function readOutput<Input, Output>(value: InvocationValue<Input, Output>): Output | undefined;
+export {};

package/dist/data/invocation.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 outputProcess(value,sequence,before=value.processes.length+1){const process=value.processes[sequence-1];if(!Number.isSafeInteger(sequence)||sequence<1||sequence>=before||!process||process.sequence!==sequence||process.type!=="return"||!Object.hasOwn(process,"output")||Object.hasOwn(process,"resultOf"))throw new Error("Invalid local result reference");return process}__name(outputProcess,"outputProcess");function hasOutput(value){return Object.hasOwn(value,"output")||Object.hasOwn(value,"resultOf")}__name(hasOutput,"hasOutput");function finalOutputProcess(value,sequence){const last=value.processes.at(-1);if(!last||last.type!=="return"||sequence!==("resultOf"in last?last.resultOf:last.sequence))throw new Error("Final result must reference the last returned output");return outputProcess(value,sequence)}__name(finalOutputProcess,"finalOutputProcess");function readOutput(value){if(Object.hasOwn(value,"resultOf")){if(Object.hasOwn(value,"output"))throw new Error("Output and local result reference are mutually exclusive");return finalOutputProcess(value,value.resultOf).output}return value.output}__name(readOutput,"readOutput");export{finalOutputProcess,hasOutput,outputProcess,readOutput};

package/dist/data/memory.d.ts

@@ -0,0 +1,26 @@
+import type { BaseRecord } from './types.js';
+export interface MemoryRecordContent {
+    readonly content: string;
+}
+export interface MemoryRecordObservation {
+    readonly items: readonly {
+        readonly id: string;
+        readonly value: MemoryRecordContent;
+        readonly records: readonly MemoryRecord[];
+    }[];
+}
+export interface MemoryRecordValue {
+    readonly action: 'create' | 'update';
+    readonly reason?: string;
+    readonly result: MemoryRecordContent;
+}
+export interface MemoryRecord extends BaseRecord<MemoryRecordValue> {
+    readonly memoryId: string;
+    readonly memoriesId: string;
+    readonly sequence: number;
+    readonly contextId?: string;
+    readonly callId?: string;
+    readonly executionId?: string;
+    readonly operationId?: string;
+}
+export declare function validateMemoryRecordValue(value: unknown): asserts value is MemoryRecordValue;

package/dist/data/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});function validateMemoryRecordValue(value){if(!value||typeof value!="object"||Array.isArray(value))throw new Error("Invalid memory record value");const record=value;if(!Object.hasOwn(record,"action")||!Object.hasOwn(record,"result")||record.action!=="create"&&record.action!=="update"||Object.keys(record).some(key=>!["action","reason","result"].includes(key))||Object.hasOwn(record,"reason")&&typeof record.reason!="string")throw new Error("Invalid memory record value");const result=record.result;if(!result||typeof result!="object"||Array.isArray(result)||Object.keys(result).length!==1||!Object.hasOwn(result,"content")||typeof result.content!="string")throw new Error("Invalid memory display value")}__name(validateMemoryRecordValue,"validateMemoryRecordValue");export{validateMemoryRecordValue};

package/dist/data/resource.d.ts

@@ -0,0 +1,10 @@
+import type { BaseRecord } from './types.js';
+export interface ResourceRecord<Detail = unknown> extends BaseRecord<Detail> {
+    readonly parentId: string;
+    readonly access: string;
+    readonly supplyId: string;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly phase: 'bound' | 'available' | 'unavailable' | 'started' | 'returned' | 'threw';
+    readonly interactionId?: string;
+}

package/dist/data/resource.js

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

package/dist/data/transcript.d.ts

@@ -0,0 +1,19 @@
+import type { BaseRecord } from './types.js';
+export type TranscriptChange = {
+    readonly action: 'append';
+    readonly start: number;
+    readonly end: number;
+} | {
+    readonly action: 'segment';
+    readonly previousStart: number;
+    readonly start: number;
+    readonly end: number;
+};
+export interface TranscriptRecord extends BaseRecord<TranscriptChange> {
+    readonly transcriptId: string;
+    readonly revision: number;
+    readonly occurredAt: string;
+    readonly contextId?: string;
+    readonly callId?: string;
+    readonly executionId?: string;
+}

package/dist/data/transcript.js

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

package/dist/data/types.d.ts

@@ -0,0 +1,189 @@
+import type { RecordingArchiveOrigin } from './archive.js';
+import type { InvocationFailureFact, RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+import type { CallableKind } from '@weiliang0121/capix-contracts';
+import type { TranscriptRecord } from './transcript.js';
+import type { MemoryRecord } from './memory.js';
+import type { ResourceRecord } from './resource.js';
+import type { InvocationRelationIdentity } from '@weiliang0121/capix-contracts';
+export interface BaseRecord<Value = unknown> {
+    readonly id: string;
+    readonly parentId?: string;
+    readonly value: Value;
+}
+export interface CompositeRecord<Value = unknown> extends BaseRecord<Value> {
+    readonly childIds: readonly string[];
+}
+export interface RecordingRootValue {
+    readonly createdAt: string;
+}
+export interface RecordingRootRecord extends CompositeRecord<RecordingRootValue> {
+}
+export type ProcessRecord = Readonly<{
+    sequence: number;
+    eventSequence: number;
+    round: number;
+    occurredAt: string;
+    offsetMs: number;
+} & ({
+    stage: 'execute';
+    type: 'start';
+    input: unknown;
+} | {
+    stage: 'execute' | 'receive' | 'handling';
+    type: 'return';
+    output: unknown;
+} | {
+    stage: 'receive';
+    type: 'return';
+    resultOf: number;
+} | {
+    stage: 'execute' | 'receive' | 'handling';
+    type: 'throw';
+    error: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+} | {
+    stage: 'receive' | 'handling';
+    type: 'continue';
+    input: unknown;
+    reason: string;
+} | {
+    stage: 'handling';
+    type: 'start' | 'unhandled';
+    error: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+} | {
+    stage: 'control';
+    type: 'stop';
+    error: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+})>;
+export type RecordedInvocationResult = Readonly<{
+    status: 'succeeded';
+    output: unknown;
+} | {
+    status: 'failed';
+    error: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+}>;
+export type RecordedRelationChange = Readonly<{
+    kind: 'attached';
+} | {
+    kind: 'returned';
+    result: RecordedInvocationResult;
+} | {
+    kind: 'receiving';
+} | {
+    kind: 'accepted';
+    output: unknown;
+} | {
+    kind: 'handled';
+    output: unknown;
+} | {
+    kind: 'failed';
+    source: 'work' | 'observation';
+    error: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+}>;
+export interface RelationChangeRecord {
+    readonly identity: InvocationRelationIdentity;
+    readonly eventSequence: number;
+    readonly occurredAt: string;
+    readonly offsetMs: number;
+    readonly childId?: string;
+    readonly change: RecordedRelationChange;
+}
+export interface InvocationValue<Input = unknown, Output = unknown> {
+    readonly processes: readonly ProcessRecord[];
+    readonly relationChanges: readonly RelationChangeRecord[];
+    input: Input;
+    output?: Output;
+    resultOf?: number;
+    error?: RuntimeErrorValue;
+    failure?: InvocationFailureFact;
+}
+export interface RuntimeCallValue<Input = unknown, Output = unknown> extends InvocationValue<Input, Output> {
+    readonly startedAt: string;
+}
+export interface RuntimeCallRecord<Input = unknown, Output = unknown> extends CompositeRecord<RuntimeCallValue<Input, Output>> {
+    readonly contextId: string;
+    readonly runtimeInstanceId: string;
+    readonly status: 'running' | 'succeeded' | 'failed';
+}
+export interface ExecutionValue<Input = unknown, Output = unknown> extends InvocationValue<Input, Output> {
+    startedAt: string;
+}
+export interface ExecutionRecord<Input = unknown, Output = unknown> extends CompositeRecord<ExecutionValue<Input, Output>> {
+    readonly contextId: string;
+    readonly status: 'running' | 'succeeded' | 'failed';
+}
+export interface OperationRecord<Input = unknown, Output = unknown> extends CompositeRecord<InvocationValue<Input, Output>> {
+    readonly contextId: string;
+    readonly status: 'running' | 'succeeded' | 'failed';
+    readonly executionId: string;
+    readonly operationInstanceId: string;
+    readonly parentOperationId?: string;
+    readonly operation: string;
+    readonly label: string;
+    readonly source: string;
+    readonly caller: string;
+    readonly callee: string;
+}
+export interface AttemptValue<Input = unknown, Output = unknown> extends InvocationValue<Input, Output> {
+}
+export interface AttemptRecord<Input = unknown, Output = unknown> extends CompositeRecord<AttemptValue<Input, Output>> {
+    readonly contextId: string;
+    readonly status: 'running' | 'succeeded' | 'failed';
+    readonly operationId: string;
+    readonly name: string;
+    readonly label: string;
+    readonly source: string;
+    readonly caller: string;
+    readonly callee: string;
+}
+export interface InvocationBoundaryValue {
+    readonly type: 'call' | 'return' | 'throw';
+    readonly scope: 'work';
+}
+export interface InvocationBoundaryRecord extends BaseRecord<InvocationBoundaryValue> {
+    readonly scopeId: string;
+    readonly executionId?: string;
+    readonly callId: string;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly offsetMs: number;
+}
+export interface LegacyExecutionRecordSnapshot {
+    readonly archive?: RecordingArchiveOrigin;
+    runtimeCall: RuntimeCallRecord;
+    runtimeEvents: InvocationBoundaryRecord[];
+    execution: ExecutionRecord;
+    operations: OperationRecord[];
+    attempts: AttemptRecord[];
+    events: InvocationBoundaryRecord[];
+    resources: ResourceRecord[];
+}
+export interface CallableValue<Input = unknown, Output = unknown> extends InvocationValue<Input, Output> {
+    readonly startedAt?: string;
+}
+export interface CallableRecord<Input = unknown, Output = unknown> extends CompositeRecord<CallableValue<Input, Output>> {
+    readonly contextId: string;
+    readonly structureKind: CallableKind;
+    readonly structureId?: string;
+    readonly name?: string;
+    readonly label?: string;
+    readonly source?: string;
+    readonly callee?: string;
+    readonly role?: string;
+    readonly status: 'running' | 'succeeded' | 'failed';
+}
+export interface ExecutionRecordSnapshot {
+    readonly archive?: RecordingArchiveOrigin;
+    readonly execution: CallableRecord;
+    readonly calls: readonly CallableRecord[];
+    readonly rootCall?: CallableRecord;
+    readonly ancestors?: readonly CallableRecord[];
+    readonly boundaries: readonly InvocationBoundaryRecord[];
+    readonly transcripts: readonly TranscriptRecord[];
+    readonly memories: readonly MemoryRecord[];
+    readonly resources: readonly ResourceRecord[];
+}

package/dist/data/types.js

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

package/dist/data/validate.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutionRecordSnapshot, LegacyExecutionRecordSnapshot, InvocationValue } from './types.js';
+export declare function validateExecutionRecordSnapshot(value: unknown): asserts value is ExecutionRecordSnapshot;
+export declare function validateLegacyExecutionRecordSnapshot(value: unknown): asserts value is LegacyExecutionRecordSnapshot;
+export declare function validateInvocationRecordValue(value: unknown, ownerContextId: string): asserts value is InvocationValue;