@weiliang0121/capix-contracts 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,19 @@
-# Temporary Holding Version
+# @weiliang0121/capix-contracts
 
-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.
+Shared contracts, stable data values, and runtime errors for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-contracts
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-contracts`
+
+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/callable/kind.d.ts

@@ -0,0 +1,2 @@
+export declare const callableKinds: readonly ["scene", "group", "node"];
+export type CallableKind = (typeof callableKinds)[number];

package/dist/callable/kind.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+const callableKinds=["scene","group","node"];export{callableKinds};

package/dist/callable/signature.d.ts

@@ -0,0 +1,26 @@
+import type { CallableKind } from './kind.js';
+export declare const invocationSignature: unique symbol;
+export interface InvocationSignature<Input, Output, Delta = never> {
+    readonly input: Input;
+    readonly acceptsInput: (input: Input) => void;
+    readonly output: Output;
+    readonly delta: Delta;
+}
+export interface CallableContract<Kind extends CallableKind = CallableKind, Input = unknown, Output = unknown, Delta = unknown> {
+    readonly kind: Kind;
+    readonly [invocationSignature]: InvocationSignature<Input, Output, Delta>;
+}
+type Signature<Definition> = Definition extends {
+    readonly [invocationSignature]?: infer S;
+} ? NonNullable<S> : InvocationSignature<unknown, unknown, unknown>;
+export type CallableInput<Callable> = Signature<Callable> extends {
+    readonly input: infer Input;
+} ? Input : unknown;
+export type CallableOutput<Callable> = Signature<Callable> extends {
+    readonly output: infer Output;
+} ? Output : unknown;
+export type CallableDelta<Callable> = Signature<Callable> extends {
+    readonly delta: infer Delta;
+} ? Delta : never;
+export type CallableShape<Structure> = Structure extends CallableContract<infer Kind, infer Input, infer Output, infer Delta> ? CallableContract<Kind, Input, Output, Delta> : never;
+export {};

package/dist/callable/signature.js

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

package/dist/checkpoint/codec.d.ts

@@ -0,0 +1,12 @@
+import type { Stable } from '../value.js';
+export type CheckpointValue = null | boolean | number | string | readonly CheckpointValue[] | {
+    readonly [key: string]: CheckpointValue;
+};
+export interface CheckpointCodec<Value> {
+    encode(value: Stable<Value>): CheckpointValue;
+    decode(value: CheckpointValue): Value | Stable<Value>;
+}
+export interface CheckpointContract {
+    readonly key: string;
+    readonly version: number;
+}

package/dist/checkpoint/codec.js

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

package/dist/checkpoint/facts.d.ts

@@ -0,0 +1,12 @@
+import type { Stable } from '../value.js';
+import type { ChildFacts } from '../children/facts.js';
+import type { ContinuationFact } from './history.js';
+import type { CheckpointReferenceSlots, SavedReferenceFacts } from './references.js';
+export interface CheckpointFacts<Input, Slots extends CheckpointReferenceSlots = CheckpointReferenceSlots> {
+    readonly initialInput: Stable<Input>;
+    readonly input: Stable<Input>;
+    readonly round: 1 | 2;
+    readonly continuation?: ContinuationFact;
+    readonly references: SavedReferenceFacts<Slots>;
+    readonly children: ChildFacts;
+}

package/dist/checkpoint/facts.js

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

package/dist/checkpoint/history.d.ts

@@ -0,0 +1,14 @@
+import type { ChildReference } from '../children/reference.js';
+export type ExceptionOrigin = {
+    readonly kind: 'self';
+    readonly phase: 'execute' | 'accept';
+} | {
+    readonly kind: 'child-return' | 'child-reception';
+    readonly child: ChildReference;
+};
+export interface ContinuationFact {
+    readonly fromRound: 1;
+    readonly stage: 'accept' | 'handling';
+    readonly reason: string;
+    readonly origin?: ExceptionOrigin;
+}

package/dist/checkpoint/history.js

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

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './codec.js';
+export type * from './history.js';
+export type * from './references.js';
+export type * from './facts.js';
+export type * from './writer.js';
+export type * from './reception.js';

package/dist/checkpoint/index.js

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

package/dist/checkpoint/reception.d.ts

@@ -0,0 +1,23 @@
+import type { Stable } from '../value.js';
+import type { CheckpointValue } from './codec.js';
+import type { ChildContract } from '../children/contract.js';
+import type { CallableShape } from '../callable/signature.js';
+export interface ReceptionValue<Value> {
+    readonly check: (value: unknown) => Value | Stable<Value>;
+    readonly encode: (value: NoInfer<Stable<Value>>) => CheckpointValue;
+    readonly decode: (value: CheckpointValue) => NoInfer<Value> | NoInfer<Stable<Value>>;
+}
+declare const receptionSignature: unique symbol;
+interface ReceptionContract<Definition extends ChildContract, Value> {
+    readonly child: Definition;
+    readonly value: ReceptionValue<Value>;
+    readonly [receptionSignature]: (child: Definition, value: Value) => {
+        readonly child: Definition;
+        readonly value: Value;
+    };
+}
+export type ReceptionDefinition<Definition extends ChildContract, Value> = ReceptionContract<CallableShape<Definition>, Value>;
+export type ReceptionRegistration<Definition extends ChildContract = ChildContract> = ReceptionContract<any, any> & {
+    readonly child: CallableShape<Definition>;
+};
+export {};

package/dist/checkpoint/reception.js

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

package/dist/checkpoint/references.d.ts

@@ -0,0 +1,31 @@
+import type { ChildContract } from '../children/contract.js';
+import type { ChildReference } from '../children/reference.js';
+import type { ChildFact } from '../children/facts.js';
+export interface ChildReferenceSlot<Definition extends ChildContract = ChildContract, Many extends boolean = boolean> {
+    readonly definition: Definition;
+    readonly many: Many;
+}
+export type CheckpointReferenceSlots = Readonly<Record<string, ChildReferenceSlot>>;
+declare const occurrenceDefinition: unique symbol;
+declare const selectionDefinition: unique symbol;
+export interface CheckpointOccurrence<Definition extends ChildContract = ChildContract> {
+    readonly [occurrenceDefinition]: Definition;
+}
+export interface CheckpointSelection<Definition extends ChildContract = ChildContract> extends Iterable<ChildReference<Definition>> {
+    readonly [selectionDefinition]: Definition;
+    readonly length: number;
+    at(index: number): ChildReference<Definition> | undefined;
+    occurrenceAt(index: number): CheckpointOccurrence<Definition> | undefined;
+    add(reference: ChildReference<Definition>): CheckpointOccurrence<Definition>;
+    remove(occurrence: CheckpointOccurrence<Definition>): void;
+}
+export type SavedReferences<Slots extends CheckpointReferenceSlots> = {
+    readonly [Key in keyof Slots]: Slots[Key] extends ChildReferenceSlot<infer Definition, infer Many> ? (Many extends true ? readonly ChildReference<Definition>[] : ChildReference<Definition>) : never;
+};
+export type CheckpointWriteReferences<Slots extends CheckpointReferenceSlots> = {
+    readonly [Key in keyof Slots]: Slots[Key] extends ChildReferenceSlot<infer Definition, infer Many> ? (Many extends true ? readonly ChildReference<Definition>[] | CheckpointSelection<Definition> : ChildReference<Definition>) : never;
+};
+export type SavedReferenceFacts<Slots extends CheckpointReferenceSlots> = {
+    readonly [Key in keyof Slots]: Slots[Key] extends ChildReferenceSlot<infer Definition, infer Many> ? (Many extends true ? readonly ChildFact<Definition>[] : ChildFact<Definition>) : never;
+};
+export {};

package/dist/checkpoint/references.js

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

package/dist/checkpoint/writer.d.ts

@@ -0,0 +1,33 @@
+import type { CallableKind } from '../callable/kind.js';
+import type { CheckpointCodec } from './codec.js';
+import type { CheckpointReferenceSlots, CheckpointWriteReferences, CheckpointSelection } from './references.js';
+import type { ChildContract } from '../children/contract.js';
+import type { ChildReference } from '../children/reference.js';
+declare const checkpointOwner: unique symbol;
+export interface CheckpointPointOwner<Kind extends CallableKind, Input, Output, Delta> {
+    readonly [checkpointOwner]?: (owner: {
+        readonly kind: Kind;
+        readonly input: Input;
+        readonly output: Output;
+    }) => {
+        readonly kind: Kind;
+        readonly input: Input;
+        readonly output: Output;
+        readonly delta: Delta;
+    };
+}
+export interface AuthorCheckpointWriter<Kind extends CallableKind, Input, Output, Delta = never> {
+    <Point extends CheckpointPointOwner<Kind, Input, Output, Delta> & {
+        readonly state: CheckpointCodec<any>;
+        readonly references: CheckpointReferenceSlots;
+    }>(options: {
+        readonly point: Point;
+        readonly state: NoInfer<ReturnType<Point['state']['decode']>>;
+    } & (keyof Point['references'] extends never ? {
+        readonly refs?: NoInfer<CheckpointWriteReferences<Point['references']>>;
+    } : {
+        readonly refs: NoInfer<CheckpointWriteReferences<Point['references']>>;
+    })): void;
+    select<Definition extends ChildContract>(definition: Kind extends 'node' ? never : Definition, initial?: readonly ChildReference<NoInfer<Definition>>[]): CheckpointSelection<Definition>;
+}
+export {};

package/dist/checkpoint/writer.js

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

package/dist/children/call.d.ts

@@ -0,0 +1,34 @@
+import type { Stable } from '../value.js';
+import type { CallableInput, CallableOutput, CallableShape } from '../callable/signature.js';
+import type { OperationResult } from '../operation.js';
+import type { ReceptionDefinition } from '../checkpoint/reception.js';
+import type { ChildReference } from './reference.js';
+import type { ChildContract } from './contract.js';
+import type { ChildFacts } from './facts.js';
+import type { ChildOptions, ChildOperationOptions, ChildReceptionOptions, ChildInvocationOptions, ChildInvocationReceptionOptions } from './options.js';
+export interface ChildCall<Definition extends ChildContract> {
+    readonly ref: ChildReference<Definition>;
+    readonly key?: string;
+    invoke(): Promise<Stable<CallableOutput<Definition>>>;
+    invoke<Value, const Options extends NoInfer<ChildInvocationReceptionOptions<Definition, Value>>>(options: Options & {
+        readonly reception: ReceptionDefinition<Definition, Value>;
+    }): Promise<Stable<OperationResult<Stable<CallableOutput<Definition>>, Options>>>;
+    invoke<const Options extends ChildInvocationOptions<Definition>>(options: Options & ChildInvocationOptions<Definition>): Promise<Stable<OperationResult<Stable<CallableOutput<Definition>>, Options>>>;
+    run(): Promise<Stable<CallableOutput<Definition>>>;
+    accept(): Promise<Stable<CallableOutput<Definition>>>;
+    accept<Value>(receive: (output: Stable<CallableOutput<Definition>>) => Value | Stable<Value> | Promise<Value | Stable<Value>>): Promise<Stable<Value>>;
+    accept<Value>(reception: ReceptionDefinition<Definition, Value>, receive: (output: Stable<CallableOutput<Definition>>) => NoInfer<Value> | NoInfer<Stable<Value>> | Promise<NoInfer<Value> | NoInfer<Stable<Value>>>): Promise<Stable<Value>>;
+}
+export interface ChildCalls<Allowed extends ChildContract = ChildContract> {
+    invoke<Definition extends Allowed | CallableShape<Allowed>>(definition: Definition, input: NoInfer<CallableInput<Definition> | Stable<CallableInput<Definition>>>): Promise<Stable<CallableOutput<Definition>>>;
+    invoke<Definition extends Allowed | CallableShape<Allowed>, Value, const Options extends NoInfer<ChildReceptionOptions<Definition, Value>>>(definition: Definition, input: NoInfer<CallableInput<Definition> | Stable<CallableInput<Definition>>>, options: Options & {
+        readonly reception: ReceptionDefinition<NoInfer<Definition>, Value>;
+    }): Promise<Stable<OperationResult<Stable<CallableOutput<Definition>>, Options>>>;
+    invoke<Definition extends Allowed | CallableShape<Allowed>, const Options extends ChildOperationOptions<NoInfer<Definition>>>(definition: Definition, input: NoInfer<CallableInput<Definition> | Stable<CallableInput<Definition>>>, options: Options & ChildOperationOptions<NoInfer<Definition>>): Promise<Stable<OperationResult<Stable<CallableOutput<Definition>>, Options>>>;
+    create<Definition extends Allowed | CallableShape<Allowed>>(definition: Definition, input: NoInfer<CallableInput<Definition> | Stable<CallableInput<Definition>>>, options?: ChildOptions<Definition>): ChildCall<Definition>;
+    open<Definition extends ChildContract>(reference: ChildReference<Definition>): ChildCall<Definition>;
+    readonly facts: ChildFacts;
+}
+export interface ResumeChildCalls<Allowed extends ChildContract = ChildContract> extends ChildCalls<Allowed> {
+    resume<Definition extends Allowed | CallableShape<Allowed>>(reference: ChildReference<Definition>): ChildCall<Definition>;
+}

package/dist/children/call.js

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

package/dist/children/contract.d.ts

@@ -0,0 +1,2 @@
+import type { CallableContract } from '../callable/signature.js';
+export type ChildContract = CallableContract<'group', any> | CallableContract<'node', any>;

package/dist/children/contract.js

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

package/dist/children/facts.d.ts

@@ -0,0 +1,53 @@
+import type { Stable } from '../value.js';
+import type { CallableInput, CallableOutput } from '../callable/signature.js';
+import type { InvocationFailureFact, RuntimeErrorValue } from '../diagnostic.js';
+import type { ReceptionDefinition } from '../checkpoint/reception.js';
+import type { ChildReference } from './reference.js';
+import type { ChildContract } from './contract.js';
+export type ChildReturnFact<Output> = {
+    readonly status: 'succeeded';
+    readonly output: Stable<Output>;
+} | {
+    readonly status: 'failed';
+    readonly diagnostic: Stable<RuntimeErrorValue>;
+    readonly failure?: InvocationFailureFact;
+} | {
+    readonly status: 'cancelled';
+    readonly diagnostic: Stable<RuntimeErrorValue>;
+};
+export interface ChildFact<Definition = unknown> {
+    readonly ref: ChildReference<Definition>;
+    readonly key?: string;
+    readonly parentRound: 1 | 2;
+    readonly order: number;
+    readonly input: Stable<CallableInput<Definition>>;
+    readonly returned: ChildReturnFact<CallableOutput<Definition>> | undefined;
+    readonly reception: {
+        readonly status: 'pending' | 'receiving';
+    } | {
+        readonly status: 'accepted' | 'handled';
+        readonly value: unknown;
+    } | {
+        readonly status: 'failed';
+        readonly diagnostic: Stable<RuntimeErrorValue>;
+        readonly failure?: InvocationFailureFact;
+    };
+    readonly progress?: {
+        readonly round: 1 | 2;
+        readonly currentInput: Stable<CallableInput<Definition>>;
+        readonly phase: 'execute' | 'receive' | 'handling';
+    };
+}
+export interface ChildFacts {
+    accepted<Definition extends ChildContract, Value>(reference: ChildReference<Definition>, reception: ReceptionDefinition<NoInfer<Definition>, Value>): Stable<Value>;
+    handled<Definition extends ChildContract, Value>(reference: ChildReference<Definition>, reception: ReceptionDefinition<NoInfer<Definition>, Value>): Stable<Value>;
+    get<Definition extends ChildContract>(reference: ChildReference<Definition>): ChildFact<Definition>;
+    require<Definition extends ChildContract>(definition: Definition, reference: ChildReference): ChildFact<Definition>;
+    list<Definition extends ChildContract>(definition: Definition, query?: {
+        readonly parentRound?: 1 | 2;
+    }): readonly ChildFact<Definition>[];
+    requireUnique<Definition extends ChildContract>(definition: Definition, query: {
+        readonly parentRound: 1 | 2;
+    }): ChildFact<Definition>;
+    values(): readonly ChildFact[];
+}

package/dist/children/facts.js

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

package/dist/children/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './contract.js';
+export type * from './reference.js';
+export type * from './call.js';
+export type * from './facts.js';
+export type * from './options.js';

package/dist/children/index.js

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

package/dist/children/options.d.ts

@@ -0,0 +1,32 @@
+import type { Stable } from '../value.js';
+import type { CallableDelta, CallableOutput } from '../callable/signature.js';
+import type { InvocationOutputReceiver } from '../output.js';
+import type { OperationOptions, Reception } from '../operation.js';
+import type { ReceptionDefinition } from '../checkpoint/reception.js';
+import type { ChildContract } from './contract.js';
+export interface ChildOptions<Definition extends ChildContract> {
+    readonly key?: string;
+    readonly output?: InvocationOutputReceiver<CallableOutput<Definition>, CallableDelta<Definition>>;
+}
+export type ChildOperationOptions<Definition extends ChildContract> = ChildOptions<Definition> & OperationOptions<Stable<CallableOutput<Definition>>, unknown, unknown, Stable<CallableDelta<Definition>>> & {
+    readonly reception?: never;
+};
+export type ChildReceptionOptions<Definition extends ChildContract, Value> = ChildOptions<Definition> & Pick<OperationOptions<Stable<CallableOutput<Definition>>, unknown, unknown, Stable<CallableDelta<Definition>>>, 'delta'> & {
+    readonly reception: ReceptionDefinition<Definition, Value>;
+} & ([Stable<CallableOutput<Definition>>] extends [Value | Stable<Value>] ? {
+    readonly result?: Reception<Stable<CallableOutput<Definition>>, unknown, NoInfer<Value> | NoInfer<Stable<Value>>>;
+} : {
+    readonly result: Reception<Stable<CallableOutput<Definition>>, unknown, NoInfer<Value> | NoInfer<Stable<Value>>> & {
+        readonly succeeded: (value: Stable<CallableOutput<Definition>>) => NoInfer<Value> | NoInfer<Stable<Value>> | PromiseLike<NoInfer<Value> | NoInfer<Stable<Value>>>;
+    };
+});
+export type ChildInvocationOptions<Definition extends ChildContract> = Pick<ChildOperationOptions<Definition>, 'result' | 'reception'> & {
+    readonly delta?: never;
+    readonly output?: never;
+    readonly key?: never;
+};
+export type ChildInvocationReceptionOptions<Definition extends ChildContract, Value> = Omit<ChildReceptionOptions<Definition, Value>, 'delta' | 'output' | 'key'> & {
+    readonly delta?: never;
+    readonly output?: never;
+    readonly key?: never;
+};

package/dist/children/options.js

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

package/dist/children/reference.d.ts

@@ -0,0 +1,5 @@
+declare const childReferenceSignature: unique symbol;
+export interface ChildReference<Definition = unknown> {
+    readonly [childReferenceSignature]: Definition;
+}
+export {};

package/dist/children/reference.js

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

package/dist/diagnostic.d.ts

@@ -0,0 +1,18 @@
+export type RuntimeErrorDetail = null | boolean | number | string | RuntimeErrorDetail[] | {
+    [key: string]: RuntimeErrorDetail;
+};
+export interface RuntimeErrorValue {
+    code: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    detail?: RuntimeErrorDetail;
+    cause?: RuntimeErrorValue;
+    errors?: RuntimeErrorValue[];
+}
+export interface InvocationFailureFact {
+    readonly kind: 'exception' | 'error';
+    readonly phase: 'setup' | 'execute' | 'receive' | 'handling' | 'control' | 'observation';
+    readonly contextId: string;
+    readonly contract?: string;
+}

package/dist/diagnostic.js

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

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class RuntimeError extends Error {
+    readonly code: string;
+    readonly detail?: unknown | undefined;
+    constructor(code: string, message: string, detail?: unknown | undefined, options?: ErrorOptions);
+}

package/dist/errors.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});class RuntimeError extends Error{static{__name(this,"RuntimeError")}code;detail;constructor(code,message,detail,options){super(message,options),this.code=code,this.detail=detail,this.name=new.target.name}}export{RuntimeError};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { callableKinds } from './callable/kind.js';
+export type { CallableKind } from './callable/kind.js';
+export type * from './callable/signature.js';
+export type { InvocationIdentity, InvocationOrigin, InvocationRelationIdentity } from './invocation.js';
+export { stableValue, stableValueLimits, StableValueError } from './value.js';
+export type { Stable, StableArray, StableValueErrorCode } from './value.js';
+export type * from './operation.js';
+export type * from './children/index.js';
+export type * from './work.js';
+export type * from './output.js';
+export type * from './observation.js';
+export type * from './checkpoint/index.js';
+export type * from './diagnostic.js';
+export { RuntimeError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{callableKinds}from"./callable/kind.js";import{stableValue,stableValueLimits,StableValueError}from"./value.js";import{RuntimeError}from"./errors.js";export{RuntimeError,StableValueError,callableKinds,stableValue,stableValueLimits};

package/dist/invocation.d.ts

@@ -0,0 +1,15 @@
+import type { CallableKind } from './callable/kind.js';
+export interface InvocationIdentity {
+    readonly contextId: string;
+    readonly kind: CallableKind;
+    readonly parentContextId?: string;
+}
+export interface InvocationOrigin {
+    readonly contextId: string;
+}
+export interface InvocationRelationIdentity {
+    readonly parentContextId: string;
+    readonly childContextId: string;
+    readonly parentRound: number;
+    readonly key?: string;
+}

package/dist/invocation.js

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

package/dist/observation.d.ts

@@ -0,0 +1,4 @@
+export interface BusinessEvent {
+    readonly event: string;
+    readonly [field: string]: unknown;
+}

package/dist/observation.js

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

package/dist/operation.d.ts

@@ -0,0 +1,22 @@
+export type OperationOutcome<Value, Failure = unknown> = {
+    readonly status: 'succeeded';
+    readonly value: Value;
+} | {
+    readonly status: 'failed';
+    readonly failure: Failure;
+};
+export interface Reception<Value, Failure = unknown, Result = Value> {
+    readonly succeeded?: (value: Value) => Result | PromiseLike<Result>;
+    readonly failed?: (failure: Failure) => Result | PromiseLike<Result>;
+}
+export interface OperationOptions<Value, Failure = unknown, Result = Value, Delta = never> {
+    readonly delta?: [Delta] extends [never] ? never : (delta: Delta) => void;
+    readonly result?: Reception<Value, Failure, Result>;
+}
+type CallbackResult<Callback, Fallback = never> = Callback extends (...args: never[]) => infer Result ? Awaited<Result> : Fallback;
+type PropertyValue<Owner, Key extends PropertyKey> = Owner extends unknown ? (Key extends keyof Owner ? Owner[Key] : undefined) : never;
+type ResultReception<Options> = PropertyValue<Options, 'result'>;
+type SuccessfulResult<Value, Handler> = [Handler] extends [never] ? Value : CallbackResult<PropertyValue<Handler, 'succeeded'>, Value>;
+type FailedResult<Handler> = CallbackResult<PropertyValue<Handler, 'failed'>>;
+export type OperationResult<Value, Options> = SuccessfulResult<Value, ResultReception<Options>> | FailedResult<ResultReception<Options>>;
+export {};

package/dist/operation.js

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

package/dist/output.d.ts

@@ -0,0 +1,30 @@
+import type { Stable } from './value.js';
+export interface OutputDeclaration<Result, Delta = never> {
+    result(value: unknown): Result | Stable<Result>;
+    delta?(value: unknown): Delta | Stable<Delta>;
+}
+export interface InvocationOutputWriter<Delta> {
+    emit(delta: Delta | Stable<Delta>): void;
+}
+export type InvocationOutputEvent<Result = unknown, Delta = unknown> = Readonly<{
+    contextId: string;
+    round: number;
+    sequence: number;
+} & ({
+    kind: 'started' | 'sealed';
+} | {
+    kind: 'delta';
+    delta: Stable<Delta>;
+} | {
+    kind: 'discarded';
+    reason: 'exception' | 'continue' | 'failed';
+} | {
+    kind: 'completed';
+    result: Stable<Result>;
+    discarded: boolean;
+})>;
+export interface ProgressReceiver<Fact> {
+    receive(fact: Readonly<Fact>): undefined;
+    failed?(error: unknown): undefined;
+}
+export type InvocationOutputReceiver<Result = unknown, Delta = unknown> = ProgressReceiver<InvocationOutputEvent<Result, Delta>>;

package/dist/output.js

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

package/dist/value.d.ts

@@ -0,0 +1,18 @@
+export type Stable<T> = T extends (...args: never[]) => unknown ? never : T extends readonly unknown[] ? (number extends T['length'] ? StableArray<Stable<T[number]>> : {
+    readonly [Key in keyof T]: Stable<T[Key]>;
+}) : T extends object ? {
+    readonly [Key in keyof T]: Stable<T[Key]>;
+} : T;
+export interface StableArray<T> extends ReadonlyArray<T> {
+}
+export declare const stableValueLimits: Readonly<{
+    maxDepth: 64;
+    maxExpandedValues: 1000000;
+    maxTextUnits: number;
+}>;
+export type StableValueErrorCode = 'UNSUPPORTED_VALUE' | 'CYCLIC_VALUE' | 'DEPTH_LIMIT' | 'VALUE_LIMIT' | 'TEXT_LIMIT' | 'INSPECTION_FAILED';
+export declare class StableValueError extends Error {
+    readonly code: StableValueErrorCode;
+    constructor(code: StableValueErrorCode);
+}
+export declare function stableValue<T>(value: T | Stable<T>): Stable<T>;

package/dist/value.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});const stableValueLimits=Object.freeze({maxDepth:64,maxExpandedValues:1e6,maxTextUnits:67108864}),messages=Object.freeze({UNSUPPORTED_VALUE:"Stable values require ordinary data records, dense arrays and supported scalar values",CYCLIC_VALUE:"Stable values cannot contain cycles",DEPTH_LIMIT:"Stable value exceeds its depth limit",VALUE_LIMIT:"Stable value exceeds its expanded value limit",TEXT_LIMIT:"Stable value exceeds its expanded text limit",INSPECTION_FAILED:"Stable value could not be inspected"}),errors=new WeakSet;class StableValueError extends Error{static{__name(this,"StableValueError")}code;constructor(code){const safeCode=typeof code=="string"&&Object.hasOwn(messages,code)?code:"INSPECTION_FAILED";super(messages[safeCode]),this.name="StableValueError",this.code=safeCode}}const trusted=new WeakMap;function fail(code){const error=Object.freeze(new StableValueError(code));throw errors.add(error),error}__name(fail,"fail");function depthWithin(depth){depth>stableValueLimits.maxDepth&&fail("DEPTH_LIMIT")}__name(depthWithin,"depthWithin");function textWithin(text){text>stableValueLimits.maxTextUnits&&fail("TEXT_LIMIT")}__name(textWithin,"textWithin");function stableValue(value){try{const memo=new WeakMap,ancestors=new Set,completed=[],visit=__name((source,depth)=>{if(depthWithin(depth),source==null||typeof source=="boolean"||typeof source=="string"||typeof source=="number"&&Number.isFinite(source)){const text2=typeof source=="string"?source.length:0;return textWithin(text2),{value:source,proof:{height:0,values:1,text:text2}}}typeof source!="object"&&fail("UNSUPPORTED_VALUE"),ancestors.has(source)&&fail("CYCLIC_VALUE");const prior=memo.get(source);if(prior)return depthWithin(depth+prior.proof.height),prior;const evidence=trusted.get(source);if(evidence)return depthWithin(depth+evidence.height),{value:source,proof:evidence};const array=Array.isArray(source),prototype=Object.getPrototypeOf(source);(array?prototype!==Array.prototype:prototype!==Object.prototype&&prototype!==null)&&fail("UNSUPPORTED_VALUE");const keys=Reflect.ownKeys(source),entries=keys.length-(array?1:0);if(entries+1>stableValueLimits.maxExpandedValues&&fail("VALUE_LIMIT"),array){const length=Object.getOwnPropertyDescriptor(source,"length");(!length||!Object.hasOwn(length,"value")||length.value!==entries)&&fail("UNSUPPORTED_VALUE")}const owned=array?[]:Object.create(prototype===null?null:Object.prototype);let height=0,values=1,text=0,index=0;ancestors.add(source);try{for(const key of keys){if(typeof key!="string"&&fail("UNSUPPORTED_VALUE"),array&&key==="length")continue;array&&key!==String(index++)&&fail("UNSUPPORTED_VALUE");const descriptor=Object.getOwnPropertyDescriptor(source,key);(!descriptor||!descriptor.enumerable||!Object.hasOwn(descriptor,"value"))&&fail("UNSUPPORTED_VALUE");const child=visit(descriptor.value,depth+1);height=Math.max(height,child.proof.height+1),values+=child.proof.values,values>stableValueLimits.maxExpandedValues&&fail("VALUE_LIMIT"),text+=child.proof.text+(array?0:key.length),textWithin(text),Object.defineProperty(owned,key,{value:child.value,enumerable:!0})}Object.freeze(owned);const proof=Object.freeze({height,values,text}),fixed=Object.freeze({value:owned,proof});return memo.set(source,fixed),completed.push({value:owned,proof}),fixed}finally{ancestors.delete(source)}},"visit"),result=visit(value,0);for(const entry of completed)trusted.set(entry.value,entry.proof);return result.value}catch(cause){throw cause!==null&&(typeof cause=="object"||typeof cause=="function")&&errors.has(cause)?cause:new StableValueError("INSPECTION_FAILED")}}__name(stableValue,"stableValue");export{StableValueError,stableValue,stableValueLimits};

package/dist/work.d.ts

@@ -0,0 +1,16 @@
+import type { Stable } from './value.js';
+import type { ChildCalls, ChildContract, ResumeChildCalls } from './children/index.js';
+import type { BusinessEvent } from './observation.js';
+import type { InvocationOutputWriter } from './output.js';
+export interface Work<Input, Resources extends object> {
+    readonly input: Stable<Input>;
+    readonly resources: Readonly<Resources>;
+    readonly signal: AbortSignal;
+    observation(event: BusinessEvent): void;
+}
+export interface CompositeWork<Allowed extends ChildContract = ChildContract, Restoring extends boolean = false> {
+    readonly children: Restoring extends true ? ResumeChildCalls<Allowed> : ChildCalls<Allowed>;
+}
+export type OutputWork<Delta> = [Delta] extends [never] ? object : {
+    readonly output: InvocationOutputWriter<Delta>;
+};

package/dist/work.js

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

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@weiliang0121/capix-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "description": "Shared contracts, stable data values, and runtime errors for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "packages/contracts"
+  },
+  "engines": {
+    "node": ">=22.23.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/test/run.mjs --package ."
+  }
 }