@weiliang0121/capix-runtime 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @weiliang0121/capix-runtime
 
-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.
+Structure binding, resource assembly, and Runner for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-runtime
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-runtime`
+- `@weiliang0121/capix-runtime/construction`
+- `@weiliang0121/capix-runtime/recording`
+
+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/binding/access.d.ts

@@ -0,0 +1,24 @@
+import type { CallableContext, Invocation } from '@weiliang0121/capix-invocation';
+import type { ChildContract } from '@weiliang0121/capix-contracts';
+import type { ResourceRequirements } from '@weiliang0121/capix-resources';
+import type { ChildBindingsBuilder } from './children/builder.js';
+import type { InvocationChildReferences } from './children/references.js';
+export type AccessPhase = 'run' | `checkpoint:${string}`;
+export declare class InvocationAccess<Input, Output, Context extends CallableContext<Input, Output>> {
+    #private;
+    private readonly invocation;
+    private readonly childBindingsBuilder;
+    readonly references: InvocationChildReferences;
+    constructor(invocation: Invocation<Input, Output, Context>, childBindingsBuilder: ChildBindingsBuilder);
+    enter(phase: AccessPhase, deps: ResourceRequirements, uses?: readonly ChildContract[]): {
+        base: Readonly<{
+            input: import("@weiliang0121/capix-contracts").Stable<Input>;
+            resources: object;
+            signal: AbortSignal;
+            observation: (event: import("@weiliang0121/capix-invocation").BusinessEvent) => void;
+        }>;
+        children: import("@weiliang0121/capix-contracts").ChildCalls<ChildContract> | import("@weiliang0121/capix-contracts").ResumeChildCalls<ChildContract>;
+        validate: () => void;
+        close: () => void;
+    };
+}

package/dist/binding/access.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 InvocationAccess{static{__name(this,"InvocationAccess")}invocation;childBindingsBuilder;references;#resources;constructor(invocation,childBindingsBuilder){this.invocation=invocation,this.childBindingsBuilder=childBindingsBuilder,this.#resources=invocation.context.resources,this.references=childBindingsBuilder.references(invocation)}enter(phase,deps,uses){const resourcePhase=phase;this.#resources.activate(resourcePhase,deps);const context=this.invocation.context,round=context.progress.round;let open=!0;const validate=__name(()=>{try{if(this.invocation.requireActive(),!open)throw new Error("Work access window is closed");if(context.progress.round!==round)throw new Error("Work belongs to an inactive declaration round");if(context.progress.phase!=="execute")throw new Error("Work belongs to an inactive declaration phase")}catch(error){throw this.invocation.reject(error),error}},"validate"),children=this.childBindingsBuilder.build(this.invocation,{uses,validate,references:this.references,restoring:phase.startsWith("checkpoint:")}),base={input:context.currentInput,resources:this.#resources.view(deps,resourcePhase),signal:context.signal,observation:__name(event=>{validate(),this.invocation.observeBusiness(event)},"observation")},close=__name(()=>{open=!1,this.#resources.close(resourcePhase)},"close");return{base:Object.freeze(base),children,validate,close}}}export{InvocationAccess};

package/dist/binding/callable.d.ts

@@ -0,0 +1,14 @@
+import type { InvocationCapabilities } from '../construction/capabilities.js';
+import { type ResolvedCallable, type AnyCallable } from './declarations.js';
+import { type CallInstallation, type CallableCallsOptions } from './calls.js';
+import type { Resources } from '../resource/resources.js';
+import type { Interactions } from '@weiliang0121/capix-interaction';
+export interface CallableBuildPlan<Structure extends AnyCallable, Options> {
+    readonly root: ResolvedCallable<Structure>;
+    readonly calls: CallInstallation<Options>;
+}
+export declare class CallableBinder {
+    private readonly capabilities;
+    constructor(capabilities?: InvocationCapabilities);
+    bind<Structure extends AnyCallable, Options extends object>(structure: Structure, resources: Resources<Options>, interactions?: Interactions, options?: CallableCallsOptions<Options>): CallableBuildPlan<Structure, Options>;
+}

package/dist/binding/callable.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{collectObservationProvides}from"./resources.js";import{resolveDeclaration}from"./declarations.js";import{CallableCalls}from"./calls.js";import{bindCallableHooks}from"./hooks.js";import{ResourceInstallation}from"../resource/installation.js";class CallableBinder{static{__name(this,"CallableBinder")}capabilities;constructor(capabilities={}){this.capabilities=capabilities}bind(structure,resources,interactions,options={}){const plan=resources.snapshot(structure),root=resolveDeclaration(structure,{observationProvides:collectObservationProvides(this.capabilities.observations),observations:this.capabilities.observations,childResources:plan.refinements,resourceScopes:new Map(plan.scopes.map(scope=>[scope.structure,scope.registrations.map(entry=>entry.offer)]))}),supply=new ResourceInstallation(root,plan,interactions),hooks=bindCallableHooks(root,options.hooks??[]);return Object.freeze({root,calls:new CallableCalls(supply,hooks,options.validate?.bind(options))})}}export{CallableBinder};

package/dist/binding/calls.d.ts

@@ -0,0 +1,41 @@
+import type { InvocationOutputReceiver } from '@weiliang0121/capix-contracts';
+import type { ResourceInstallation } from '../resource/installation.js';
+import type { ResourceSupply } from '@weiliang0121/capix-resources';
+import type { ProgressReceiver } from '@weiliang0121/capix-changes';
+import { type InvocationProgress } from '@weiliang0121/capix-invocation';
+import type { CallableInvocationStarted } from '../construction/invocation.js';
+import type { AnyCallable } from './declarations.js';
+import type { CallableHooks, CallableHookBinding } from './hooks.js';
+import { type CallableFeedback, type CallableFeedbackBinding } from '../construction/feedback.js';
+export interface PreparedCall {
+    readonly supply?: ResourceSupply;
+    readonly started?: CallableInvocationStarted<any, any, any>;
+    readonly progress?: ProgressReceiver<InvocationProgress>;
+    readonly output?: InvocationOutputReceiver<any, any>;
+}
+export interface CallInstallation<Options> {
+    begin(options: Options, feedback?: CallableFeedback): CallableCallScope<Options>;
+    require(value: object | undefined): CallableCallScope<Options>;
+    prepare(structure: AnyCallable, input: unknown, options: Options, restoring: boolean, inherited?: ResourceSupply, signal?: AbortSignal): PreparedCall;
+}
+export interface CallableCallsOptions<Options> {
+    readonly hooks?: readonly CallableHookBinding<Options>[];
+    readonly validate?: (options: Options) => undefined;
+}
+export declare class CallableCallScope<Options = unknown> {
+    private readonly owner;
+    private readonly options;
+    readonly feedback?: CallableFeedbackBinding;
+    constructor(owner: CallInstallation<Options>, options: Options, feedback?: CallableFeedback);
+    belongsTo(owner: CallInstallation<Options>): boolean;
+    prepare(structure: AnyCallable, input: unknown, restoring: boolean, inherited?: ResourceSupply, signal?: AbortSignal): PreparedCall;
+}
+export declare class CallableCalls<Options> implements CallInstallation<Options> {
+    private readonly resources;
+    private readonly hooks;
+    private readonly validate?;
+    constructor(resources: ResourceInstallation<Options>, hooks: CallableHooks<Options>, validate?: ((options: Options) => undefined) | undefined);
+    begin(options: Options, feedback?: CallableFeedback): CallableCallScope<Options>;
+    require(value: object | undefined): CallableCallScope<Options>;
+    prepare(structure: AnyCallable, input: unknown, options: Options, restoring: boolean, inherited?: ResourceSupply, signal?: AbortSignal): PreparedCall;
+}

package/dist/binding/calls.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{requireNotCancelled}from"@weiliang0121/capix-invocation";import{bindCallableFeedback}from"../construction/feedback.js";class CallableCallScope{static{__name(this,"CallableCallScope")}owner;options;feedback;constructor(owner,options,feedback){this.owner=owner,this.options=options,this.feedback=feedback?bindCallableFeedback(feedback):void 0,Object.freeze(this)}belongsTo(owner){return this.owner===owner}prepare(structure,input,restoring,inherited,signal){return this.owner.prepare(structure,input,this.options,restoring,inherited,signal)}}class CallableCalls{static{__name(this,"CallableCalls")}resources;hooks;validate;constructor(resources,hooks,validate){this.resources=resources,this.hooks=hooks,this.validate=validate}begin(options,feedback){const result=this.validate?.(options);if(result!==void 0)throw Promise.resolve(result).catch(()=>{}),new TypeError("Runner validation must return undefined synchronously");return new CallableCallScope(this,options,feedback)}require(value){if(!(value instanceof CallableCallScope)||!value.belongsTo(this))throw new Error("Call construction belongs to another binding installation");return value}prepare(structure,input,options,restoring,inherited,signal){signal&&requireNotCancelled(signal),this.hooks.validate(structure,input,options),signal&&requireNotCancelled(signal);const supply=this.resources.open(structure,input,options,inherited);return signal&&requireNotCancelled(signal),{supply,...this.hooks.open(structure,input,options,restoring,signal)}}}export{CallableCallScope,CallableCalls};

package/dist/binding/checkpoint-list.d.ts

@@ -0,0 +1 @@
+export declare function checkpointList<Value>(length: () => number, read: (index: number) => Value, validate: () => void): readonly Value[];

package/dist/binding/checkpoint-list.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 checkpointList(length,read,validate){const index=__name(key=>{if(typeof key!="string"||!/^(0|[1-9]\d*)$/.test(key))return;const value=Number(key);return Number.isSafeInteger(value)&&value<4294967295?value:void 0},"index"),reject=__name(()=>{throw validate(),new TypeError("Checkpoint reference queries are read-only")},"reject");return new Proxy([],{get(target,key,receiver){if(validate(),key==="length")return length();const position=index(key);return position!==void 0?position<length()?read(position):void 0:Reflect.get(target,key,receiver)},has(target,key){validate();const position=index(key);return position===void 0?Reflect.has(target,key):position<length()},ownKeys(){return validate(),[...Array.from({length:length()},(_,position)=>String(position)),"length"]},getOwnPropertyDescriptor(target,key){if(validate(),key==="length")return{...Reflect.getOwnPropertyDescriptor(target,key),value:length()};const position=index(key);return position===void 0?Reflect.getOwnPropertyDescriptor(target,key):position<length()?{configurable:!0,enumerable:!0,writable:!1,value:read(position)}:void 0},set:reject,deleteProperty:reject,defineProperty:reject,setPrototypeOf:reject,preventExtensions:reject})}__name(checkpointList,"checkpointList");export{checkpointList};

package/dist/binding/checkpoint.d.ts

@@ -0,0 +1,9 @@
+import type { CheckpointReferences } from '@weiliang0121/capix-checkpoint';
+import { type DecodedCheckpointFrame } from '@weiliang0121/capix-invocation';
+import type { CheckpointFacts } from '@weiliang0121/capix-contracts';
+import type { BoundChildren } from './children/bound.js';
+import { BoundReceptions } from './receptions.js';
+export declare function savedCheckpointFacts(frame: DecodedCheckpointFrame, references: CheckpointReferences, children: BoundChildren, receptions?: BoundReceptions): {
+    readonly facts: CheckpointFacts<unknown>;
+    close(): void;
+};

package/dist/binding/checkpoint.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{decodeCheckpointDiagnostic}from"@weiliang0121/capix-invocation";import{BoundReceptions}from"./receptions.js";import{checkpointList}from"./checkpoint-list.js";function savedCheckpointFacts(frame,references,children,receptions=new BoundReceptions([],children)){let active=!0;const requireOpen=__name(()=>{if(!active)throw new Error("Saved fact queries are only valid during the synchronous checkpoint check")},"requireOpen");let fallback;const lookup=__name(id=>(requireOpen(),frame.child?frame.child(id):(fallback??=new Map(frame.children.map(child=>[child.identity.contextId,child])),fallback.get(id))),"lookup"),entries=new WeakMap,byId=new Map,materialize=__name(saved=>{requireOpen();const existing=byId.get(saved.identity.contextId);if(existing)return existing;const definition=children.at(saved.target.position),ref=Object.freeze({}),state=saved.state,returned=state.kind==="waiting"?void 0:state.kind==="returned"?Object.freeze({status:"succeeded",output:state.output}):Object.freeze({status:"failed",diagnostic:decodeCheckpointDiagnostic(state.error),failure:state.failure}),reception=state.kind==="failed"&&state.reception?Object.freeze({status:"handled",value:state.reception.output}):state.kind!=="returned"?Object.freeze({status:"pending"}):state.reception.kind==="accepted"?Object.freeze({status:"accepted",value:state.reception.output}):state.reception.kind==="failed"?Object.freeze({status:"failed",diagnostic:decodeCheckpointDiagnostic(state.reception.error),failure:state.reception.failure}):Object.freeze({status:state.reception.kind}),fact=Object.freeze({ref,...saved.key!==void 0?{key:saved.key}:{},parentRound:round(saved.round),order:saved.order,input:saved.input,returned,reception,...state.kind!=="waiting"?{progress:Object.freeze({...state.progress,round:round(state.progress.round)})}:{}}),entry=Object.freeze({saved,ref,definition,fact});return entries.set(ref,entry),byId.set(saved.identity.contextId,entry),entry},"materialize"),requireEntry=__name(ref=>{requireOpen();const entry=ref&&typeof ref=="object"?entries.get(ref):void 0;if(!entry)throw new Error("Unknown or foreign saved child reference");return entry},"requireEntry"),selected=__name(wire=>{const saved=lookup(wire.contextId),entry=saved?materialize(saved):void 0;if(!entry||!saved||wire.parentContextId!==frame.owner.contextId||wire.parentRound!==saved.round||wire.order!==saved.order||wire.target.position!==saved.target.position)throw new Error("Saved child reference differs from the checked frame");return entry},"selected"),facts=Object.freeze({get:__name(ref=>requireEntry(ref).fact,"get"),accepted:__name((ref,contract)=>{const entry=requireEntry(ref),binding=receptions.require(contract,entry.definition),state=entry.saved.state;if(state.kind!=="returned"||state.reception.kind!=="accepted"||state.reception.contract?.position!==binding.position)throw new Error("Saved child has no accepted value under this reception contract");return state.reception.output},"accepted"),handled:__name((ref,contract)=>{const entry=requireEntry(ref),binding=receptions.require(contract,entry.definition),state=entry.saved.state;if(state.kind!=="failed"||state.reception?.kind!=="handled"||state.reception.contract?.position!==binding.position)throw new Error("Saved child has no handled value under this reception contract");return state.reception.output},"handled"),require:__name((definition,ref)=>{const entry=requireEntry(ref);if(entry.definition!==definition)throw new Error("Saved child reference belongs to a different declaration");return entry.fact},"require"),list:__name((definition,query)=>(requireOpen(),Object.freeze(frame.children.map(materialize).filter(entry=>entry.definition===definition&&(query?.parentRound===void 0||entry.saved.round===query.parentRound)).map(entry=>entry.fact))),"list"),requireUnique:__name((definition,query)=>{const matches=facts.list(definition,query);if(matches.length!==1)throw new Error("Expected exactly one saved direct child fact");return matches[0]},"requireUnique"),values:__name(()=>(requireOpen(),Object.freeze(frame.children.map(saved=>materialize(saved).fact))),"values")}),slots={};for(const[key,value]of Object.entries(references)){const list=Array.isArray(value)?checkpointList(()=>value.length,index=>selected(value[index]).fact,requireOpen):void 0;Object.defineProperty(slots,key,{enumerable:!0,get(){return requireOpen(),list??selected(value).fact}})}Object.freeze(slots);let continuation;if(frame.continuation){const{origin,...accepted}=frame.continuation;continuation=Object.freeze({...accepted,...origin?{origin:origin.kind==="self"?origin:Object.freeze({kind:origin.kind,child:selected(origin.child).ref})}:{}})}return Object.freeze({facts:Object.freeze({initialInput:frame.input,input:frame.currentInput,round:round(frame.round),...continuation?{continuation}:{},references:slots,children:facts}),close(){active=!1}})}__name(savedCheckpointFacts,"savedCheckpointFacts");function round(value){if(value!==1&&value!==2)throw new Error("Invalid saved invocation round");return value}__name(round,"round");export{savedCheckpointFacts};

package/dist/binding/children/binding.d.ts

@@ -0,0 +1,34 @@
+import type { ChildCalls, ChildContract, ResumeChildCalls } from '@weiliang0121/capix-contracts';
+import { type Invocation } from '@weiliang0121/capix-invocation';
+import type { BoundChildren } from './bound.js';
+import type { InvocationChildReferences } from './references.js';
+import type { BoundReceptions } from '../receptions.js';
+export type ChildBindingsParent = Invocation<any, any, any>;
+interface ChildAccessOptions {
+    readonly children: BoundChildren;
+    readonly names?: ReadonlyMap<string, ChildContract>;
+    readonly receptions: BoundReceptions;
+    readonly parent: ChildBindingsParent;
+    readonly allowed: ReadonlySet<ChildContract>;
+    readonly validate: () => void;
+    readonly references: InvocationChildReferences;
+    readonly restoring: boolean;
+}
+export declare class InvocationChildBindings {
+    private readonly options;
+    readonly port: ChildCalls | ResumeChildCalls;
+    constructor(options: ChildAccessOptions);
+    private invoke;
+    private bindReception;
+    private receiveTarget;
+    private create;
+    private open;
+    private resume;
+    private handle;
+    private requireAllowed;
+    private checkActive;
+    private guard;
+    private perform;
+    private deliver;
+}
+export {};

package/dist/binding/children/binding.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{createCallableInvocation,restoreCallableInvocation}from"../../construction/calls.js";import{InvocationCancelled,ChildCallFailure,combineOutputReceivers}from"@weiliang0121/capix-invocation";class InvocationChildBindings{static{__name(this,"InvocationChildBindings")}options;port;constructor(options){this.options=options,this.port=Object.freeze({...Object.fromEntries([...options.names??[]].filter(([,definition])=>options.allowed.has(definition)).map(([name,definition])=>[name,Object.freeze({invoke:__name((input,reception)=>this.invoke(definition,input,reception??{}),"invoke")})])),invoke:this.invoke.bind(this),create:this.create.bind(this),open:this.open.bind(this),facts:options.references.facts,...options.restoring?{resume:this.resume.bind(this)}:{}})}invoke(definition,input,options={}){return this.perform(()=>this.options.parent.children.accepting(async()=>{if(this.requireAllowed(definition),options.delta!==void 0&&typeof options.delta!="function")throw new TypeError("Delta receiver must be a function");const{succeeded,failed,contract}=this.bindReception(definition,options),delta=options.delta?.bind(options),output=options.output,outputReceive=output?.receive.bind(output),outputFailed=output?.failed?.bind(output),outputReceiver=combineOutputReceivers(delta?{receive:__name(event=>{if(event.kind!=="delta")return;const returned=delta(event.delta);if(returned!==void 0)throw Promise.resolve(returned).catch(()=>{}),new TypeError("Delta receivers must return undefined synchronously")},"receive")}:void 0,outputReceive?{receive:outputReceive,failed:outputFailed}:void 0),child=createCallableInvocation(this.options.children.get(definition),this.options.parent,input,{key:options.key,declarationPosition:this.options.children.position(definition),receiveFailure:!!failed,...outputReceiver?{output:outputReceiver}:{}}),relation=this.options.parent.children.get(child);return this.receiveTarget(relation,succeeded,failed,contract)}))}bindReception(definition,options){const receiver=options.result;if(receiver?.succeeded!==void 0&&typeof receiver.succeeded!="function")throw new TypeError("Success receiver must be a function");if(receiver?.failed!==void 0&&typeof receiver.failed!="function")throw new TypeError("Failure receiver must be a function");const contract=options.reception?this.options.receptions.require(options.reception,definition):void 0;return{succeeded:receiver?.succeeded?.bind(receiver),failed:receiver?.failed?.bind(receiver),contract}}async receiveTarget(relation,succeeded,failed,contract){const child=relation.invocation;try{await child.run()}catch(error){try{this.options.parent.requireActive(),this.checkActive()}catch(windowFailure){const sourceFailure=relation.returned?.status==="failed"?relation.returned.error:error;throw sourceFailure===windowFailure||sourceFailure instanceof InvocationCancelled&&windowFailure instanceof InvocationCancelled?windowFailure:new AggregateError([sourceFailure,windowFailure],"Child operation failed after its reception window became unavailable",{cause:sourceFailure})}if(!failed||relation.returned?.status!=="failed"||!relation.returned.failure?.receptionAllowed||relation.returned.error instanceof InvocationCancelled||child.context.progress.round===0||["setup","control","observation"].includes(relation.returned.failure?.phase??"setup"))throw error;return relation.handle(failure=>(this.checkActive(),failed(failure)),contract)}return relation.accept(output=>(this.checkActive(),succeeded?succeeded(output):output),contract)}create(definition,input,options={}){return this.guard(()=>{this.requireAllowed(definition);const child=createCallableInvocation(this.options.children.get(definition),this.options.parent,input,{...options,declarationPosition:this.options.children.position(definition)});return this.handle(this.options.references.forTarget(definition,child))})}open(ref){return this.guard(()=>this.handle(ref))}resume(ref){return this.guard(()=>{if(!this.options.restoring)throw new Error("Child resume is available only in a checkpoint resume phase");const entry=this.options.references.require(ref);this.requireAllowed(entry.definition);const position=this.options.children.position(entry.definition),contextId=entry.relation.invocation.context.id;return this.options.parent.restoreChild(position,contextId,()=>restoreCallableInvocation(this.options.children.get(entry.definition),this.options.parent,contextId,{declarationPosition:position})),this.handle(ref)})}handle(ref){const entry=this.options.references.require(ref),relation=entry.relation,access=this;function accept(first,receive){return access.perform(()=>{if(first!==void 0&&typeof first!="function"&&(typeof first!="object"||first===null))throw new Error("Invalid child reception contract or callback");const contract=typeof first=="object"&&first!==null?access.options.receptions.require(first,entry.definition):void 0,callback=typeof first=="function"?first:receive;if(contract&&typeof callback!="function")throw new Error("Typed reception requires a callback");return relation.accept(output=>(access.checkActive(),callback?callback(output):output),contract)})}return __name(accept,"accept"),Object.freeze({ref,...relation.key!==void 0?{key:relation.key}:{},run:__name(()=>this.perform(async()=>(relation.returned||this.requireAllowed(entry.definition),await relation.invocation.run())),"run"),invoke:__name((options={})=>this.perform(()=>this.options.parent.children.accepting(async()=>{relation.returned||this.requireAllowed(entry.definition);const{succeeded,failed,contract}=this.bindReception(entry.definition,options);return failed&&!relation.returned&&relation.receiveFailures(),this.receiveTarget(relation,succeeded,failed,contract)})),"invoke"),accept})}requireAllowed(definition){if(!this.options.allowed.has(definition))throw new Error("Child definition is not declared in this phase uses")}checkActive(){this.options.parent.requireHealthy(),this.options.validate(),this.options.parent.context.requireActive()}guard(action){try{return this.checkActive(),action()}catch(error){throw this.options.parent.reject(error),error}}perform(action){const delivery=this.deliver(action);return delivery.catch(()=>{}),delivery}async deliver(action){try{return this.checkActive(),await action()}catch(error){throw error instanceof ChildCallFailure||this.options.parent.reject(error),error}}}export{InvocationChildBindings};

package/dist/binding/children/bound.d.ts

@@ -0,0 +1,19 @@
+import type { ChildCallable, NamedMembers } from '@weiliang0121/capix-structure';
+import type { ChildContract } from '@weiliang0121/capix-contracts';
+import type { CheckpointBinding } from '@weiliang0121/capix-invocation';
+import type { ResolvedChild } from '../declarations.js';
+export declare class BoundChildren {
+    #private;
+    constructor(children: readonly ResolvedChild[], names?: NamedMembers);
+    names(): ReadonlyMap<string, ChildContract>;
+    definitions(): readonly ChildCallable[];
+    position(definition: ChildContract): number;
+    at(position: number): ChildCallable;
+    checkpointLayout(): readonly Readonly<{
+        kind: "group" | "node";
+        binding: CheckpointBinding | undefined;
+    }>[];
+    get<Definition extends ChildContract>(definition: Definition): ChildCallable;
+    checkpoint(definition: ChildContract): CheckpointBinding | undefined;
+    checkUses(definitions: readonly ChildContract[]): void;
+}

package/dist/binding/children/bound.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{checkMemberName}from"@weiliang0121/capix-structure/construction";class BoundChildren{static{__name(this,"BoundChildren")}#entries;#definitions;#names;constructor(children,names={}){this.#entries=new Map(children.map(child=>[child.definition,{kind:child.declaration.kind,value:child.definition,checkpoint:child.declaration.checkpoint}])),this.#definitions=Object.freeze([...new Set(children.map(child=>child.definition))]);for(const[name,definition]of Object.entries(names))if(checkMemberName(name),!this.#entries.has(definition))throw new Error("Named member is outside its owner");this.#names=new Map(Object.entries(names))}names(){return this.#names}definitions(){return this.#definitions}position(definition){const position=this.#definitions.findIndex(candidate=>candidate===definition);if(position<0)throw new Error("Child definition is not declared in this binding");return position}at(position){const definition=this.#definitions[position];if(!Number.isSafeInteger(position)||!definition)throw new Error("Child declaration position is not registered");return definition}checkpointLayout(){return Object.freeze([...this.#entries.values()].map(entry=>Object.freeze({kind:entry.kind,binding:entry.checkpoint})))}get(definition){const entry=this.#entries.get(definition);if(!entry)throw new Error("Child definition is not declared in this binding");return entry.value}checkpoint(definition){const entry=this.#entries.get(definition);if(!entry)throw new Error("Child definition is not declared in this binding");return entry.checkpoint}checkUses(definitions){for(const definition of definitions)if(!this.#entries.has(definition))throw new Error("Declaration uses a child outside its owner")}}export{BoundChildren};

package/dist/binding/children/builder.d.ts

@@ -0,0 +1,18 @@
+import type { ChildCalls, ChildContract, ResumeChildCalls } from '@weiliang0121/capix-contracts';
+import type { BoundChildren } from './bound.js';
+import { type ChildBindingsParent } from './binding.js';
+import { InvocationChildReferences } from './references.js';
+import { BoundReceptions } from '../receptions.js';
+export interface ChildBindingsBuildOptions {
+    readonly uses?: readonly ChildContract[];
+    readonly validate: () => void;
+    readonly references: InvocationChildReferences;
+    readonly restoring?: boolean;
+}
+export declare class ChildBindingsBuilder {
+    readonly children: BoundChildren;
+    readonly receptions: BoundReceptions;
+    constructor(children: BoundChildren, receptions?: BoundReceptions);
+    references(parent: ChildBindingsParent): InvocationChildReferences;
+    build(parent: ChildBindingsParent, options: ChildBindingsBuildOptions): ChildCalls | ResumeChildCalls;
+}

package/dist/binding/children/builder.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{InvocationChildBindings}from"./binding.js";import{InvocationChildReferences}from"./references.js";import{BoundReceptions}from"../receptions.js";class ChildBindingsBuilder{static{__name(this,"ChildBindingsBuilder")}children;receptions;constructor(children,receptions=new BoundReceptions([],children)){this.children=children,this.receptions=receptions}references(parent){return new InvocationChildReferences(parent,this.children,this.receptions)}build(parent,options){try{const definitions=options.uses??this.children.definitions();return this.children.checkUses(definitions),new InvocationChildBindings({children:this.children,names:this.children.names(),receptions:this.receptions,parent,allowed:new Set(definitions),validate:options.validate,references:options.references,restoring:options.restoring??!1}).port}catch(error){throw parent.reject(error),error}}}export{ChildBindingsBuilder};

package/dist/binding/children/references.d.ts

@@ -0,0 +1,29 @@
+import type { ChildContract, ChildReference, ChildFacts, ExceptionOrigin, ContinuationFact } from '@weiliang0121/capix-contracts';
+import { type Invocation, type InvocationRelation, type InvocationTarget, type InvocationExceptionOrigin, type CheckpointContinuationFact } from '@weiliang0121/capix-invocation';
+import type { CheckpointReference } from '@weiliang0121/capix-checkpoint';
+import type { BoundChildren } from './bound.js';
+import type { BoundReceptions } from '../receptions.js';
+interface ReferenceEntry {
+    readonly definition: ChildContract;
+    readonly relation: InvocationRelation;
+    readonly ref: ChildReference;
+}
+export declare class InvocationChildReferences {
+    #private;
+    private readonly parent;
+    private readonly children;
+    private readonly receptions;
+    readonly facts: ChildFacts;
+    constructor(parent: Invocation<any, any, any>, children: BoundChildren, receptions: BoundReceptions);
+    forTarget<D extends ChildContract>(definition: D, target: InvocationTarget): ChildReference<D>;
+    require(ref: ChildReference): ReferenceEntry;
+    fromSaved(value: CheckpointReference): ChildReference;
+    encode(ref: ChildReference): CheckpointReference;
+    origin(origin: InvocationExceptionOrigin): ExceptionOrigin;
+    continuation(value: CheckpointContinuationFact | undefined): ContinuationFact | undefined;
+    private values;
+    private entry;
+    private fact;
+    private reject;
+}
+export {};

package/dist/binding/children/references.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{failureFact,failureDiagnostic,isInvocationCancelled}from"@weiliang0121/capix-invocation";class InvocationChildReferences{static{__name(this,"InvocationChildReferences")}parent;children;receptions;#entries=new WeakMap;#relations=new Map;facts;constructor(parent,children,receptions){this.parent=parent,this.children=children,this.receptions=receptions,this.facts=Object.freeze({get:__name(ref=>this.fact(this.require(ref)),"get"),accepted:__name((ref,contract)=>{try{const entry=this.require(ref),binding=this.receptions.require(contract,entry.definition),reception=entry.relation.reception;if(reception.status!=="accepted"||reception.contract!==binding)throw new Error("Child has no accepted value under this reception contract");return reception.output}catch(error){throw this.parent.reject(error),error}},"accepted"),handled:__name((ref,contract)=>{try{const entry=this.require(ref),binding=this.receptions.require(contract,entry.definition),reception=entry.relation.reception;if(reception.status!=="handled"||reception.contract!==binding)throw new Error("Child has no handled value under this reception contract");return reception.output}catch(error){throw this.parent.reject(error),error}},"handled"),require:__name((definition,ref)=>{const entry=this.require(ref);return entry.definition!==definition?this.reject(new Error("Child reference belongs to a different declaration")):this.fact(entry)},"require"),list:__name((definition,query)=>Object.freeze(this.values().filter(entry=>entry.definition===definition&&(query?.parentRound===void 0||entry.relation.round===query.parentRound)).map(entry=>this.fact(entry))),"list"),requireUnique:__name((definition,query)=>{const matches=this.facts.list(definition,query);return matches.length!==1?this.reject(new Error("Expected exactly one direct child fact")):matches[0]},"requireUnique"),values:__name(()=>Object.freeze(this.values().map(entry=>this.fact(entry))),"values")})}forTarget(definition,target){const relation=this.parent.children.get(target),entry=this.entry(relation);return entry.definition!==definition?this.reject(new Error("Child declaration position differs from its binding")):entry.ref}require(ref){const entry=ref&&typeof ref=="object"?this.#entries.get(ref):void 0;return entry||this.reject(new Error("Unknown or foreign child reference"))}fromSaved(value){const relation=this.parent.children.byContextId(value.contextId);return!relation||value.parentContextId!==this.parent.context.id||relation.round!==value.parentRound||relation.order!==value.order||relation.declarationPosition!==value.target.position?this.reject(new Error("Saved child reference does not match the installed relationship")):this.entry(relation).ref}encode(ref){const entry=this.require(ref),relation=entry.relation;return Object.freeze({contextId:relation.invocation.context.id,parentContextId:this.parent.context.id,parentRound:relation.round,order:relation.order,target:Object.freeze({position:this.children.position(entry.definition)})})}origin(origin){if(origin.kind==="self")return origin;const identity=origin.child,relation=this.parent.children.values().find(item=>item.invocation.context.id===identity.childContextId);return!relation||identity.parentContextId!==this.parent.context.id||identity.parentRound!==relation.round||identity.order!==relation.order?this.reject(new Error("Exception source is not an exact direct child relationship")):Object.freeze({kind:origin.kind,child:this.entry(relation).ref})}continuation(value){return value?Object.freeze({fromRound:value.fromRound,stage:value.stage,reason:value.reason,...value.origin?{origin:this.origin(value.origin)}:{}}):void 0}values(){return this.parent.children.values().map(relation=>this.entry(relation))}entry(relation){const existing=this.#relations.get(relation);if(existing)return existing;const position=relation.declarationPosition;if(position===void 0)return this.reject(new Error("Direct child has no registered declaration position"));const definition=this.children.at(position),ref=Object.freeze({}),entry=Object.freeze({definition,relation,ref});return this.#relations.set(relation,entry),this.#entries.set(ref,entry),entry}fact(entry){const relation=entry.relation,context=relation.invocation.context,returned=relation.returned,signal="signal"in context?context.signal:void 0,result=returned?.status==="succeeded"?Object.freeze({status:"succeeded",output:returned.output}):returned?signal instanceof AbortSignal&&isInvocationCancelled(returned.error,signal)?Object.freeze({status:"cancelled",diagnostic:returned.diagnostic??failureDiagnostic(returned.error)}):Object.freeze({status:"failed",diagnostic:returned.diagnostic??failureDiagnostic(returned.error),...returned.failure?{failure:Object.freeze(failureFact(returned.failure))}:{}}):void 0,reception=relation.reception,received=reception.status==="accepted"||reception.status==="handled"?Object.freeze({status:reception.status,value:reception.output}):reception.status==="failed"?Object.freeze({status:"failed",diagnostic:reception.diagnostic??failureDiagnostic(reception.error),...reception.failure?{failure:Object.freeze(failureFact(reception.failure))}:{}}):Object.freeze({status:reception.status});return Object.freeze({ref:entry.ref,...relation.key?{key:relation.key}:{},parentRound:relation.round,order:relation.order,input:context.input,returned:result,reception:received,...context.progress.round?{progress:Object.freeze({round:context.progress.round,currentInput:context.currentInput,phase:context.progress.phase})}:{}})}reject(error){throw this.parent.reject(error),error}}export{InvocationChildReferences};

package/dist/binding/contract.d.ts

@@ -0,0 +1,27 @@
+import type { CallableContext, InvocationWork } from '@weiliang0121/capix-invocation';
+import type { ResourceRequirements, ResourceRefinement, ResourceIdentity } from '@weiliang0121/capix-resources';
+import type { BoundChildren } from './children/bound.js';
+import type { ObservationInstallation } from './observation.js';
+import type { InvocationObservationDeclaration } from './observation.js';
+import type { ChildResourceBinding } from './resources.js';
+import type { AnyCallable } from './declarations.js';
+import type { CallableSnapshot } from './snapshot.js';
+import type { ChildCallable } from '@weiliang0121/capix-structure';
+export interface ChildBindingOptions {
+    readonly observationProvides?: ResourceRequirements;
+    readonly observations?: readonly ObservationInstallation[];
+    readonly childResources?: readonly ChildResourceBinding[];
+    readonly sources?: readonly ChildCallable[];
+    readonly resourceScopes?: ReadonlyMap<AnyCallable, readonly ResourceIdentity[]>;
+}
+export interface CallableBinding<Input, Output, Resources extends object> {
+    readonly definition: AnyCallable;
+    readonly declaration: CallableSnapshot;
+    readonly children: BoundChildren;
+    readonly composite: boolean;
+    readonly deps: ResourceRequirements<Resources>;
+    readonly supply: ResourceRequirements;
+    readonly refinements?: readonly ResourceRefinement<Input>[];
+    readonly work: InvocationWork<Input, Output, CallableContext<Input, Output, Resources>>;
+    readonly observations: readonly InvocationObservationDeclaration[];
+}

package/dist/binding/contract.js

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

package/dist/binding/declarations.d.ts

@@ -0,0 +1,18 @@
+import type { ChildCallable, CallableStructure, Composite } from '@weiliang0121/capix-structure';
+import { type ResourceRequirements, type ResourceRefinement } from '@weiliang0121/capix-resources';
+import type { ChildBindingOptions } from './contract.js';
+import { type CallableSnapshot } from './snapshot.js';
+import type { InvocationObservationDeclaration } from './observation.js';
+export type AnyCallable = (CallableStructure<'scene'> & Composite) | ChildCallable;
+export interface ResolvedCallable<Definition extends AnyCallable = AnyCallable> {
+    readonly kind: Definition['kind'];
+    readonly definition: Definition;
+    readonly declaration: CallableSnapshot;
+    readonly observations: readonly InvocationObservationDeclaration[];
+    readonly deps: ResourceRequirements;
+    readonly supply: ResourceRequirements;
+    readonly members: readonly ResolvedChild[];
+    readonly refinements?: readonly ResourceRefinement<any>[];
+}
+export type ResolvedChild = ResolvedCallable<ChildCallable>;
+export declare function resolveDeclaration<Definition extends AnyCallable>(definition: Definition, options?: ChildBindingOptions): ResolvedCallable<Definition>;

package/dist/binding/declarations.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{resourceRequests,isResourceRefinement}from"@weiliang0121/capix-resources";import{collectDefinitionRequirements,collectResourceSupply}from"./resources.js";import{childKinds}from"@weiliang0121/capix-structure/construction";import{originalReception,snapshotDefinition,snapshotObservation}from"./snapshot.js";function resolveDeclaration(definition,options={}){const refinements=new Map;for(const binding of options.childResources??[]){if(refinements.has(binding.definition))throw new Error("Duplicate child resource binding");refinements.set(binding.definition,Object.freeze([...binding.refinements]))}const captures=new Set(options.sources??[]),encountered=new Set,path=new Set,observations=[],visit=__name((current,parent)=>{if(path.has(current))throw new Error("Cyclic member declaration");const allowed=parent&&childKinds[parent.kind];if(!Object.hasOwn(childKinds,current.kind)||allowed&&!allowed.includes(current.kind))throw new Error("Invalid member definition kind");const declaration=snapshotDefinition(current);observations.push({definition:current,parent:parent?.definition});const selectedObservations=selectObservations(current,options.observations),deps=collectDefinitionRequirements(declaration,options.observationProvides,selectedObservations),declaredMembers="members"in declaration?declaration.members??[]:[];checkCheckpointMembers(declaration,declaredMembers);const selected=refinements.get(current),node={kind:declaration.kind,definition:current,declaration,observations:selectedObservations,deps,refinements:selected};encountered.add(current),path.add(current);const members=declaredMembers.map(member=>visit(member,node));path.delete(current);const supply=collectSubtreeSupply(deps,members,captures,options.resourceScopes);return selected&&checkRefinements(supply,selected),Object.freeze({...node,supply,members:Object.freeze(members)})},"visit"),resolved=visit(definition);for(const binding of options.childResources??[])if(!encountered.has(binding.definition))throw new Error("Resource refinement requires a registered member");for(const target of captures)if(!encountered.has(target))throw new Error("Call source requires a registered member");for(const entry of observations)for(const observation of options.observations??[])observation.check?.(entry.definition,entry.parent);return resolved}__name(resolveDeclaration,"resolveDeclaration");function selectObservations(definition,installations){return Object.freeze((installations??[]).flatMap(installation=>(installation.declarations?.(definition)??[]).map(declaration=>Object.freeze({...snapshotObservation(declaration),installation}))))}__name(selectObservations,"selectObservations");function checkCheckpointMembers(declaration,members){const receptions=new Set;for(const reception of declaration.checkpoint?.receptions??[]){const original=originalReception(reception);if(receptions.has(original))throw new Error("Duplicate parent reception contract");if(receptions.add(original),!members.some(member=>member===reception.child))throw new Error("Reception targets a member outside its owner")}const points=declaration.checkpoint?.points??[],names=new Set;for(const point of points){if(!point.name||names.has(point.name))throw new Error("Checkpoint points need distinct registered names");names.add(point.name);for(const slot of Object.values(point.references))if(!members.some(member=>member===slot.definition))throw new Error("Checkpoint reference targets a member outside its owner")}const checkpointUses=points.flatMap(point=>[...point.resume.uses??[]]);for(const child of checkpointUses)if(!members.some(member=>member===child))throw new Error("Declaration uses a member outside its owner")}__name(checkCheckpointMembers,"checkCheckpointMembers");function collectSubtreeSupply(deps,members,captures,resourceScopes){const inherited=members.filter(member=>!captures.has(member.definition)).map(member=>{const local=new Set(resourceScopes?.get(member.definition)??[]);return Object.fromEntries(Object.entries(member.supply).filter(([,request])=>!local.has(request.offer)))});return collectResourceSupply([deps,...inherited])}__name(collectSubtreeSupply,"collectSubtreeSupply");function checkRefinements(supply,refinements){const offers=new Set(resourceRequests(supply).map(request=>request.offer)),seen=new Set;for(const refinement of refinements){if(!isResourceRefinement(refinement))throw new Error("Resource refinement was not issued by an offer");if(!offers.has(refinement.offer))throw new Error(`Refined resource is not requested: ${refinement.offer.name}`);if(seen.has(refinement.offer))throw new Error(`Duplicate resource refinement: ${refinement.offer.name}`);seen.add(refinement.offer)}}__name(checkRefinements,"checkRefinements");export{resolveDeclaration};

package/dist/binding/hooks.d.ts

@@ -0,0 +1,32 @@
+import type { CallableInput, CallableOutput, CallableDelta, InvocationOutputReceiver } from '@weiliang0121/capix-contracts';
+import type { ProgressReceiver } from '@weiliang0121/capix-changes';
+import { type InvocationProgress } from '@weiliang0121/capix-invocation';
+import type { CallableInvocationStarted } from '../construction/invocation.js';
+import type { AnyCallable, ResolvedCallable } from './declarations.js';
+import type { PreparedCall } from './calls.js';
+export interface CallableHookDeclaration<Structure extends AnyCallable, Options> {
+    readonly validate?: (input: CallableInput<Structure>, options: Options) => undefined;
+    readonly started?: (input: CallableInput<Structure>, options: Options) => CallableInvocationStarted<CallableInput<Structure>, CallableOutput<Structure>> | undefined;
+    readonly progress?: (input: CallableInput<Structure>, options: Options) => ProgressReceiver<InvocationProgress> | undefined;
+    readonly output?: (input: CallableInput<Structure>, options: Options) => InvocationOutputReceiver<CallableOutput<Structure>, CallableDelta<Structure>> | undefined;
+}
+export interface CallableHookBinding<Options = {}, Structure extends AnyCallable = AnyCallable> {
+    readonly structure: Structure;
+    readonly hooks: CallableHookDeclaration<Structure, Options>;
+}
+export declare function callableHooks<Structure extends AnyCallable, Options = {}>(structure: Structure, hooks: CallableHookDeclaration<NoInfer<Structure>, Options>): CallableHookBinding<Options, Structure>;
+type HookAccess = Omit<PreparedCall, 'supply'>;
+interface FixedHooks<Options> {
+    readonly validate?: (input: unknown, options: Options) => undefined;
+    readonly started?: (input: unknown, options: Options) => CallableInvocationStarted<any, any> | undefined;
+    readonly progress?: (input: unknown, options: Options) => ProgressReceiver<InvocationProgress> | undefined;
+    readonly output?: (input: unknown, options: Options) => InvocationOutputReceiver<any, any> | undefined;
+}
+export declare class CallableHooks<Options> {
+    private readonly registrations;
+    constructor(registrations: ReadonlyMap<AnyCallable, FixedHooks<Options>>);
+    validate(structure: AnyCallable, input: unknown, options: Options): void;
+    open(structure: AnyCallable, input: unknown, options: Options, restoring: boolean, signal?: AbortSignal): HookAccess;
+}
+export declare function bindCallableHooks<Options>(root: ResolvedCallable, registrations: readonly CallableHookBinding<Options>[]): CallableHooks<Options>;
+export {};

package/dist/binding/hooks.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{requireNotCancelled}from"@weiliang0121/capix-invocation";function callableHooks(structure,hooks){return Object.freeze({structure,hooks})}__name(callableHooks,"callableHooks");class CallableHooks{static{__name(this,"CallableHooks")}registrations;constructor(registrations){this.registrations=registrations}validate(structure,input,options){const validated=this.registrations.get(structure)?.validate?.(input,options);if(validated!==void 0)throw Promise.resolve(validated).catch(()=>{}),new TypeError("Callable validation must return undefined synchronously")}open(structure,input,options,restoring,signal){const hooks=this.registrations.get(structure);if(!hooks)return{};const started=restoring?void 0:synchronous(hooks.started?.(input,options),"started");if(started!==void 0&&typeof started!="function")throw new TypeError("Callable started factory must return a callback or undefined");signal&&requireNotCancelled(signal);const progress=synchronous(hooks.progress?.(input,options),"progress");signal&&requireNotCancelled(signal);const output=synchronous(hooks.output?.(input,options),"output");return signal&&requireNotCancelled(signal),{started,progress,output}}}function bindCallableHooks(root,registrations){const members=new Set,visit=__name(current=>{members.add(current.definition);for(const child of current.members)visit(child)},"visit");visit(root);const fixed=new Map;for(const registration of registrations){if(!members.has(registration.structure))throw new Error("Call hooks require a structure in this scene");if(fixed.has(registration.structure))throw new Error("Duplicate callable hooks registration");const hooks=registration.hooks;fixed.set(registration.structure,Object.freeze({validate:hooks.validate?.bind(hooks),started:hooks.started?.bind(hooks),progress:hooks.progress?.bind(hooks),output:hooks.output?.bind(hooks)}))}return new CallableHooks(fixed)}__name(bindCallableHooks,"bindCallableHooks");function synchronous(value,hook){if(value!==null&&(typeof value=="object"||typeof value=="function")&&typeof value.then=="function")throw Promise.resolve(value).catch(()=>{}),new TypeError(`Callable ${hook} factory must be synchronous`);return value}__name(synchronous,"synchronous");export{CallableHooks,bindCallableHooks,callableHooks};

package/dist/binding/observation.d.ts

@@ -0,0 +1,27 @@
+import { InvocationResources, type InvocationFact, type InvocationIdentity, type InvocationDescription, type InvocationObserver, InvocationObservation } from '@weiliang0121/capix-invocation';
+import type { ObservationDeclaration, ObservationDeclarationScope } from '../definition/observation.js';
+import { type ResourceRequirements } from '@weiliang0121/capix-resources';
+import type { DriverFact, DriverObserver } from '../observation/driver.js';
+import type { EventConsumer } from '@weiliang0121/capix-changes';
+export interface InvocationObservationDeclaration extends ObservationDeclaration<InvocationFact> {
+    readonly installation?: ObservationInstallation;
+}
+export interface InvocationObservationSetup {
+    readonly identity: InvocationIdentity;
+    readonly description?: InvocationDescription;
+    readonly declarations?: readonly InvocationObservationDeclaration[];
+    readonly resources: InvocationResources;
+}
+export interface ObservationInstallation {
+    declarations?(structure: ObservationDeclarationScope): readonly ObservationDeclaration<InvocationFact>[];
+    check?(definition: ObservationDeclarationScope, parent?: ObservationDeclarationScope): void;
+    readonly failure?: 'isolate' | 'propagate';
+    readonly provides?: ResourceRequirements;
+    bindDriver?(identity: Readonly<{
+        driverId: string;
+    }>): DriverObserver;
+    bindInvocation(setup: InvocationObservationSetup, parent?: InvocationObserver): InvocationObserver;
+    invalidate?(error: unknown): void;
+}
+export declare function bindInvocationObservation(setup: InvocationObservationSetup, installations: readonly ObservationInstallation[] | undefined, parent?: InvocationObservation): InvocationObservation;
+export declare function bindDriverObservation(driverId: string, installations?: readonly ObservationInstallation[]): EventConsumer<DriverFact>;

package/dist/binding/observation.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{InvocationObservation,ObserverSession,publishSessions}from"@weiliang0121/capix-invocation";import{ResourceBinding,resourceRequests}from"@weiliang0121/capix-resources";function bindObservation(declaration,resources){const binding=ResourceBinding.fromSupply(declaration.deps,resources.supply);return fact=>{const access=binding.open();try{return declaration.observe(fact,access.endpoints)}finally{access.close()}}}__name(bindObservation,"bindObservation");function bindInvocationObservation(setup,installations,parent){const sessions=[],installed=new Map;if(!installations)return new InvocationObservation(sessions,installed);for(const installation of installations){const previous=parent?.sessionFor(installation);if(parent&&(!previous||!previous.available()))continue;const observer=installation.bindInvocation(setup,previous?.observer),session=new ObserverSession(observer,installation.failure??"isolate",error=>installation.invalidate?.(error),previous);installed.set(installation,session),sessions.push(session)}const suppliers=[...installed.values()],resources=setup.resources.supplement(suppliers.flatMap(session=>session.observer.resources?[session.observer.resources]:[]));for(const declaration of setup.declarations??[]){const owner=declaration.installation?installed.get(declaration.installation):void 0;if(declaration.installation&&!owner)continue;const requests=resourceRequests(declaration.deps);if(requests.some(request=>!resources.provides(request))&&requests.every(request=>resources.provides(request)||installations.some(installation=>resourceRequests(installation.provides??{}).some(provided=>provided.offer===request.offer))))continue;const dependencies=suppliers.filter(session=>session===owner||requests.some(request=>session.observer.resources?.provides(request))),observe=bindObservation(declaration,resources),available=__name(()=>dependencies.every(session=>session.available()),"available"),failure=declaration.failure??owner?.failure??(dependencies.some(session=>session.failure==="propagate")?"propagate":"isolate");sessions.push(new ObserverSession({observe,available},failure,error=>{for(const dependency of dependencies)dependency.stop(error)}))}return new InvocationObservation(sessions,installed)}__name(bindInvocationObservation,"bindInvocationObservation");function bindDriverObservation(driverId,installations=[]){const sessions=installations.flatMap(installation=>{const observer=installation.bindDriver?.(Object.freeze({driverId}));return observer?[new ObserverSession(observer,installation.failure??"isolate",error=>installation.invalidate?.(error))]:[]});return{publish:__name(fact=>publishSessions(sessions,observer=>observer.observe(fact)),"publish")}}__name(bindDriverObservation,"bindDriverObservation");export{bindDriverObservation,bindInvocationObservation};

package/dist/binding/receptions.d.ts

@@ -0,0 +1,9 @@
+import type { ChildContract, ReceptionDefinition, ReceptionRegistration } from '@weiliang0121/capix-contracts';
+import type { InvocationReceptionBinding } from '@weiliang0121/capix-invocation';
+import type { BoundChildren } from './children/bound.js';
+export declare class BoundReceptions {
+    #private;
+    constructor(receptions: readonly ReceptionRegistration[], children: BoundChildren);
+    require<Definition extends ChildContract, Value>(reception: ReceptionDefinition<NoInfer<Definition>, Value>, child: Definition): InvocationReceptionBinding;
+    bindings(): readonly InvocationReceptionBinding[];
+}

package/dist/binding/receptions.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{originalReception}from"./snapshot.js";class BoundReceptions{static{__name(this,"BoundReceptions")}#entries=new Map;#bindings;constructor(receptions,children){const bindings=[];for(const reception of receptions){const original=originalReception(reception);if(this.#entries.has(original))throw new Error("Duplicate parent reception contract");const value=reception.value,check=value.check.bind(value),binding=Object.freeze({position:bindings.length,childPosition:children.position(reception.child),check:__name(value2=>{const checked=check(value2);if(checked&&(typeof checked=="object"||typeof checked=="function")&&"then"in checked&&typeof checked.then=="function")throw Promise.resolve(checked).catch(()=>{}),new TypeError("Reception checks must return synchronously")},"check"),codec:Object.freeze({encode:value.encode.bind(value),decode:value.decode.bind(value)})});this.#entries.set(original,Object.freeze({child:reception.child,binding})),bindings.push(binding)}this.#bindings=Object.freeze(bindings)}require(reception,child){const entry=this.#entries.get(originalReception(reception));if(!entry)throw new Error("Reception contract is not registered by this parent");if(entry.child!==child)throw new Error("Reception contract belongs to a different child declaration");return entry.binding}bindings(){return this.#bindings}}export{BoundReceptions};

package/dist/binding/resources.d.ts

@@ -0,0 +1,18 @@
+import { type CallableDependencies } from '@weiliang0121/capix-structure/construction';
+import { type ResourceRefinement, type ResourceRequirements } from '@weiliang0121/capix-resources';
+import type { ObservationDeclaration } from '../definition/observation.js';
+import type { InvocationFact } from '@weiliang0121/capix-invocation';
+import type { ChildCallable } from '@weiliang0121/capix-structure';
+import type { CallableInput } from '@weiliang0121/capix-contracts';
+type RefinableDefinition = ChildCallable;
+export interface ChildResourceBinding {
+    readonly definition: RefinableDefinition;
+    readonly refinements: readonly ResourceRefinement<any>[];
+}
+export declare function bindChildResources<Definition extends RefinableDefinition>(definition: Definition, refinements: readonly ResourceRefinement<NoInfer<CallableInput<Definition>>>[]): ChildResourceBinding;
+export declare function collectDefinitionRequirements(definition: CallableDependencies, observationProvides?: ResourceRequirements, observations?: readonly ObservationDeclaration<InvocationFact>[]): ResourceRequirements;
+export declare function collectResourceSupply(requirements: readonly ResourceRequirements[]): ResourceRequirements;
+export declare function collectObservationProvides(installations?: readonly {
+    readonly provides?: ResourceRequirements;
+}[]): ResourceRequirements | undefined;
+export {};

package/dist/binding/resources.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{callableDependencies}from"@weiliang0121/capix-structure/construction";import{isResourceRefinement,resourceRequests}from"@weiliang0121/capix-resources";function bindChildResources(definition,refinements){const offers=new Set;for(const refinement of refinements){if(!isResourceRefinement(refinement))throw new Error("Resource refinement was not issued by an offer");if(offers.has(refinement.offer))throw new Error(`Duplicate resource refinement: ${refinement.offer.name}`);offers.add(refinement.offer)}return Object.freeze({definition,refinements:Object.freeze([...refinements])})}__name(bindChildResources,"bindChildResources");function collectDefinitionRequirements(definition,observationProvides,observations=[]){const deps={...callableDependencies(definition)},observationOffers=new Set(resourceRequests(observationProvides??{}).map(request=>request.offer));for(const[index,declaration]of(observationProvides?observations:[]).entries())for(const[name,request]of Object.entries(declaration.deps))observationOffers.has(request.offer)||(deps[`observation.${index}.${name}`]=request);return Object.freeze(deps)}__name(collectDefinitionRequirements,"collectDefinitionRequirements");function collectResourceSupply(requirements){const supply={},offers=new Set;for(const deps of requirements)for(const request of resourceRequests(deps))offers.has(request.offer)||(offers.add(request.offer),supply[`supply.${offers.size-1}`]=request);return Object.freeze(supply)}__name(collectResourceSupply,"collectResourceSupply");function collectObservationProvides(installations){if(!installations)return;const provided={};for(const[index,installation]of installations.entries())for(const[name,request]of Object.entries(installation.provides??{}))provided[`${index}.${name}`]=request;return Object.freeze(provided)}__name(collectObservationProvides,"collectObservationProvides");export{bindChildResources,collectDefinitionRequirements,collectObservationProvides,collectResourceSupply};

package/dist/binding/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { CallableDescription, CallableRun, ChildCallable, NamedMembers } from '@weiliang0121/capix-structure';
+import type { CallableKind } from '@weiliang0121/capix-contracts';
+import type { ObservationDeclaration } from '../definition/observation.js';
+import type { ResourceRequirements } from '@weiliang0121/capix-resources';
+import type { AnyCallable } from './declarations.js';
+export interface CallableSnapshot<Input = any, Output = any, Kind extends CallableKind = any, Resources extends object = any, Delta = any> extends Omit<CallableDescription<Input, Output, Kind, Delta>, 'kind' | 'members'> {
+    readonly kind: Kind;
+    readonly deps: ResourceRequirements<Resources>;
+    readonly run: CallableRun<Input, Output, Kind, Resources, import('@weiliang0121/capix-structure').ChildContractsOf<Kind>, Delta>;
+    readonly members?: readonly ChildCallable[];
+    readonly names?: NamedMembers;
+}
+export declare function snapshotDefinition(definition: AnyCallable): CallableSnapshot;
+export declare function originalReception(reception: object): object;
+export declare function snapshotObservation<Fact>(declaration: ObservationDeclaration<Fact>): ObservationDeclaration<Fact>;
+export declare function originalCheckpointPoint(point: object): object;

package/dist/binding/snapshot.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{checkMemberName}from"@weiliang0121/capix-structure/construction";function snapshotDefinition(definition){const members="members"in definition?definition.members:void 0,names="names"in definition?definition.names:void 0;if(definition.kind==="node"&&names!==void 0)throw new Error("Nodes cannot declare member names");for(const[name,member]of Object.entries(names??{}))if(checkMemberName(name),!members?.includes(member))throw new Error("Named member is outside its owner");if(definition.kind==="node"&&members!==void 0)throw new Error("Nodes cannot declare members");if(definition.kind==="node"&&definition.checkpoint?.receptions!==void 0)throw new Error("Nodes cannot declare checkpoint receptions");for(const field of["setRun","setDefinition","accept","exceptions","raises","maxRounds","uses","observation","callee","receptions"])if(field in definition)throw new Error(`Unsupported callable configuration field: ${field}`);const run=definition.run;if(typeof run!="function")throw new Error("Callable definition needs a run function");const output=definition.output;return Object.freeze({kind:definition.kind,name:definition.name,label:definition.label,source:definition.source,output:output?Object.freeze({result:output.result.bind(output),delta:output.delta?.bind(output)}):void 0,deps:Object.freeze({...definition.deps}),run:run.bind(definition),checkpoint:definition.checkpoint?snapshotCheckpoint(definition.checkpoint):void 0,...members?{members:Object.freeze([...members]),names:Object.freeze({...names})}:{}})}__name(snapshotDefinition,"snapshotDefinition");const receptionOrigins=new WeakMap;function originalReception(reception){return receptionOrigins.get(reception)??reception}__name(originalReception,"originalReception");function snapshotReception(reception){const value=reception.value;if(typeof value?.check!="function"||typeof value.encode!="function"||typeof value.decode!="function")throw new Error("Reception needs check, encode and decode functions");const fixed=Object.freeze({child:reception.child,value:Object.freeze({check:value.check.bind(value),encode:value.encode.bind(value),decode:value.decode.bind(value)})});return receptionOrigins.set(fixed,originalReception(reception)),fixed}__name(snapshotReception,"snapshotReception");function snapshotObservation(declaration){return Object.freeze({deps:Object.freeze({...declaration.deps}),failure:declaration.failure,observe:declaration.observe.bind(declaration)})}__name(snapshotObservation,"snapshotObservation");function snapshotReceptions(receptions){return Object.freeze(receptions.map(snapshotReception))}__name(snapshotReceptions,"snapshotReceptions");function snapshotCodec(codec){return Object.freeze({encode:codec.encode.bind(codec),decode:codec.decode.bind(codec)})}__name(snapshotCodec,"snapshotCodec");function snapshotCheckpoint(checkpoint){return Object.freeze({key:checkpoint.key,version:checkpoint.version,input:snapshotCodec(checkpoint.input),output:snapshotCodec(checkpoint.output),points:Object.freeze(checkpoint.points.map(snapshotCheckpointPoint)),receptions:checkpoint.receptions?snapshotReceptions(checkpoint.receptions):void 0})}__name(snapshotCheckpoint,"snapshotCheckpoint");const pointOrigins=new WeakMap;function originalCheckpointPoint(point){return pointOrigins.get(point)??point}__name(originalCheckpointPoint,"originalCheckpointPoint");function snapshotCheckpointPoint(point){const resume=point.resume,fixed=Object.freeze({name:point.name,state:snapshotCodec(point.state),references:Object.freeze(Object.fromEntries(Object.entries(point.references).map(([name,slot])=>[name,Object.freeze({...slot})]))),check:point.check?.bind(point),resume:Object.freeze({deps:Object.freeze({...resume.deps}),uses:resume.uses?Object.freeze([...resume.uses]):void 0,run:resume.run.bind(resume)})});return pointOrigins.set(fixed,originalCheckpointPoint(point)),fixed}__name(snapshotCheckpointPoint,"snapshotCheckpointPoint");export{originalCheckpointPoint,originalReception,snapshotDefinition,snapshotObservation};

package/dist/binding/work.d.ts

@@ -0,0 +1,20 @@
+import type { CallableKind, OperationOutcome } from '@weiliang0121/capix-contracts';
+import type { CallableContext, InvocationCheckpointWork, InvocationWork, Invocation } from '@weiliang0121/capix-invocation';
+import type { BoundChildren } from './children/bound.js';
+import { type CallableSnapshot } from './snapshot.js';
+export declare class InvocationWorkBinding<Input, Output, Context extends CallableContext<Input, Output>, Resources extends object, Kind extends CallableKind> implements InvocationWork<Input, Output, Context> {
+    #private;
+    private readonly declaration;
+    private readonly children;
+    private readonly composite;
+    readonly output: InvocationWork<Input, Output, Context>['output'];
+    readonly checkpoint?: InvocationCheckpointWork<Input, Output, Context>;
+    constructor(declaration: CallableSnapshot<Input, Output, Kind, Resources, any>, children: BoundChildren, composite: boolean);
+    execute(_context: Context, invocation: Invocation<Input, Output, Context>): Output | import("@weiliang0121/capix-contracts").Stable<Output> | Promise<Output | import("@weiliang0121/capix-contracts").Stable<Output>>;
+    close(_context: Context, invocation: Invocation<Input, Output, Context>): OperationOutcome<void>;
+    private resume;
+    private childPort;
+    private executionWork;
+    private accessFor;
+    private bindCheckpoint;
+}