@weiliang0121/capix-protocol 0.0.0-stage → 0.1.0

package/dist/observer/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/observer/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/observer/changes.d.ts

@@ -0,0 +1,4 @@
+import type { TranscriptEvent, MemoryEvent } from '../content/changes.js';
+import type { RecordChangeEvent } from '../recording/changes.js';
+import type { InvocationEvent } from '../invocation/changes.js';
+export type ObserverChange = TranscriptEvent | MemoryEvent | RecordChangeEvent | InvocationEvent;

package/dist/observer/changes.js

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

package/dist/observer/execution.d.ts

@@ -0,0 +1,10 @@
+import type { SelectionObservation } from './selection.js';
+import type { OperationRecord } from '../recording/types.js';
+export interface ExecutionObservation extends Omit<SelectionObservation, 'executions'> {
+    executions: (SelectionObservation['executions'][number] & {
+        response?: {
+            index?: number;
+        };
+        memoryStatus?: OperationRecord['status'];
+    })[];
+}

package/dist/observer/execution.js

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

package/dist/observer/index.d.ts

@@ -0,0 +1,8 @@
+export * from './overview.js';
+export * from './execution.js';
+export * from './memory.js';
+export * from './selection.js';
+export * from './changes.js';
+export * from './stream.js';
+export * from './archive.js';
+export * from './interaction.js';

package/dist/observer/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+export*from"./overview.js";export*from"./execution.js";export*from"./memory.js";export*from"./selection.js";export*from"./changes.js";export*from"./stream.js";export*from"./archive.js";export*from"./interaction.js";

package/dist/observer/interaction.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeErrorValue } from '../invocation/errors.js';
+export interface CallInteractionLinks {
+    readonly callId: string;
+    readonly interactionIds: readonly string[];
+}
+export interface InteractionObservation {
+    readonly id: string;
+    readonly contract: string;
+    readonly revision: number;
+    readonly delivery: 'prepared' | 'started';
+    readonly retained: 'persistent' | 'memory';
+    readonly model: string;
+    readonly purpose: string;
+    readonly result: {
+        readonly kind: 'pending';
+    } | {
+        readonly kind: 'received';
+        readonly feedbackId: string;
+    } | {
+        readonly kind: 'unavailable';
+        readonly error: RuntimeErrorValue;
+    };
+}
+export type InteractionUpdate = {
+    readonly type: 'snapshot';
+    readonly value: InteractionObservation;
+} | {
+    readonly type: 'error';
+    readonly error: string;
+    readonly code?: string;
+};

package/dist/observer/interaction.js

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

package/dist/observer/memory.d.ts

@@ -0,0 +1,13 @@
+import type { MessageLocator } from '../content/transcript.js';
+import type { MemoryRecord } from '../recording/memory.js';
+import type { MemoryResultSource } from '../content/memory.js';
+export interface MemoryObservation {
+    readonly items: readonly {
+        id: string;
+        topic: string;
+        content: string;
+        sources: readonly MessageLocator[];
+        sourceResults?: readonly MemoryResultSource[];
+        records: readonly MemoryRecord[];
+    }[];
+}

package/dist/observer/memory.js

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

package/dist/observer/overview.d.ts

@@ -0,0 +1,45 @@
+import type { RecordingArchive, RecordingArchiveOrigin } from './archive.js';
+import type { CallableKind } from '../invocation/types.js';
+import type { ExecutionRecord } from '../recording/types.js';
+import type { ExecutionObservation } from './execution.js';
+import type { MemoryRecord } from '../recording/memory.js';
+import type { TranscriptRangeLocator } from '../content/transcript.js';
+export interface SourceResponse {
+    path: string;
+    content: string;
+}
+export type { ObservationUpdate } from './stream.js';
+export interface InvocationSummary {
+    id: string;
+    contextId: string;
+    recordType: CallableKind;
+    parentId?: string;
+    name: string;
+    label: string;
+    source: string;
+    status: ExecutionRecord['status'];
+    offsetMs: number;
+    durationMs?: number;
+}
+type ObservedExecution = ExecutionObservation['executions'][number];
+export interface ExecutionSummary extends ObservedExecution {
+    readonly archive?: RecordingArchiveOrigin;
+    durationMs?: number;
+    observedOffsetMs: number;
+    calls: InvocationSummary[];
+    transcriptRange?: TranscriptRangeLocator;
+    availableMemoryIds: string[];
+    memoryChanges: {
+        id: string;
+        memoryId: string;
+        operationId?: string;
+        action: MemoryRecord['value']['action'];
+        change: string;
+    }[];
+}
+export interface ObserverOverview {
+    readonly archives?: readonly RecordingArchive[];
+    transcriptId: string;
+    messages: ExecutionObservation['messages'];
+    executions: ExecutionSummary[];
+}

