@weiliang0121/capix-runtime 0.0.0-stage → 0.1.0

package/dist/resource/installation.d.ts

@@ -0,0 +1,9 @@
+import type { AnyCallable, ResolvedCallable } from '../binding/declarations.js';
+import type { Interactions } from '@weiliang0121/capix-interaction';
+import { ResourceSupply } from '@weiliang0121/capix-resources';
+import type { ResourcePlan } from './resources.js';
+export declare class ResourceInstallation<Options> {
+    private readonly scopes;
+    constructor(root: ResolvedCallable, plan: ResourcePlan<Options>, interactions?: Interactions);
+    open(structure: AnyCallable, input: unknown, options: Options, inherited?: ResourceSupply): ResourceSupply;
+}

package/dist/resource/installation.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,checkResourceProviders,ResourceSupply}from"@weiliang0121/capix-resources";class ResourceInstallation{static{__name(this,"ResourceInstallation")}scopes=new Map;constructor(root,plan,interactions){const captureScopes=new Map(plan.scopes.map(scope=>[scope.structure,scope])),visit=__name((resolved,inherited)=>{const scope=captureScopes.get(resolved.definition),requested=resourceRequests(resolved.supply),needed=new Set(requested.map(request=>request.offer)),local=(scope?.registrations??[]).filter(entry=>needed.has(entry.offer)).map(entry=>entry.bind(interactions)),localOffers=new Set(local.map(entry=>entry.offer)),fixed=resolved===root?plan.registrations.filter(entry=>needed.has(entry.offer)&&!localOffers.has(entry.offer)).map(entry=>entry.bind(interactions)):[],available=[...(resolved===root?fixed:inherited).filter(entry=>!localOffers.has(entry.offer)),...local];checkResourceProviders(requested,available),this.scopes.set(resolved.definition,Object.freeze({supply:resolved.supply,fixed,local,capture:local.length?scope?.capture:void 0}));for(const member of resolved.members)visit(member,available)},"visit");visit(root,[])}open(structure,input,options,inherited){const scope=this.scopes.get(structure);if(!scope)throw new Error("Callable resource scope is not installed");const base=inherited??ResourceSupply.capture(scope.fixed,void 0),snapshot=scope.capture?.(input,options);return base.overlay(ResourceSupply.capture(scope.local,snapshot)).select(scope.supply)}}export{ResourceInstallation};

package/dist/resource/resources.d.ts

@@ -0,0 +1,37 @@
+import type { AnyCallable } from '../binding/declarations.js';
+import type { ChildResourceBinding } from '../binding/resources.js';
+import { type ChildCallable } from '@weiliang0121/capix-structure';
+import type { CallableInput, Stable } from '@weiliang0121/capix-contracts';
+import type { InteractionContract } from '@weiliang0121/capix-interaction';
+import type { InteractionChannel, Interactions } from '@weiliang0121/capix-interaction';
+import { ResourceOffer, type ResourceIdentity, type ResourceProvider, type ResourceRefinement, Resource } from '@weiliang0121/capix-resources';
+export interface ResourceRegistration {
+    readonly offer: ResourceIdentity;
+    bind(interactions?: Interactions): ResourceProvider<unknown>;
+}
+export interface ResourceCaptureScope<Options> {
+    readonly structure: AnyCallable;
+    readonly capture: (input: unknown, options: Options) => unknown;
+    readonly registrations: readonly ResourceRegistration[];
+}
+export interface ResourcePlan<Options> {
+    readonly registrations: readonly ResourceRegistration[];
+    readonly scopes: readonly ResourceCaptureScope<Options>[];
+    readonly refinements: readonly ChildResourceBinding[];
+}
+type Synchronous<Value> = Value & (Value extends PromiseLike<unknown> ? never : unknown);
+export declare class CapturedResources<Snapshot> {
+    private readonly registrations;
+    constructor(registrations: ResourceRegistration[]);
+    register<Source, Value, Captured, Selection>(offer: ResourceOffer<Source, Value, Captured, Selection>, select: (snapshot: Snapshot) => Synchronous<NoInfer<Source>>): this;
+}
+export declare class Resources<Options extends object = {}> {
+    #private;
+    register<Source, Value, Captured, Selection>(resource: Resource<NoInfer<Source>>, offer: ResourceOffer<Source, Value, Captured, Selection>): this;
+    register<Source, Value, Captured, Selection>(offer: ResourceOffer<Source, Value, Captured, Selection>, supply: NoInfer<Source>): this;
+    capture<Structure extends AnyCallable, Snapshot>(structure: Structure, capture: (input: Stable<CallableInput<Structure>>, options: Options) => Synchronous<Snapshot>): CapturedResources<Snapshot>;
+    refine<Structure extends ChildCallable>(structure: Structure, ...rules: readonly ResourceRefinement<NoInfer<Stable<CallableInput<Structure>>>>[]): this;
+    registerInteraction<Request, Reply, Delta, Value, Captured, Selection>(offer: ResourceOffer<InteractionChannel<Request, Reply, Delta>, Value, Captured, Selection>, contract: InteractionContract<NoInfer<Request>, NoInfer<Reply>, NoInfer<Delta>>): this;
+    snapshot(root: AnyCallable): ResourcePlan<Options>;
+}
+export {};