package/dist/observer/overview.js

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

package/dist/observer/selection.d.ts

@@ -0,0 +1,19 @@
+import type { ExecutionRecord, OperationRecord } from '../recording/types.js';
+export interface SelectionObservation {
+    transcriptId: string;
+    messages: {
+        index: number;
+        count: number;
+    }[];
+    executions: {
+        id: string;
+        startedAt: string;
+        status: ExecutionRecord['status'];
+        inputIndex: number;
+        selections: {
+            operationId: string;
+            status: OperationRecord['status'];
+            indexes?: readonly number[];
+        }[];
+    }[];
+}

package/dist/observer/selection.js

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

package/dist/observer/stream.d.ts

@@ -0,0 +1,56 @@
+import type { ObserverOverview } from './overview.js';
+import type { MemoryObservation } from './memory.js';
+import type { RecordEntry } from '../recording/changes.js';
+import type { ObserverChange } from './changes.js';
+import type { InvocationEvent } from '../invocation/changes.js';
+import type { TranscriptEvent } from '../content/changes.js';
+export type TranscriptNotice = Omit<TranscriptEvent, 'change'> & {
+    readonly change: Readonly<{
+        kind: 'messages-appended';
+        start: number;
+        end: number;
+    }> | Extract<TranscriptEvent['change'], {
+        kind: 'segment-started';
+    }>;
+};
+export type ObservationChange = Exclude<ObserverChange, TranscriptEvent> | TranscriptNotice;
+export interface ObservationBaseline {
+    readonly type: 'baseline';
+    readonly scopeId: string;
+    readonly sequence: number;
+    readonly overview: ObserverOverview;
+    readonly memory: MemoryObservation;
+    readonly transcript: {
+        readonly id: string;
+        readonly revision: number;
+        readonly starts: readonly number[];
+    };
+    readonly memories: {
+        readonly id: string;
+        readonly sequence: number;
+    };
+    readonly recorder: {
+        readonly id: string;
+        readonly revision: number;
+    };
+    readonly entries: readonly RecordEntry[];
+    readonly invocations: readonly InvocationEvent[];
+}
+export interface ObservationDelta {
+    readonly type: 'delta';
+    readonly scopeId: string;
+    readonly sequence: number;
+    readonly changes: readonly ObservationChange[];
+}
+export type ObservationFrame = ObservationBaseline | ObservationDelta;
+export interface ObservationSourceIncomplete {
+    readonly type: 'error';
+    readonly code: 'SOURCE_INCOMPLETE';
+    readonly sourceId: string;
+    readonly error: string;
+}
+export type ObservationUpdate = ObservationFrame | ObservationSourceIncomplete | {
+    type: 'error';
+    error: string;
+    code?: string;
+};

package/dist/observer/stream.js

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

package/dist/recording/changes.d.ts

@@ -0,0 +1,43 @@
+import type { BaseRecord, ProcessRecord, RelationChangeRecord } from './types.js';
+import type { RuntimeErrorValue, InvocationFailureFact } from '../invocation/errors.js';
+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/recording/changes.js

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

package/dist/recording/index.d.ts

@@ -0,0 +1,7 @@
+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 './validate.js';

package/dist/recording/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"./validate.js";

package/dist/recording/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/recording/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/recording/memory.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryContent, MemoryResultSource } from '../content/memory.js';
+import type { BaseRecord } from './types.js';
+export interface MemoryRecordValue {
+    readonly action: 'create' | 'update';
+    readonly change: string;
+    readonly sourceIndexes: readonly number[];
+    readonly sourceResults?: readonly MemoryResultSource[];
+    readonly result: MemoryContent;
+}
+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;
+}

package/dist/recording/memory.js

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

package/dist/recording/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/recording/resource.js

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

package/dist/recording/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/recording/transcript.js

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

package/dist/recording/types.d.ts

@@ -0,0 +1,190 @@
+import type { RecordingArchiveOrigin } from '../observer/archive.js';
+import type { InvocationFailureFact, RuntimeErrorValue } from '../invocation/errors.js';
+import type { CallableKind } from '../invocation/types.js';
+import type { TranscriptRecord } from './transcript.js';
+import type { MemoryRecord } from './memory.js';
+import type { ResourceRecord } from './resource.js';
+import type { InvocationRelationIdentity } from '../invocation/types.js';
+export { invocationProcessStages, invocationProcessActions } from '../invocation/types.js';
+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/recording/types.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{invocationProcessStages,invocationProcessActions}from"../invocation/types.js";export{invocationProcessActions,invocationProcessStages};

package/dist/recording/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;

package/dist/recording/validate.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{validateRecordingArchiveOrigin}from"../observer/archive.js";import{hasOutput,outputProcess,readOutput}from"./invocation.js";function validateExecutionRecordSnapshot(value){function fail(){throw new Error("\u8C03\u7528\u8BB0\u5F55\u683C\u5F0F\u65E0\u6548\u6216\u5173\u8054\u7F3A\u5931\u3002")}__name(fail,"fail"),(!value||typeof value!="object")&&fail();const snapshot=value;snapshot.archive!==void 0&&validateRecordingArchiveOrigin(snapshot.archive),(!snapshot.execution||!Array.isArray(snapshot.calls)||!Array.isArray(snapshot.boundaries)||!Array.isArray(snapshot.resources)||!Array.isArray(snapshot.transcripts)||!Array.isArray(snapshot.memories))&&fail();const records=new Map,contexts=new Set,accept=__name(record=>{(!record||typeof record.id!="string"||!record.id||typeof record.contextId!="string"||!record.contextId||record.contextId===record.id||records.has(record.id)||contexts.has(record.id)||records.has(record.contextId)||contexts.has(record.contextId)||!["scene","group","node"].includes(record.structureKind)||!Array.isArray(record.childIds)||new Set(record.childIds).size!==record.childIds.length||record.childIds.some(id=>typeof id!="string"||!id)||!record.value)&&fail(),(record.value.startedAt===void 0?!snapshot.archive:typeof record.value.startedAt!="string"||!Number.isFinite(Date.parse(record.value.startedAt)))&&fail();for(const key of["structureId","name","label","callee","role"])record[key]!==void 0&&(typeof record[key]!="string"||!record[key].trim())&&fail();record.source!==void 0&&typeof record.source!="string"&&fail(),record.parentId!==void 0&&(typeof record.parentId!="string"||!record.parentId)&&fail(),validateInvocationRecordValue(record.value,record.contextId),validRecordedStatus(record.status,record.value)||fail(),records.set(record.id,record),contexts.add(record.contextId)},"accept");for(const record of snapshot.calls)accept(record);const task=records.get(snapshot.execution.id);(!task||JSON.stringify(task)!==JSON.stringify(snapshot.execution))&&fail(),snapshot.rootCall&&snapshot.rootCall.id!==task.id?accept(snapshot.rootCall):snapshot.rootCall&&JSON.stringify(snapshot.rootCall)!==JSON.stringify(task)&&fail(),snapshot.ancestors!==void 0&&!Array.isArray(snapshot.ancestors)&&fail();const ancestors=snapshot.ancestors??[];ancestors.length&&(!snapshot.rootCall||snapshot.rootCall.id===task.id)&&fail();for(const ancestor of ancestors)accept(ancestor);const path=snapshot.rootCall&&snapshot.rootCall.id!==task.id?[snapshot.rootCall,...ancestors,task]:[task];for(let index=1;index<path.length;index++){const parent=path[index-1],child=path[index];(parent.structureKind==="node"||child.parentId!==parent.id||!parent.childIds.includes(child.id))&&fail()}const root=path[0];root.parentId&&records.has(root.parentId)&&fail();for(const record of snapshot.calls){if(contexts.has(record.id)&&fail(),record.id===task.id)continue;const visited=new Set([record.id]);let current=record;for(;current.id!==task.id;){const parent=current.parentId?records.get(current.parentId):void 0;(!parent||visited.has(parent.id)||parent.structureKind==="node"||!parent.childIds.includes(current.id))&&fail(),visited.add(parent.id),current=parent}}for(const record of records.values()){record.structureKind==="scene"&&record.parentId&&records.has(record.parentId)&&fail();for(const relation of record.value.relationChanges){const child=relation.childId?records.get(relation.childId):void 0;child&&(child.parentId!==record.id||child.contextId!==relation.identity.childContextId)&&fail()}}const seen=new Set([...records.keys(),...contexts]),timing=new Map,scopes=new Map;for(const boundary of snapshot.boundaries){const call=records.get(boundary?.callId),prior=scopes.get(boundary?.scopeId);(!boundary||typeof boundary.id!="string"||!boundary.id||seen.has(boundary.id)||!call||boundary.parentId!==call.id||typeof boundary.scopeId!="string"||!boundary.scopeId||!Number.isSafeInteger(boundary.sequence)||boundary.sequence<1||prior&&boundary.sequence<=prior.sequence||!Number.isFinite(boundary.offsetMs)||boundary.offsetMs<(prior?.offsetMs??0)||typeof boundary.occurredAt!="string"||!Number.isFinite(Date.parse(boundary.occurredAt))||boundary.value?.scope!=="work")&&fail(),!snapshot.archive&&(boundary.scopeId!==(snapshot.rootCall??task).id||boundary.executionId!==void 0)&&fail(),seen.add(boundary.id),scopes.set(boundary.scopeId,{sequence:boundary.sequence,offsetMs:boundary.offsetMs});const state=timing.get(call.id)??{scopeId:boundary.scopeId};state.scopeId!==boundary.scopeId&&fail();const time=boundary.offsetMs;boundary.value.type==="call"?((state.started!==void 0||state.ended!==void 0)&&fail(),state.started=time):boundary.value.type==="return"||boundary.value.type==="throw"?((state.started===void 0||state.ended!==void 0||time<state.started||call.status!==(boundary.value.type==="return"?"succeeded":"failed"))&&fail(),state.ended=time):fail(),timing.set(call.id,state)}for(const record of records.values()){const time=timing.get(record.id);!snapshot.archive&&(!time||time.started===void 0||record.status!=="running"&&time.ended===void 0)&&fail();const parentTime=record.parentId?timing.get(record.parentId):void 0;time?.scopeId===parentTime?.scopeId&&(time?.started!==void 0&&parentTime?.started!==void 0&&time.started<parentTime.started&&fail(),time?.ended!==void 0&&parentTime?.ended!==void 0&&time.ended>parentTime.ended&&fail(),time?.started!==void 0&&parentTime?.ended!==void 0&&time.ended===void 0&&fail())}const resourceSequences=new Map,accesses=new Map,interactions=new Map;for(const resource of snapshot.resources){(!resource||typeof resource.id!="string"||!resource.id||seen.has(resource.id)||!records.has(resource.parentId)||typeof resource.access!="string"||!resource.access||typeof resource.supplyId!="string"||!resource.supplyId||typeof resource.occurredAt!="string"||!Number.isFinite(Date.parse(resource.occurredAt))||!Object.hasOwn(resource,"value")||resource.sequence!==(resourceSequences.get(resource.parentId)??0)+1)&&fail(),resourceSequences.set(resource.parentId,resource.sequence),seen.add(resource.id);const key=JSON.stringify([resource.parentId,resource.supplyId,resource.access]);resource.phase==="bound"?((accesses.has(key)||resource.interactionId!==void 0)&&fail(),accesses.set(key,"bound")):resource.phase==="available"||resource.phase==="unavailable"?((accesses.get(key)!=="bound"||resource.interactionId!==void 0)&&fail(),accesses.set(key,resource.phase)):resource.phase==="started"?((accesses.get(key)!=="available"||typeof resource.interactionId!="string"||!resource.interactionId||interactions.has(resource.interactionId))&&fail(),interactions.set(resource.interactionId,key)):resource.phase==="returned"||resource.phase==="threw"?((typeof resource.interactionId!="string"||interactions.get(resource.interactionId)!==key)&&fail(),interactions.delete(resource.interactionId)):fail()}for(const content of[...snapshot.transcripts,...snapshot.memories]){const call=content.callId?records.get(content.callId):void 0;(!content||typeof content.id!="string"||!content.id||seen.has(content.id)||!call||content.parentId!==call.id||content.contextId!==call.contextId||!Object.hasOwn(content,"value"))&&fail(),seen.add(content.id)}}__name(validateExecutionRecordSnapshot,"validateExecutionRecordSnapshot");function validateLegacyExecutionRecordSnapshot(value){const fail=__name(()=>{throw new Error("\u8FD0\u884C\u8BB0\u5F55\u683C\u5F0F\u65E0\u6548\u6216\u5173\u8054\u7F3A\u5931\u3002")},"fail");if(!value||typeof value!="object")return fail();const snapshot=value;snapshot.archive!==void 0&&validateRecordingArchiveOrigin(snapshot.archive);const historical=snapshot.archive!==void 0;if(!snapshot.execution||typeof snapshot.execution.id!="string"||!snapshot.execution.id||!snapshot.execution.value||typeof snapshot.execution.value.startedAt!="string"||!Array.isArray(snapshot.operations)||!Array.isArray(snapshot.attempts)||!Array.isArray(snapshot.events)||!Array.isArray(snapshot.resources))return fail();const executionId=snapshot.execution.id,operations=new Map,parents=new Map,statuses=new Map([[executionId,snapshot.execution.status]]),bodies=new Map([[executionId,snapshot.execution.value]]),contextsByRecord=new Map,contextIds=new Set,acceptContextIdentity=__name(record=>{if(typeof record.contextId!="string"||!record.contextId||record.contextId===record.id||contextIds.has(record.contextId))return fail();contextIds.add(record.contextId),contextsByRecord.set(record.id,record.contextId)},"acceptContextIdentity");acceptContextIdentity(snapshot.execution);const runtimeCall=snapshot.runtimeCall;if(!runtimeCall||typeof runtimeCall.id!="string"||!runtimeCall.id||runtimeCall.id===executionId||typeof runtimeCall.runtimeInstanceId!="string"||!runtimeCall.runtimeInstanceId||!runtimeCall.value||typeof runtimeCall.value.startedAt!="string"||snapshot.execution.parentId!==runtimeCall.id||!["running","succeeded","failed"].includes(runtimeCall.status))return fail();acceptContextIdentity(runtimeCall);const validParticipant=__name(value2=>typeof value2=="string"&&value2.trim().length>0,"validParticipant");for(const operationRecord of snapshot.operations){if(!operationRecord||typeof operationRecord.id!="string"||!operationRecord.id||bodies.has(operationRecord.id)||operationRecord.executionId!==executionId||typeof operationRecord.operationInstanceId!="string"||!operationRecord.operationInstanceId||typeof operationRecord.operation!="string"||typeof operationRecord.label!="string"||typeof operationRecord.source!="string"||!validParticipant(operationRecord.caller)||!validParticipant(operationRecord.callee)||operationRecord.parentOperationId!==void 0&&typeof operationRecord.parentOperationId!="string")return fail();acceptContextIdentity(operationRecord),operations.set(operationRecord.id,operationRecord),parents.set(operationRecord.id,operationRecord.parentOperationId??executionId),statuses.set(operationRecord.id,operationRecord.status),bodies.set(operationRecord.id,operationRecord.value)}for(const attemptRecord of snapshot.attempts){if(!attemptRecord||typeof attemptRecord.id!="string"||!attemptRecord.id||bodies.has(attemptRecord.id)||typeof attemptRecord.operationId!="string"||!operations.has(attemptRecord.operationId)||typeof attemptRecord.name!="string"||!attemptRecord.name.trim()||typeof attemptRecord.label!="string"||!attemptRecord.label.trim()||typeof attemptRecord.source!="string"||!validParticipant(attemptRecord.caller)||!validParticipant(attemptRecord.callee))return fail();acceptContextIdentity(attemptRecord),parents.set(attemptRecord.id,attemptRecord.operationId),statuses.set(attemptRecord.id,attemptRecord.status),bodies.set(attemptRecord.id,attemptRecord.value)}if(bodies.has(runtimeCall.id))return fail();const observedBodies=new Map(bodies);observedBodies.set(runtimeCall.id,runtimeCall.value);for(const id of contextIds)if(observedBodies.has(id))return fail();for(const status of statuses.values())if(!["running","succeeded","failed"].includes(status))return fail();for(const[owner,body]of observedBodies)validateInvocationRecordValue(body,contextsByRecord.get(owner));for(const operationRecord of operations.values())if(operationRecord.parentOperationId!==void 0&&!operations.has(operationRecord.parentOperationId))return fail();for(const id of parents.keys()){const visited=new Set([id]);let ancestor=parents.get(id);for(;ancestor&&ancestor!==executionId;){if(visited.has(ancestor))return fail();visited.add(ancestor),ancestor=parents.get(ancestor)}}const active=new Set,entered=new Set,ended=new Set,boundaryIds=new Set;let time=0;for(const[i,boundary]of snapshot.events.entries()){if(!boundary||typeof boundary.id!="string"||!boundary.id||bodies.has(boundary.id)||contextIds.has(boundary.id)||boundaryIds.has(boundary.id)||boundary.executionId!==executionId||boundary.scopeId!==executionId||!boundary.value||boundary.value.scope!=="work"||!["call","return","throw"].includes(boundary.value.type)||typeof boundary.occurredAt!="string"||!Number.isFinite(Date.parse(boundary.occurredAt))||!bodies.has(boundary.callId)||boundary.sequence!==i+1||!Number.isFinite(boundary.offsetMs)||boundary.offsetMs<time)return fail();boundaryIds.add(boundary.id),time=boundary.offsetMs;const parentId=parents.get(boundary.callId);if(boundary.value.type==="call"){if(entered.has(boundary.callId)||parentId!==void 0&&(!active.has(executionId)||!active.has(parentId))||boundary.callId===executionId&&i!==0)return fail();entered.add(boundary.callId),active.add(boundary.callId)}else{const body=bodies.get(boundary.callId);if(!["return","throw"].includes(boundary.value.type)||!active.has(boundary.callId)||[...active].some(id=>id!==boundary.callId&&(boundary.callId===executionId||parents.get(id)===boundary.callId))||!(boundary.value.type==="return"?hasOutput(body):Object.hasOwn(body,"error"))||statuses.get(boundary.callId)!==(boundary.value.type==="return"?"succeeded":"failed"))return fail();active.delete(boundary.callId),ended.add(boundary.callId)}}if(!historical&&entered.size!==bodies.size)return fail();for(const[id,body]of bodies)if(!historical&&!ended.has(id)&&(statuses.get(id)!=="running"||hasOutput(body)||Object.hasOwn(body,"error"))||historical&&!validRecordedStatus(statuses.get(id),body))return fail();if(!Array.isArray(snapshot.runtimeEvents)||!validRuntimeCallBoundaries(snapshot.runtimeEvents,runtimeCall.id,runtimeCall.status,runtimeCall.value,historical))return fail();for(const boundary of snapshot.runtimeEvents){if(boundaryIds.has(boundary.id)||observedBodies.has(boundary.id)||contextIds.has(boundary.id))return fail();boundaryIds.add(boundary.id)}const resourceIds=new Set,resourceSequences=new Map,accesses=new Map,interactions=new Map;for(const resourceRecord of snapshot.resources){if(!resourceRecord||typeof resourceRecord.id!="string"||!resourceRecord.id||bodies.has(resourceRecord.id)||contextIds.has(resourceRecord.id)||boundaryIds.has(resourceRecord.id)||resourceIds.has(resourceRecord.id)||typeof resourceRecord.parentId!="string"||!observedBodies.has(resourceRecord.parentId)||typeof resourceRecord.access!="string"||!resourceRecord.access||typeof resourceRecord.supplyId!="string"||!resourceRecord.supplyId||typeof resourceRecord.occurredAt!="string"||!Number.isFinite(Date.parse(resourceRecord.occurredAt))||!Object.hasOwn(resourceRecord,"value")||resourceRecord.sequence!==(resourceSequences.get(resourceRecord.parentId)??0)+1)return fail();resourceSequences.set(resourceRecord.parentId,resourceRecord.sequence),resourceIds.add(resourceRecord.id);const accessKey=JSON.stringify([resourceRecord.parentId,resourceRecord.supplyId,resourceRecord.access]);if(resourceRecord.phase==="bound"){if(accesses.has(accessKey)||resourceRecord.interactionId!==void 0)return fail();accesses.set(accessKey,"bound")}else if(resourceRecord.phase==="available"||resourceRecord.phase==="unavailable"){if(accesses.get(accessKey)!=="bound"||resourceRecord.interactionId!==void 0)return fail();accesses.set(accessKey,resourceRecord.phase)}else if(resourceRecord.phase==="started"){if(accesses.get(accessKey)!=="available"||typeof resourceRecord.interactionId!="string"||!resourceRecord.interactionId||interactions.has(resourceRecord.interactionId))return fail();interactions.set(resourceRecord.interactionId,accessKey)}else if(resourceRecord.phase==="returned"||resourceRecord.phase==="threw"){if(typeof resourceRecord.interactionId!="string"||interactions.get(resourceRecord.interactionId)!==accessKey)return fail();interactions.delete(resourceRecord.interactionId)}else return fail()}}__name(validateLegacyExecutionRecordSnapshot,"validateLegacyExecutionRecordSnapshot");function validFailure(value){if(!value||typeof value!="object")return!1;const failure=value;return(failure.kind==="exception"||failure.kind==="error")&&typeof failure.contextId=="string"&&failure.contextId.length>0&&["setup","execute","receive","handling","control","observation"].includes(failure.phase)&&(failure.contract===void 0||typeof failure.contract=="string")}__name(validFailure,"validFailure");function validRelations(body,ownerContextId){const relations=new Map,eventSequences=new Set(body.processes.map(process=>process.eventSequence));let previous=0;for(const entry of body.relationChanges){if(!entry||!Number.isSafeInteger(entry.eventSequence)||entry.eventSequence<=previous||eventSequences.has(entry.eventSequence)||!Number.isFinite(entry.offsetMs)||entry.offsetMs<0||typeof entry.occurredAt!="string"||!Number.isFinite(Date.parse(entry.occurredAt))||!entry.identity||!entry.change)return!1;const identity=entry.identity;if(identity.parentContextId!==ownerContextId||typeof identity.childContextId!="string"||!identity.childContextId||identity.childContextId===ownerContextId||!Number.isSafeInteger(identity.parentRound)||identity.parentRound<0||identity.parentRound>2||identity.key!==void 0&&typeof identity.key!="string"||entry.childId!==void 0&&(typeof entry.childId!="string"||!entry.childId))return!1;const old=relations.get(identity.childContextId);if(old&&(old.identity.parentRound!==identity.parentRound||old.identity.key!==identity.key))return!1;const change=entry.change;if(change.kind==="attached"){if(old)return!1;relations.set(identity.childContextId,{identity,phase:"attached"})}else if(change.kind==="returned"){if(old?.phase!=="attached"||!change.result||!["succeeded","failed"].includes(change.result.status)||(change.result.status==="succeeded"?!Object.hasOwn(change.result,"output"):!validError(change.result.error)||change.result.failure!==void 0&&!validFailure(change.result.failure)))return!1;relations.set(identity.childContextId,{identity,phase:"returned",status:change.result.status})}else if(change.kind==="receiving"){if(old?.phase!=="returned")return!1;relations.set(identity.childContextId,{...old,phase:"receiving"})}else if(change.kind==="accepted"){if(old?.phase!=="receiving"||old.status!=="succeeded"||!Object.hasOwn(change,"output"))return!1;relations.set(identity.childContextId,{...old,phase:"accepted"})}else if(change.kind==="handled"){if(old?.phase!=="receiving"||old.status!=="failed"||!Object.hasOwn(change,"output"))return!1;relations.set(identity.childContextId,{...old,phase:"handled"})}else if(change.kind==="failed"){if(old?.phase!=="receiving"||!validError(change.error)||!["work","observation"].includes(change.source)||change.failure!==void 0&&!validFailure(change.failure))return!1;relations.set(identity.childContextId,{...old,phase:"failed"})}else return!1;eventSequences.add(entry.eventSequence),previous=entry.eventSequence}const times=[...body.processes,...body.relationChanges].sort((a,b)=>a.eventSequence-b.eventSequence);return times.every((entry,index)=>index===0||entry.offsetMs>=times[index-1].offsetMs)}__name(validRelations,"validRelations");function validError(value){return!!value&&typeof value=="object"&&typeof value.code=="string"&&typeof value.message=="string"}__name(validError,"validError");function validRuntimeCallBoundaries(boundaries,id,status,value,historical=!1){if(!historical&&boundaries.length<1||boundaries.length>2)return!1;for(const[index,boundary]of boundaries.entries())if(!boundary||!boundary.id||boundary.scopeId!==id||boundary.executionId!==void 0||boundary.callId!==id||boundary.parentId!==id||boundary.sequence!==index+1||!Number.isFinite(boundary.offsetMs)||boundary.offsetMs<(boundaries[index-1]?.offsetMs??0)||!Number.isFinite(Date.parse(boundary.occurredAt))||boundary.value?.scope!=="work"||boundary.value.type!==(index===0?"call":status==="succeeded"?"return":"throw"))return!1;return historical&&boundaries.length<2?validRecordedStatus(status,value):status==="running"?boundaries.length===1:boundaries.length===2&&(status==="succeeded"?hasOutput(value):Object.hasOwn(value,"error"))}__name(validRuntimeCallBoundaries,"validRuntimeCallBoundaries");function validateInvocationRecordValue(value,ownerContextId){const fail=__name(()=>{throw new Error("\u8C03\u7528\u8BB0\u5F55\u6B63\u6587\u65E0\u6548\u3002")},"fail"),body=value;if(!body||!Array.isArray(body.processes)||!Array.isArray(body.relationChanges)||typeof body!="object"||!Object.hasOwn(body,"input")||hasOutput(body)&&Object.hasOwn(body,"error")||Object.hasOwn(body,"output")&&Object.hasOwn(body,"resultOf")||Object.hasOwn(body,"error")&&(!body.error||typeof body.error.code!="string"||typeof body.error.message!="string")||body.failure&&(!Object.hasOwn(body,"error")||!validFailure(body.failure)))return fail();let previousRound=0,previousTime=0,previousSequence=0;for(const[index,process]of body.processes.entries()){if(!process||!Number.isSafeInteger(process.eventSequence)||process.eventSequence<=previousSequence||process.sequence!==index+1||!Number.isInteger(process.round)||process.round<previousRound||process.round>2||!Number.isFinite(process.offsetMs)||process.offsetMs<previousTime||typeof process.occurredAt!="string"||!(process.stage==="execute"?["start","return","throw"]:process.stage==="receive"?["return","throw","continue"]:process.stage==="handling"?["start","return","throw","continue","unhandled"]:process.stage==="control"?["stop"]:[]).includes(process.type)||process.round===0&&process.stage!=="control"||(process.stage==="execute"&&process.type==="start"||process.type==="continue")&&!Object.hasOwn(process,"input")||process.type==="return"&&Object.hasOwn(process,"output")===Object.hasOwn(process,"resultOf"))return fail();if("resultOf"in process)try{const target=outputProcess(body,process.resultOf,process.sequence);if(process.stage!=="receive"||target.stage!=="execute"||target.round!==process.round||target.sequence!==process.sequence-1)return fail()}catch{return fail()}if((process.type==="throw"||process.type==="stop"||process.stage==="handling"&&(process.type==="start"||process.type==="unhandled"))&&(!process.error||typeof process.error.code!="string"||typeof process.error.message!="string")||process.type==="continue"&&(typeof process.reason!="string"||!process.reason.trim())||"failure"in process&&process.failure&&!validFailure(process.failure))return fail();previousRound=process.round,previousTime=process.offsetMs,previousSequence=process.eventSequence}if(!validRelations(body,ownerContextId))return fail();if(Object.hasOwn(body,"resultOf"))try{readOutput(body)}catch{return fail()}}__name(validateInvocationRecordValue,"validateInvocationRecordValue");function validRecordedStatus(status,body){return status==="running"?!hasOutput(body)&&!Object.hasOwn(body,"error"):status==="succeeded"?hasOutput(body)&&!Object.hasOwn(body,"error"):status==="failed"&&Object.hasOwn(body,"error")&&!hasOutput(body)}__name(validRecordedStatus,"validRecordedStatus");export{validateExecutionRecordSnapshot,validateInvocationRecordValue,validateLegacyExecutionRecordSnapshot};