package/dist/resource/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{Callable}from"@weiliang0121/capix-structure";import{ResourceOffer,Resource}from"@weiliang0121/capix-resources";class CapturedResources{static{__name(this,"CapturedResources")}registrations;constructor(registrations){this.registrations=registrations}register(offer,select){const provider=offer.provide(snapshot=>synchronous(select(snapshot),"Resource selection"));return addRegistration(this.registrations,Object.freeze({offer:provider.offer,bind:__name(()=>provider,"bind")})),this}}class Resources{static{__name(this,"Resources")}#registrations=[];#scopes=new Map;#refinements=new Map;register(resourceOrOffer,offerOrSupply){const resource=resourceOrOffer instanceof Resource?resourceOrOffer:void 0,offer=resource?offerOrSupply:resourceOrOffer;if(!(offer instanceof ResourceOffer))throw new TypeError("Resource registration requires an access offer");const supply=resource?resource.origin:offerOrSupply,provider=offer.provide(()=>supply);return addRegistration(this.#registrations,Object.freeze({offer:provider.offer,bind:__name(()=>provider,"bind")})),this}capture(structure,capture){if(requireCallable(structure),this.#scopes.has(structure))throw new Error("Duplicate resource capture scope");const registrations=[];return this.#scopes.set(structure,{capture:__name((input,options)=>synchronous(capture(input,options),"Resource capture"),"capture"),registrations}),new CapturedResources(registrations)}refine(structure,...rules){if(requireCallable(structure),structure.kind!=="group"&&structure.kind!=="node")throw new Error("Resource refinement requires a child structure");const previous=this.#refinements.get(structure)??[];return this.#refinements.set(structure,[...previous,...rules]),this}registerInteraction(offer,contract){const identity=offer.request().offer;return addRegistration(this.#registrations,Object.freeze({offer:identity,bind:__name(interactions=>{if(!interactions)throw new Error(`Resource requires Interactions: ${identity.name}`);const channel=interactions.bind(contract);return offer.provide(()=>channel)},"bind")})),this}snapshot(root){const members=new Set,visit=__name(current=>{if(!members.has(current)&&(members.add(current),current.kind!=="node"))for(const member of current.members)visit(member)},"visit");return visit(root),Object.freeze({registrations:Object.freeze([...this.#registrations]),scopes:Object.freeze([...this.#scopes].filter(([structure])=>members.has(structure)).map(([structure,scope])=>Object.freeze({structure,capture:scope.capture,registrations:Object.freeze([...scope.registrations])}))),refinements:Object.freeze([...this.#refinements].filter(([structure])=>members.has(structure)).map(([definition,refinements])=>Object.freeze({definition,refinements:Object.freeze([...refinements])})))})}}function requireCallable(structure){if(!(structure instanceof Callable))throw new TypeError("Resource scope requires a callable structure")}__name(requireCallable,"requireCallable");function addRegistration(registrations,registration){if(registrations.some(entry=>entry.offer===registration.offer))throw new Error(`Duplicate resource registration: ${registration.offer.name}`);registrations.push(registration)}__name(addRegistration,"addRegistration");function synchronous(value,label){if(value!==null&&(typeof value=="object"||typeof value=="function")&&typeof value.then=="function")throw Promise.resolve(value).catch(()=>{}),new TypeError(`${label} must be synchronous`);return value}__name(synchronous,"synchronous");export{CapturedResources,Resources};

package/dist/runner/cancellation.d.ts

@@ -0,0 +1,9 @@
+export declare class RunnerCancellation {
+    #private;
+    private readonly external?;
+    constructor(external?: AbortSignal | undefined);
+    get signal(): AbortSignal;
+    cancel(reason?: unknown): boolean;
+    deliveryError(error: unknown): unknown;
+    dispose(): void;
+}

package/dist/runner/cancellation.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{InvocationCancelled,isInvocationCancelled}from"@weiliang0121/capix-invocation";class RunnerCancellation{static{__name(this,"RunnerCancellation")}external;#controller=new AbortController;#origin;#externalAborted=__name(()=>{this.#controller.signal.aborted||(this.#origin="external",this.#controller.abort(this.external?.reason))},"#externalAborted");constructor(external){if(this.external=external,external){if(!(external instanceof AbortSignal))throw new TypeError("Runner signal must be an AbortSignal");external.aborted?this.#externalAborted():external.addEventListener("abort",this.#externalAborted,{once:!0})}}get signal(){return this.#controller.signal}cancel(reason){return!this.signal.aborted&&this.external?.aborted&&this.#externalAborted(),this.signal.aborted?!1:(this.#origin="runner",this.#controller.abort(reason),!0)}deliveryError(error){return this.#origin==="external"&&this.external&&isInvocationCancelled(error,this.signal)?new InvocationCancelled(this.external,{cause:error}):error}dispose(){this.external?.removeEventListener("abort",this.#externalAborted)}}export{RunnerCancellation};

package/dist/runner/feedback.d.ts

@@ -0,0 +1,20 @@
+import { type ProgressReceiver } from '@weiliang0121/capix-changes';
+import type { InvocationIdentity } from '@weiliang0121/capix-contracts';
+import type { Clock } from '@weiliang0121/capix-invocation';
+import type { CallableFeedback } from '../construction/feedback.js';
+import type { EntryChange } from '../entry.js';
+import { RunnerObservationSubscriptions } from './observation.js';
+export declare class RunnerEntryFeedback {
+    #private;
+    private readonly runnerId;
+    private readonly subscriptions;
+    private readonly clock;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly created: ProgressReceiver<InvocationIdentity>;
+    constructor(runnerId: string, subscriptions: RunnerObservationSubscriptions, clock: Clock);
+    requested(mode: 'run' | 'resume', requestedContextId?: string): void;
+    entry(change: EntryChange): void;
+    settled(status: 'succeeded' | 'failed' | 'cancelled', error?: unknown): void;
+    receivers(signal: AbortSignal): CallableFeedback;
+    private publishEntry;
+}

package/dist/runner/feedback.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{randomUUID}from"node:crypto";import{ProgressChannel}from"@weiliang0121/capix-changes";import"./observation.js";import{projectInvocation,projectResource,projectBusiness,projectCheckpoint,projectDiagnostic}from"./observation-projection.js";class RunnerEntryFeedback{static{__name(this,"RunnerEntryFeedback")}runnerId;subscriptions;clock;id=randomUUID();#sequence=0;#entries;created;constructor(runnerId,subscriptions,clock){this.runnerId=runnerId,this.subscriptions=subscriptions,this.clock=clock,this.#entries=new ProgressChannel({receive:__name(change=>this.publishEntry(change),"receive")}),this.created=Object.freeze({receive:__name(identity=>{this.#entries.publish({kind:"attached",identity})},"receive")})}requested(mode,requestedContextId){this.#entries.publish({kind:"requested",mode,...requestedContextId!==void 0?{requestedContextId}:{}})}entry(change){change.kind!=="established"&&this.#entries.publish(change)}settled(status,error){this.#entries.publish({kind:"settled",status,error})}receivers(signal){return Object.freeze({invocation:{receive:__name(fact=>{this.subscriptions.active&&this.subscriptions.publish({runnerId:this.runnerId,entryId:this.id,source:"invocation",fact:projectInvocation(fact,signal)})},"receive")},resource:{receive:__name(fact=>{this.subscriptions.active&&this.subscriptions.publish({runnerId:this.runnerId,entryId:this.id,source:"resource",fact:projectResource(fact)})},"receive")},business:{receive:__name(fact=>{this.subscriptions.active&&this.subscriptions.publish({runnerId:this.runnerId,entryId:this.id,source:"business",fact:projectBusiness(fact)})},"receive")},checkpoint:{receive:__name(fact=>{this.subscriptions.active&&this.subscriptions.publish({runnerId:this.runnerId,entryId:this.id,source:"checkpoint",fact:projectCheckpoint(fact,signal)})},"receive")}})}publishEntry(change){const sequence=++this.#sequence;if(!this.subscriptions.active)return;const time={sequence,occurredAt:this.clock.now()};let fact;change.kind==="requested"?fact=Object.freeze({...time,...change}):change.kind==="attached"?fact=Object.freeze({...time,kind:"attached",identity:Object.freeze({...change.identity})}):change.kind==="settled"?fact=Object.freeze({...time,kind:"settled",status:change.status,...change.status!=="succeeded"?{diagnostic:projectDiagnostic(change.error)}:{}}):change.kind==="entry-failed"?fact=Object.freeze({...time,kind:"entry-failed",diagnostic:projectDiagnostic(change.error)}):change.kind==="rejected"?fact=Object.freeze({...time,kind:"rejected",reason:change.reason,diagnostic:projectDiagnostic(change.error)}):fact=Object.freeze({...time,kind:change.kind}),this.subscriptions.publish({runnerId:this.runnerId,entryId:this.id,source:"entry",fact})}}export{RunnerEntryFeedback};

package/dist/runner/observation-contract.d.ts

@@ -0,0 +1,137 @@
+import type { InvocationIdentity } from '@weiliang0121/capix-contracts';
+import type { InvocationProgress } from '@weiliang0121/capix-invocation';
+export interface RunnerDiagnostic {
+    readonly code: string;
+    readonly message: string;
+}
+export type RunnerEntryFact = Readonly<{
+    sequence: number;
+    occurredAt: string;
+} & ({
+    kind: 'requested';
+    mode: 'run' | 'resume';
+    requestedContextId?: string;
+} | {
+    kind: 'acquired' | 'released';
+} | {
+    kind: 'rejected';
+    reason: 'busy';
+    diagnostic: RunnerDiagnostic;
+} | {
+    kind: 'entry-failed';
+    diagnostic: RunnerDiagnostic;
+} | {
+    kind: 'attached';
+    identity: InvocationIdentity;
+} | {
+    kind: 'settled';
+    status: 'succeeded' | 'failed' | 'cancelled';
+    diagnostic?: RunnerDiagnostic;
+})>;
+export interface RunnerResourceFact {
+    readonly contextId: string;
+    readonly offerId: string;
+    readonly access: string;
+    readonly supplyId: string;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly phase: 'bound' | 'available' | 'unavailable' | 'started' | 'returned' | 'threw';
+    readonly interactionId?: string;
+}
+export interface RunnerBusinessFact {
+    readonly identity: InvocationIdentity;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly event: string;
+}
+export type RunnerCheckpointChild = Readonly<{
+    identity: InvocationIdentity;
+    round: number;
+    order: number;
+    key?: string;
+} & ({
+    state: 'waiting';
+} | {
+    state: 'returned';
+    reception: 'pending' | 'receiving' | 'accepted' | 'failed';
+} | {
+    state: 'failed';
+    reception?: 'handled';
+})>;
+export interface RunnerTranscriptFact {
+    readonly transcriptId: string;
+    readonly revision: number;
+    readonly change: 'messages-appended' | 'segment-started';
+    readonly start: number;
+    readonly end: number;
+}
+export interface RunnerMemoryFact {
+    readonly memoriesId: string;
+    readonly sequence: number;
+    readonly action: 'create' | 'update';
+    readonly memoryId: string;
+}
+export type RunnerCheckpointFact = Readonly<{
+    activityId: string;
+    contextId: string;
+    owner: InvocationIdentity;
+    recovering: boolean;
+    sequence: number;
+    occurredAt: string;
+} & ({
+    kind: 'captured' | 'saved' | 'checking' | 'continued';
+    checkpointId: string;
+    point: string;
+} | {
+    kind: 'installed';
+    checkpointId: string;
+    point: string;
+    baseline: Readonly<{
+        round: number;
+        nextChildOrder: number;
+        childCount: number;
+    }>;
+} | {
+    kind: 'child-restored';
+    child: RunnerCheckpointChild;
+    mode: 'continuation' | 'delivery';
+} | {
+    kind: 'activity';
+    fact: InvocationProgress;
+} | {
+    kind: 'resource';
+    fact: RunnerResourceFact;
+} | {
+    kind: 'transcript';
+    fact: RunnerTranscriptFact;
+} | {
+    kind: 'memory';
+    fact: RunnerMemoryFact;
+} | {
+    kind: 'failed';
+    stage: 'capture' | 'save' | 'restore' | 'finish';
+    diagnostic: RunnerDiagnostic;
+    childContextId?: string;
+} | {
+    kind: 'finishing' | 'finished';
+    status: 'succeeded' | 'failed' | 'cancelled';
+})>;
+export type RunnerObservationEvent = Readonly<{
+    runnerId: string;
+    entryId: string;
+} & ({
+    source: 'entry';
+    fact: RunnerEntryFact;
+} | {
+    source: 'invocation';
+    fact: InvocationProgress;
+} | {
+    source: 'resource';
+    fact: RunnerResourceFact;
+} | {
+    source: 'checkpoint';
+    fact: RunnerCheckpointFact;
+} | {
+    source: 'business';
+    fact: RunnerBusinessFact;
+})>;

package/dist/runner/observation-contract.js

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

package/dist/runner/observation-projection.d.ts

@@ -0,0 +1,7 @@
+import { type InvocationFact, type InvocationProgress, type ResourceObservation, type BusinessObservation, type CheckpointFact } from '@weiliang0121/capix-invocation';
+import type { RunnerDiagnostic, RunnerResourceFact, RunnerBusinessFact, RunnerCheckpointFact } from './observation-contract.js';
+export declare function projectInvocation(fact: InvocationFact, signal: AbortSignal): InvocationProgress;
+export declare function projectResource(fact: ResourceObservation): RunnerResourceFact;
+export declare function projectBusiness(fact: BusinessObservation): RunnerBusinessFact;
+export declare function projectDiagnostic(error: unknown): RunnerDiagnostic;
+export declare function projectCheckpoint(fact: CheckpointFact, signal: AbortSignal): RunnerCheckpointFact;

package/dist/runner/observation-projection.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{RuntimeErrorHelper}from"@weiliang0121/capix-diagnostics";import{invocationProgress}from"@weiliang0121/capix-invocation";function projectInvocation(fact,signal){return invocationProgress(fact,signal)}__name(projectInvocation,"projectInvocation");function projectResource(fact){return Object.freeze({contextId:fact.contextId,offerId:fact.offerId,access:fact.access,supplyId:fact.supplyId,sequence:fact.sequence,occurredAt:fact.occurredAt,phase:fact.phase,...fact.interactionId!==void 0?{interactionId:fact.interactionId}:{}})}__name(projectResource,"projectResource");function projectBusiness(fact){return Object.freeze({identity:projectIdentity(fact.identity),sequence:fact.sequence,occurredAt:fact.occurredAt,event:fact.event.event})}__name(projectBusiness,"projectBusiness");function projectDiagnostic(error){try{const diagnostic=RuntimeErrorHelper.format(error);return Object.freeze({code:diagnostic.code.slice(0,128),message:diagnostic.message.slice(0,512)})}catch{return Object.freeze({code:"OBSERVATION_DIAGNOSTIC_FAILED",message:"The failure could not be described."})}}__name(projectDiagnostic,"projectDiagnostic");function projectCheckpoint(fact,signal){const base={activityId:fact.activityId,contextId:fact.contextId,owner:projectIdentity(fact.owner),recovering:fact.recovering,sequence:fact.sequence,occurredAt:fact.occurredAt};switch(fact.kind){case"captured":case"saved":case"checking":case"continued":return Object.freeze({...base,kind:fact.kind,checkpointId:fact.checkpointId,point:fact.point});case"installed":return Object.freeze({...base,kind:fact.kind,checkpointId:fact.checkpointId,point:fact.point,baseline:Object.freeze({round:fact.frame.round,nextChildOrder:fact.frame.nextChildOrder,childCount:fact.frame.children.length})});case"child-restored":return Object.freeze({...base,kind:fact.kind,child:projectChild(fact.child),mode:fact.mode});case"activity":return Object.freeze({...base,kind:fact.kind,fact:projectInvocation(fact.fact,signal)});case"resource":return Object.freeze({...base,kind:fact.kind,fact:projectResource(fact.fact)});case"transcript":{const change=fact.fact.change,content=Object.freeze({transcriptId:fact.fact.transcriptId,revision:fact.fact.revision,change:change.kind,start:change.start,end:change.kind==="messages-appended"?change.start+change.messages.length:change.end});return Object.freeze({...base,kind:fact.kind,fact:content})}case"memory":return Object.freeze({...base,kind:fact.kind,fact:Object.freeze({memoriesId:fact.fact.memoriesId,sequence:fact.fact.sequence,action:fact.fact.change.action,memoryId:fact.fact.change.memoryId})});case"failed":return Object.freeze({...base,kind:fact.kind,stage:fact.stage,diagnostic:projectDiagnostic(fact.error),...fact.childContextId!==void 0?{childContextId:fact.childContextId}:{}});case"finishing":case"finished":return Object.freeze({...base,kind:fact.kind,status:fact.status})}}__name(projectCheckpoint,"projectCheckpoint");function projectIdentity(identity){return Object.freeze({contextId:identity.contextId,kind:identity.kind,...identity.parentContextId!==void 0?{parentContextId:identity.parentContextId}:{}})}__name(projectIdentity,"projectIdentity");function projectChild(child){const base={identity:projectIdentity(child.identity),round:child.round,order:child.order,...child.key!==void 0?{key:child.key}:{}};return child.state.kind==="waiting"?Object.freeze({...base,state:child.state.kind}):child.state.kind==="returned"?Object.freeze({...base,state:child.state.kind,reception:child.state.reception.kind}):Object.freeze({...base,state:child.state.kind,...child.state.reception?{reception:child.state.reception.kind}:{}})}__name(projectChild,"projectChild");export{projectBusiness,projectCheckpoint,projectDiagnostic,projectInvocation,projectResource};

package/dist/runner/observation.d.ts

@@ -0,0 +1,14 @@
+import { type ProgressReceiver } from '@weiliang0121/capix-changes';
+import type { RunnerObservationEvent } from './observation-contract.js';
+export type { RunnerDiagnostic, RunnerEntryFact, RunnerResourceFact, RunnerBusinessFact, RunnerCheckpointChild, RunnerCheckpointFact, RunnerObservationEvent } from './observation-contract.js';
+export type RunnerObservationReceiver = ProgressReceiver<RunnerObservationEvent>;
+export interface RunnerObservation {
+    subscribe(receiver: RunnerObservationReceiver): () => void;
+}
+export declare class RunnerObservationSubscriptions {
+    #private;
+    readonly port: RunnerObservation;
+    get active(): boolean;
+    publish(event: RunnerObservationEvent): undefined;
+    private subscribe;
+}

package/dist/runner/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{ProgressChannel}from"@weiliang0121/capix-changes";class RunnerObservationSubscriptions{static{__name(this,"RunnerObservationSubscriptions")}#subscribers=new Set;port=Object.freeze({subscribe:__name(receiver=>this.subscribe(receiver),"subscribe")});get active(){return this.#subscribers.size>0}publish(event){const fixed=Object.freeze({...event});for(const channel of[...this.#subscribers])this.#subscribers.has(channel)&&(channel.publish(fixed),channel.failure&&this.#subscribers.delete(channel))}subscribe(receiver){if(!receiver||typeof receiver.receive!="function"||receiver.failed!==void 0&&typeof receiver.failed!="function")throw new TypeError("Observation subscription requires a synchronous receiver");const channel=new ProgressChannel({receive:receiver.receive.bind(receiver),failed:receiver.failed?.bind(receiver)});return this.#subscribers.add(channel),()=>{this.#subscribers.delete(channel)}}}export{RunnerObservationSubscriptions};

package/dist/runner/output.d.ts

@@ -0,0 +1,14 @@
+import type { InvocationOutputEvent, InvocationOutputReceiver, ProgressReceiver } from '@weiliang0121/capix-contracts';
+export type RunnerOutputEvent<Result, Delta = never> = InvocationOutputEvent<Result, Delta> & Readonly<{
+    entryId: string;
+}>;
+export interface RunnerOutput<Result, Delta = never> {
+    subscribe(receiver: ProgressReceiver<RunnerOutputEvent<Result, Delta>>): () => void;
+}
+export declare class RunnerOutputSubscriptions<Result, Delta> {
+    #private;
+    readonly port: RunnerOutput<Result, Delta>;
+    forEntry(entryId: string): InvocationOutputReceiver<Result, Delta>;
+    private subscribe;
+    private publish;
+}

package/dist/runner/output.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{ProgressChannel}from"@weiliang0121/capix-changes";class RunnerOutputSubscriptions{static{__name(this,"RunnerOutputSubscriptions")}#subscribers=new Set;port=Object.freeze({subscribe:__name(receiver=>this.subscribe(receiver),"subscribe")});forEntry(entryId){return Object.freeze({receive:__name(event=>this.publish(event,entryId),"receive")})}subscribe(receiver){if(!receiver||typeof receiver.receive!="function"||receiver.failed!==void 0&&typeof receiver.failed!="function")throw new TypeError("Output subscription requires a synchronous receiver");const channel=new ProgressChannel({receive:receiver.receive.bind(receiver),failed:receiver.failed?.bind(receiver)});return this.#subscribers.add(channel),()=>{this.#subscribers.delete(channel)}}publish(event,entryId){if(!this.#subscribers.size)return;const output=Object.freeze({...event,entryId});for(const channel of[...this.#subscribers])this.#subscribers.has(channel)&&(channel.publish(output),channel.failure&&this.#subscribers.delete(channel))}}export{RunnerOutputSubscriptions};

package/dist/runner.d.ts

@@ -0,0 +1,37 @@
+import { type InvocationControls } from '@weiliang0121/capix-invocation';
+import type { CallableHookBinding } from './binding/hooks.js';
+import { type InvocationCapabilities } from './construction/capabilities.js';
+import type { CallableInput, CallableOutput, CallableDelta, Stable } from '@weiliang0121/capix-contracts';
+import type { CheckpointStore } from '@weiliang0121/capix-checkpoint';
+import { Resources } from './resource/resources.js';
+import { Interactions } from '@weiliang0121/capix-interaction';
+import type { AnyCallable } from './binding/declarations.js';
+import { type RunnerOutput } from './runner/output.js';
+import { type RunnerObservation } from './runner/observation.js';
+export type { RunnerOutput, RunnerOutputEvent } from './runner/output.js';
+export type { RunnerObservation, RunnerObservationReceiver } from './runner/observation.js';
+export type * from './runner/observation-contract.js';
+export interface RunnerOptions<Options extends object = {}> extends InvocationCapabilities {
+    readonly hooks?: readonly CallableHookBinding<Options>[];
+    readonly validate?: (options: Options) => undefined;
+}
+export type RunnerArguments<Options extends object> = {} extends Options ? [options?: Options & InvocationControls] : [options: Options & InvocationControls];
+export declare class Runner<Structure extends Extract<AnyCallable, {
+    readonly kind: 'scene';
+}>, Options extends object = {}> {
+    #private;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    constructor(scene: Structure, resources: Resources<Options>, interactions?: Interactions, options?: RunnerOptions<NoInfer<Options>>);
+    get scene(): Structure;
+    get checkpointStore(): CheckpointStore | undefined;
+    get isRunning(): boolean;
+    get output(): RunnerOutput<CallableOutput<Structure>, CallableDelta<Structure>>;
+    get observation(): RunnerObservation;
+    cancel(reason?: unknown): boolean;
+    build(): this;
+    run(input: NoInfer<CallableInput<Structure> | Stable<CallableInput<Structure>>>, ...args: RunnerArguments<Options>): Promise<Stable<CallableOutput<Structure>>>;
+    resume(contextId: string, ...args: RunnerArguments<Options>): Promise<Stable<CallableOutput<Structure>>>;
+    private perform;
+    private snapshotOptions;
+    private publish;
+}

package/dist/runner.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{randomUUID}from"node:crypto";import{isUndefined}from"es-toolkit/predicate";import{Clock,isInvocationCancelled}from"@weiliang0121/capix-invocation";import{bindDriverObservation}from"./binding/observation.js";import{CallableBuilder}from"./structure/builder.js";import{runEntry}from"./entry.js";import{snapshotInvocationCapabilities}from"./construction/capabilities.js";import{Scene}from"@weiliang0121/capix-structure";import{Resources}from"./resource/resources.js";import{Interactions}from"@weiliang0121/capix-interaction";import{RunnerOutputSubscriptions}from"./runner/output.js";import{RunnerCancellation}from"./runner/cancellation.js";import{RunnerObservationSubscriptions}from"./runner/observation.js";import{RunnerEntryFeedback}from"./runner/feedback.js";class Runner{static{__name(this,"Runner")}id=randomUUID();#scene;#resources;#interactions;#options;#builder;#clock;#checkpoints;#observation;#built;#building=!1;#entry={running:!1};#outputs=new RunnerOutputSubscriptions;#observations=new RunnerObservationSubscriptions;#cancellation;#sequence=0;constructor(scene,resources,interactions,options={}){if(!(scene instanceof Scene))throw new TypeError("Runner requires a Scene");if(!(resources instanceof Resources))throw new TypeError("Runner requires Resources");if(interactions!==void 0&&!(interactions instanceof Interactions))throw new TypeError("Runner interactions must be an Interactions instance");this.#scene=scene,this.#resources=resources,this.#interactions=interactions,this.#options=Object.freeze({hooks:options.hooks?Object.freeze([...options.hooks]):void 0,validate:options.validate?.bind(options)}),this.#clock=options.clock??new Clock;const capabilities=snapshotInvocationCapabilities({...options,clock:this.#clock});this.#checkpoints=capabilities.checkpoints,this.#builder=new CallableBuilder(capabilities),this.#observation=bindDriverObservation(this.id,capabilities.observations),this.publish({kind:"established"})}get scene(){return this.#scene}get checkpointStore(){return this.#checkpoints?.store}get isRunning(){return this.#entry.running}get output(){return this.#outputs.port}get observation(){return this.#observations.port}cancel(reason){return this.#entry.running?this.#cancellation?.cancel(reason)??!1:!1}build(){if(this.#built)throw new Error("Runner has already been built");if(this.#building)throw new Error("Runner build is already in progress");this.#building=!0;try{return this.#built=this.#builder.build(this.#scene,this.#resources,this.#interactions,this.#options),this}finally{this.#building=!1}}run(input,...args){return this.perform({input},args[0]??{})}resume(contextId,...args){return this.perform({contextId},args[0]??{})}async perform(request,options){const feedback=new RunnerEntryFeedback(this.id,this.#observations,this.#clock),mode="contextId"in request?"resume":"run",requestedContextId="contextId"in request?request.contextId:void 0;let requested=!1,cancellation,externalSignal;try{const fixedOptions=this.snapshotOptions(options);requested=!0,feedback.requested(mode,requestedContextId);const structure=this.#built;if(!structure)throw new Error("Runner must be built before running");let result;return this.#entry.running?result=await runEntry(this.#entry,structure,request,fixedOptions,change=>this.publish(change,feedback)):(externalSignal=fixedOptions.signal,cancellation=new RunnerCancellation(externalSignal),this.#cancellation=cancellation,result=await runEntry(this.#entry,structure,request,fixedOptions,change=>this.publish(change,feedback),{signal:cancellation.signal,output:this.#outputs.forEntry(feedback.id),feedback:feedback.receivers(cancellation.signal),created:feedback.created})),feedback.settled("succeeded"),result}catch(error){requested||feedback.requested(mode,requestedContextId);const delivered=cancellation?cancellation.deliveryError(error):error,cancelled=cancellation&&(isInvocationCancelled(delivered,cancellation.signal)||externalSignal&&isInvocationCancelled(delivered,externalSignal));throw feedback.settled(cancelled?"cancelled":"failed",delivered),delivered}finally{cancellation?.dispose(),this.#cancellation===cancellation&&(this.#cancellation=void 0)}}snapshotOptions(options){return Object.freeze({...options})}publish(change,feedback){feedback?.entry(change);const fault=this.#observation.publish(Object.freeze({...change,driverId:this.id,sequence:++this.#sequence,occurredAt:this.#clock.now()}));if(!isUndefined(fault))throw fault}}export{Runner};

package/dist/structure/builder.d.ts

@@ -0,0 +1,12 @@
+import type { Resources } from '../resource/resources.js';
+import type { CallableCallsOptions } from '../binding/calls.js';
+import type { Interactions } from '@weiliang0121/capix-interaction';
+import type { AnyCallable } from '../binding/declarations.js';
+import { type InvocationCapabilities } from '../construction/capabilities.js';
+import type { BuiltCallable } from './construction.js';
+export declare class CallableBuilder {
+    private readonly binder;
+    private readonly capabilities;
+    constructor(capabilities?: InvocationCapabilities);
+    build<Structure extends AnyCallable, Options extends object>(structure: Structure, resources: Resources<Options>, interactions?: Interactions, options?: CallableCallsOptions<Options>): BuiltCallable<Structure, Options>;
+}

package/dist/structure/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{CallableBinder}from"../binding/callable.js";import{snapshotInvocationCapabilities}from"../construction/capabilities.js";import{installCallable}from"./install.js";class CallableBuilder{static{__name(this,"CallableBuilder")}binder;capabilities;constructor(capabilities={}){this.capabilities=snapshotInvocationCapabilities(capabilities),this.binder=new CallableBinder(this.capabilities)}build(structure,resources,interactions,options={}){return installCallable(structure,this.capabilities,()=>this.binder.bind(structure,resources,interactions,options))}}export{CallableBuilder};

package/dist/structure/construction.d.ts

@@ -0,0 +1,22 @@
+import type { AnyCallable } from '../binding/declarations.js';
+import type { CallableBinding } from '../binding/contract.js';
+import type { CallInstallation } from '../binding/calls.js';
+import type { CallableInvocationBuilder } from '../construction/invocation.js';
+declare const builtOptions: unique symbol;
+export type BuiltCallable<Structure extends AnyCallable, Options = unknown> = Structure & {
+    readonly [builtOptions]: (options: Options) => Options;
+};
+export type AnyBuiltCallable = AnyCallable & {
+    readonly [builtOptions]: (options: never) => unknown;
+};
+export type BuiltOptions<Structure> = Structure extends {
+    readonly [builtOptions]: (options: infer Options) => unknown;
+} ? Options : never;
+export interface CallableConstruction {
+    readonly binding: CallableBinding<any, any, object>;
+    readonly calls: CallInstallation<any>;
+    readonly invocations: CallableInvocationBuilder;
+}
+export declare function callableConstruction(structure: AnyCallable): CallableConstruction;
+export declare function installCallableConstruction(structure: AnyCallable, value: CallableConstruction): void;
+export {};

package/dist/structure/construction.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});const construction=Symbol("callable-construction");function callableConstruction(structure){if(!Object.hasOwn(structure,construction))throw new Error("Callable structure has not been built");return structure[construction]}__name(callableConstruction,"callableConstruction");function installCallableConstruction(structure,value){Object.defineProperty(structure,construction,{value:Object.freeze(value)})}__name(installCallableConstruction,"installCallableConstruction");export{callableConstruction,installCallableConstruction};

package/dist/structure/install.d.ts

@@ -0,0 +1,5 @@
+import type { AnyCallable } from '../binding/declarations.js';
+import { type BuiltCallable } from './construction.js';
+import type { CallableBuildPlan } from '../binding/callable.js';
+import type { InvocationCapabilities } from '../construction/capabilities.js';
+export declare function installCallable<Structure extends AnyCallable, Options>(structure: Structure, capabilities: InvocationCapabilities, resolve: () => CallableBuildPlan<Structure, Options>): BuiltCallable<Structure, Options>;

package/dist/structure/install.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{types}from"node:util";import{BoundChildren}from"../binding/children/bound.js";import{InvocationWorkBinding}from"../binding/work.js";import{Callable}from"@weiliang0121/capix-structure";import{CallableInvocationBuilder}from"../construction/invocation.js";import{assertStructureConfigurable,beginStructureBuild,endStructureBuild,lockStructureConfiguration,structureParent}from"@weiliang0121/capix-structure/construction";import{installCallableConstruction}from"./construction.js";function installCallable(structure,capabilities,resolve){const tree=checkTree(structure),reserved=new Set(tree),original=tree.map(structure2=>({structure:structure2,descriptors:Object.getOwnPropertyDescriptors(structure2)}));for(const current of tree)beginStructureBuild(current);try{const{root,calls}=resolve(),invocations=new CallableInvocationBuilder(capabilities),prepared=[],prepare=__name(node=>{if(!reserved.delete(node.definition))throw new Error("Callable membership changed while building");for(const member of node.members)if(structureParent(member.definition)!==node.definition)throw new Error("Callable membership changed while building");const children=new BoundChildren(node.members,node.declaration.names),composite=node.declaration.members!==void 0,work=new InvocationWorkBinding(node.declaration,children,composite),binding=Object.freeze({definition:node.definition,declaration:node.declaration,observations:node.observations,children,composite,deps:node.deps,supply:node.supply,refinements:node.refinements,work}),fields={};for(const[key,value]of Object.entries(node.declaration)){if(key==="kind"||key==="members"||key==="names")continue;const existing=Object.getOwnPropertyDescriptor(node.definition,key);if(existing&&!existing.configurable)throw new Error(`Callable configuration field cannot be fixed: ${key}`);fields[key]={value,enumerable:!0,writable:!1,configurable:!1}}for(const key of["id","kind",...composite?["members","names"]:[]]){const existing=Object.getOwnPropertyDescriptor(node.definition,key),value=key==="id"?node.definition.id:key==="kind"?node.declaration.kind:key==="members"?node.declaration.members:node.declaration.names,fixed=existing&&"value"in existing&&!existing.writable&&existing.value===value;if(existing&&!existing.configurable&&!fixed)throw new Error(`Callable structure field cannot be fixed: ${key}`);(!existing||existing.configurable)&&(fields[key]={value,enumerable:!0,writable:!1,configurable:!1})}prepared.push({structure:node.definition,construction:{binding,calls,invocations},fields});for(const member of node.members)prepare(member)},"prepare");if(prepare(root),reserved.size)throw new Error("Callable membership changed while building");for(const{structure:structure2,descriptors}of original){if(!Object.isExtensible(structure2))throw new Error("Callable structure changed while building");for(const key of configurationFields){const before=descriptors[key],after=Object.getOwnPropertyDescriptor(structure2,key);if(!sameDescriptor(before,after))throw new Error(`Callable configuration changed while building: ${key}`)}}for(const item of prepared)Object.defineProperties(item.structure,item.fields),installCallableConstruction(item.structure,item.construction),lockStructureConfiguration(item.structure);return structure}finally{for(const current of tree)endStructureBuild(current)}}__name(installCallable,"installCallable");function checkTree(root){const seen=new Set,visit=__name((structure,parent)=>{if(types.isProxy(structure))throw new TypeError("Callable structures cannot be proxies");if(!(structure instanceof Callable))throw new TypeError("Callable structure must be a Scene, Group or Node");if(assertStructureConfigurable(structure),!Object.isExtensible(structure))throw new Error("Callable structure must allow construction before build");if(structureParent(structure)!==parent)throw new Error("Callable structure has another parent or unregistered membership");if(seen.has(structure))throw new Error("Callable structure occurs more than once");if(seen.add(structure),structure.kind!=="node"){if(!structure.members)throw new TypeError("Composite structures must provide their members");for(const member of structure.members)visit(member,structure)}},"visit");return visit(root),[...seen]}__name(checkTree,"checkTree");const configurationFields=["id","kind","members","names","name","label","source","output","deps","run","checkpoint"];function sameDescriptor(before,after){return!before||!after?before===after:before.value===after.value&&before.get===after.get&&before.set===after.set&&before.writable===after.writable&&before.enumerable===after.enumerable&&before.configurable===after.configurable}__name(sameDescriptor,"sameDescriptor");export{installCallable};

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@weiliang0121/capix-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./construction": {
+      "types": "./dist/construction.d.ts",
+      "import": "./dist/construction.js"
+    },
+    "./recording": {
+      "types": "./dist/recording.d.ts",
+      "import": "./dist/recording.js"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "1.52.0",
+    "@weiliang0121/capix-protocol": "0.1.0",
+    "@weiliang0121/capix-structure": "0.1.0",
+    "@weiliang0121/capix-resources": "0.1.0",
+    "@weiliang0121/capix-changes": "0.1.0",
+    "@weiliang0121/capix-contracts": "0.1.0",
+    "@weiliang0121/capix-records": "0.1.0",
+    "@weiliang0121/capix-checkpoint": "0.1.0",
+    "@weiliang0121/capix-invocation": "0.1.0",
+    "@weiliang0121/capix-diagnostics": "0.1.0",
+    "@weiliang0121/capix-interaction": "0.1.0"
+  },
+  "description": "Structure binding, resource assembly, and Runner for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "server/runtime"
+  },
+  "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"
+  }
 }