@weiliang0121/capix-invocation 0.0.0-stage → 0.1.0

package/dist/invocation/reception.js

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

package/dist/invocation/relation.d.ts

@@ -0,0 +1,93 @@
+import type { CheckpointBinding } from '../checkpoint/work.js';
+import { type Stable, type InvocationIdentity } from '@weiliang0121/capix-contracts';
+import type { InvocationOutputReceiver, RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+import type { InvocationRelationChange } from '../observation/facts.js';
+import type { InvocationFailure } from './failure.js';
+import type { InvocationRelationView, InvocationView } from './view.js';
+import type { InvocationContext } from '../context/context.js';
+import type { InvocationResult } from './result.js';
+import type { InvocationPropagationScope } from './provenance.js';
+import type { InvocationReceptionBinding } from './reception.js';
+export interface InvocationRelationOptions {
+    key?: string;
+    declarationPosition?: number;
+    output?: InvocationOutputReceiver<any, any>;
+    receiveFailure?: boolean;
+}
+export interface InvocationTarget<Output = unknown> {
+    readonly context: InvocationContext<unknown, Output>;
+    run(): Promise<Stable<Output>>;
+    readonly view?: InvocationView;
+    readonly callView?: InvocationView & {
+        run(): Promise<Stable<Output>>;
+    };
+    readonly checkpointBinding?: CheckpointBinding;
+    readonly identity?: InvocationIdentity;
+}
+export type InvocationRelationReception = Readonly<{
+    status: 'pending';
+} | ({
+    readonly contract?: InvocationReceptionBinding;
+} & ({
+    status: 'receiving';
+} | {
+    status: 'accepted' | 'handled';
+    output: unknown;
+} | {
+    status: 'failed';
+    error: unknown;
+    failure?: InvocationFailure;
+    diagnostic?: Stable<RuntimeErrorValue>;
+}))>;
+export interface InvocationRelationBaseline<Output = unknown> {
+    readonly returned?: InvocationResult<Output>;
+    readonly reception: InvocationRelationReception;
+}
+export interface InvocationRelationOwner {
+    changing?(): void;
+    requireHealthy(): void;
+    accepting<Value>(work: () => Promise<Value>): Promise<Value>;
+    fail(failure: InvocationFailure): void;
+    publish(relation: InvocationRelation, change: InvocationRelationChange): unknown | undefined;
+    receive<Value>(relation: InvocationRelation, work: () => Promise<Value>): Promise<Value>;
+    captureDelivery(): InvocationPropagationScope;
+    receptionFailure(relation: InvocationRelation, error: unknown, scope: InvocationPropagationScope): {
+        error: unknown;
+        failure: InvocationFailure;
+        delivery: unknown;
+    };
+}
+export interface InvocationRelationSetup<Output = unknown> {
+    readonly target: InvocationTarget<Output>;
+    readonly round: number;
+    readonly order: number;
+    readonly key?: string;
+    readonly declarationPosition?: number;
+    readonly receiveFailure?: boolean;
+}
+export declare class InvocationRelation<Output = unknown> {
+    #private;
+    private readonly owner;
+    readonly view: InvocationRelationView;
+    private target;
+    readonly round: number;
+    readonly order: number;
+    readonly key?: string;
+    readonly declarationPosition?: number;
+    constructor(identity: InvocationRelationSetup<Output>, owner: InvocationRelationOwner);
+    get receiveFailure(): boolean;
+    receiveFailures(): void;
+    get invocation(): InvocationTarget<Output>;
+    install(target: InvocationTarget<Output>, state: InvocationRelationBaseline<Output>): void;
+    replace(target: InvocationTarget<Output>): void;
+    get returned(): InvocationResult<Output> | undefined;
+    get reception(): InvocationRelationReception;
+    returnedWith(result: InvocationResult<Output>): void;
+    private fixedResult;
+    accept<Value>(work: (delivered: Stable<Output>) => Value | Stable<Value> | Promise<Value | Stable<Value>>, contract?: InvocationReceptionBinding): Promise<Stable<Value>>;
+    handle<Value>(work: (failure: unknown) => Value | Stable<Value> | Promise<Value | Stable<Value>>, contract?: InvocationReceptionBinding): Promise<Stable<Value>>;
+    private acceptResult;
+    private beginReception;
+    private receiveWithinParent;
+    private completeReception;
+}

package/dist/invocation/relation.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{stableValue}from"@weiliang0121/capix-contracts";import{combineFaults}from"@weiliang0121/capix-changes";import{failureDiagnostic}from"./failure.js";import{InvocationStopped}from"./stop.js";class InvocationRelation{static{__name(this,"InvocationRelation")}owner;#returned;#restoredReception=!1;view;#reception=Object.freeze({status:"pending"});target;round;order;key;declarationPosition;#receiveFailure;constructor(identity,owner){this.owner=owner,this.target=identity.target,this.round=identity.round,this.order=identity.order,this.key=identity.key,this.declarationPosition=identity.declarationPosition,this.#receiveFailure=identity.receiveFailure??!1;const relation=this;this.view=Object.freeze({get invocation(){if(!relation.invocation.view)throw new Error("Child invocation has no business view");return relation.invocation.view},round:this.round,key:this.key,get returned(){return relation.returned},get reception(){return relation.reception}})}get receiveFailure(){return this.#receiveFailure}receiveFailures(){if(this.owner.requireHealthy(),this.#returned||this.#reception.status!=="pending")throw new Error("Failure reception must be chosen before child execution");this.owner.changing?.(),this.#receiveFailure=!0}get invocation(){return this.target}install(target,state){this.owner.changing?.();const returned=state.returned?this.fixedResult(state.returned):void 0,reception=state.reception.status==="accepted"||state.reception.status==="handled"?{...state.reception,output:stableValue(state.reception.output)}:state.reception.status==="failed"?{...state.reception,diagnostic:state.reception.diagnostic?stableValue(state.reception.diagnostic):failureDiagnostic(state.reception.error)}:state.reception;this.owner.changing?.(),this.target=target,this.#restoredReception=state.reception.status==="receiving",this.#returned=returned,this.#reception=Object.freeze(reception)}replace(target){this.owner.changing?.(),this.target=target}get returned(){return this.#returned}get reception(){return this.#reception}returnedWith(result){if(this.owner.changing?.(),this.#returned)throw new Error("Child invocation has already returned");const fixed=this.fixedResult(result);if(this.owner.changing?.(),this.#returned)throw new Error("Child invocation has already returned");this.#returned=fixed,result.status==="failed"&&result.failure&&(!this.receiveFailure||!result.failure.receptionAllowed)&&this.owner.fail(result.failure),this.owner.publish(this,{kind:"returned",result:this.#returned})}fixedResult(result){return Object.freeze(result.status==="succeeded"?{...result,output:stableValue(result.output)}:{...result,diagnostic:result.diagnostic?stableValue(result.diagnostic):failureDiagnostic(result.error)})}accept(work,contract){try{return this.owner.accepting(()=>this.acceptResult(work,contract))}catch(error){return Promise.reject(error)}}handle(work,contract){try{return this.owner.accepting(async()=>{if(!this.receiveFailure||this.#returned?.status!=="failed"||!this.#returned.failure?.receptionAllowed)throw new Error("Child has no receivable failed delivery");const scope=this.owner.captureDelivery(),failure=this.#returned.error;this.beginReception(contract,!0);const output=await this.receiveWithinParent(failure,work,scope,contract);this.owner.changing?.(),this.#reception=Object.freeze({status:"handled",output,...contract?{contract}:{}});const observed=this.owner.publish(this,{kind:"handled",output});if(observed!==void 0)throw observed;return output})}catch(error){return Promise.reject(error)}}async acceptResult(work,contract){const scope=this.owner.captureDelivery();if(this.#returned?.status!=="succeeded")throw new Error("Child invocation has not returned successfully");const delivered=this.#returned.output;this.beginReception(contract);const output=await this.receiveWithinParent(delivered,work,scope,contract);return this.completeReception(output,contract),output}beginReception(contract,failed=!1){if(this.owner.requireHealthy(),!this.#returned||(failed?this.#returned.status!=="failed":this.#returned.status!=="succeeded"))throw new Error("Child invocation has not returned the expected outcome");if(contract&&contract.childPosition!==this.declarationPosition)throw new Error("Reception contract belongs to a different child position");if(this.#reception.status!=="pending"&&!this.#restoredReception)throw new Error("Child result has already entered acceptance");if(this.#restoredReception&&this.#reception.status==="receiving"&&this.#reception.contract!==contract)throw new Error("Restored reception contract cannot be replaced");this.owner.changing?.(),this.#restoredReception=!1,this.#reception=Object.freeze({status:"receiving",...contract?{contract}:{}});const observed=this.owner.publish(this,{kind:"receiving"});if(observed!==void 0){this.owner.changing?.();const diagnostic=failureDiagnostic(observed);this.owner.changing?.(),this.#reception=Object.freeze({status:"failed",error:observed,diagnostic,...contract?{contract}:{}});const failed2=this.owner.publish(this,{kind:"failed",error:observed,source:"observation"});throw combineFaults([observed,...failed2!==void 0?[failed2]:[]])}}async receiveWithinParent(delivered,work,scope,contract){try{return this.owner.requireHealthy(),await this.owner.receive(this,async()=>{const candidate=await work(delivered);this.owner.changing?.();const value=stableValue(candidate);try{const checked=contract?.check(value);if(checked!==null&&(typeof checked=="object"||typeof checked=="function")&&typeof Reflect.get(checked,"then")=="function")throw Promise.resolve(checked).catch(()=>{}),new TypeError("Reception checks must return synchronously")}catch(cause){throw new InvocationStopped("RECEPTION_CONTRACT","Parent reception value violates its contract",void 0,{cause})}return value})}catch(error){const rejected=this.owner.receptionFailure(this,error,scope);this.owner.changing?.();const diagnostic=failureDiagnostic(rejected.error);this.owner.changing?.(),this.#reception=Object.freeze({status:"failed",error:rejected.error,failure:rejected.failure,diagnostic,...contract?{contract}:{}});const failed=this.owner.publish(this,{kind:"failed",error:rejected.error,source:"work"});throw failed!==void 0?new AggregateError([rejected.error,failed],"Child acceptance and observation both failed",{cause:rejected.error}):rejected.delivery}}completeReception(output,contract){this.owner.changing?.(),this.#reception=Object.freeze({status:"accepted",output,...contract?{contract}:{}});const accepted=this.owner.publish(this,{kind:"accepted",output});if(accepted!==void 0)throw accepted}}export{InvocationRelation};

package/dist/invocation/resource-access.d.ts

@@ -0,0 +1,31 @@
+import { ResourceRequest, ResourceSupply, type ResourceOwner, type ResourceRequirements, type ResourceRefinement, type ResourceSupplyEntry } from '@weiliang0121/capix-resources';
+import type { OperationOutcome } from '@weiliang0121/capix-contracts';
+export interface InvocationResourceOwner extends ResourceOwner {
+    readonly round?: () => number;
+}
+export declare class InvocationResources<Resources extends object = object> {
+    #private;
+    readonly supply: ResourceSupply;
+    readonly values: Readonly<Resources>;
+    constructor(deps: ResourceRequirements<Resources>, entries?: readonly ResourceSupplyEntry[], initial?: ResourceRequirements, supply?: ResourceRequirements);
+    view<Values extends object>(deps: ResourceRequirements<Values>, phase?: string): Readonly<Values>;
+    private namedView;
+    restrict(validate: () => void): void;
+    attach(owner: InvocationResourceOwner): void;
+    start(phase?: string): void;
+    activate(phase: string, deps: ResourceRequirements): void;
+    close(phase: string): void;
+    closeAll(): void;
+    closeAllResult(): OperationOutcome<void>;
+    select<Values extends object, Input = unknown>(deps: ResourceRequirements<Values>, initial?: ResourceRequirements, selection?: {
+        readonly input: Input;
+        readonly refinements: readonly ResourceRefinement<Input>[];
+        readonly supply?: ResourceRequirements;
+    }): InvocationResources<Values>;
+    supplement(others: readonly InvocationResources[]): InvocationResources;
+    provides(request: ResourceRequest<unknown>): boolean;
+    private round;
+    private window;
+    private validateWindow;
+    private first;
+}

package/dist/invocation/resource-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});import{ResourceAccess,ResourceAccessClosed,captureResourceOwner,ResourceRequest,ResourceSupply,checkResourceRequests,resourceRequests}from"@weiliang0121/capix-resources";class InvocationResources{static{__name(this,"InvocationResources")}supply;values;#requirements;#initial;#windows=new Map;#phaseRequirements=new Map;#closed=new Set;#bound=new Set;#available=new Set;#owner;#restriction;#started=!1;#phase="run";#ended=!1;constructor(deps,entries=[],initial=deps,supply=deps){this.supply=new ResourceSupply(entries).select(supply),this.#requirements=Object.freeze({...deps}),this.#initial=Object.freeze({...initial}),this.#phaseRequirements.set("run",this.#initial),this.values=this.view(initial)}view(deps,phase="run"){const fixed=Object.freeze({...deps});checkResourceRequests(this.#requirements,resourceRequests(fixed)),this.supply.select(fixed);let round=this.#owner?this.round():void 0;return this.namedView(fixed,phase,()=>round??=this.round())}namedView(deps,phase,round){const values={};let endpoints;for(const name of Object.keys(deps))Object.defineProperty(values,name,{enumerable:!0,get:__name(()=>{const access=this.window(phase,round(),deps);return(endpoints??=access.view(deps))[name]},"get")});return Object.freeze(values)}restrict(validate){if(this.#restriction||this.#owner||this.#started||this.#windows.size||this.#ended)throw new Error("Resource access is already established");this.#restriction=validate}attach(owner){if(this.#owner||this.#started||this.#windows.size||this.#ended)throw new Error("Resource access is already established");const fixed=captureResourceOwner(owner);if(!fixed)throw new TypeError("Invocation resource owner is required");this.#owner=Object.freeze({...fixed,round:owner.round?.bind(owner)})}start(phase="run"){if(this.#started||this.#ended)throw new Error("Resource access has already started");this.#started=!0,this.activate(phase,this.#initial)}activate(phase,deps){if(!this.#started)throw new Error("Resource access requires a started invocation");if(this.#ended)throw new ResourceAccessClosed;checkResourceRequests(this.#requirements,resourceRequests(deps)),this.#phase!==phase&&this.close(this.#phase),this.#phase=phase,this.#phaseRequirements.set(phase,Object.freeze({...deps})),this.window(phase,this.round(),deps).view(deps)}close(phase){const key=`${phase}:${this.round()}`;this.#closed.add(key),this.#windows.get(key)?.close()}closeAll(){const result=this.closeAllResult();if(result.status==="failed")throw result.failure}closeAllResult(){this.#ended=!0;const failures=[];for(const window of this.#windows.values())try{window.close()}catch(failure){failures.push(failure)}return failures.length?{status:"failed",failure:failures.length===1?failures[0]:new AggregateError(failures,"Invocation resource windows failed to close",{cause:failures[0]})}:{status:"succeeded",value:void 0}}select(deps,initial=deps,selection){let supply=this.supply.select(selection?.supply??deps);return selection?.refinements.length&&(supply=supply.refine(selection.input,selection.refinements)),new InvocationResources(deps,supply.entries,initial,selection?.supply)}supplement(others){const entries=[...this.supply.entries];for(const other of others)for(const entry of other.supply.entries){const previous=entries.find(candidate=>candidate.offer===entry.offer);if(previous&&previous!==entry)throw new Error(`Ambiguous resource supply: ${entry.offer.name}`);previous||entries.push(entry)}const requests=Object.fromEntries(entries.map((entry,index)=>[String(index),new ResourceRequest(entry.offer)]));return new InvocationResources(requests,entries)}provides(request){return this.supply.entries.some(entry=>entry.offer===request.offer)}round(){return Math.max(1,this.#owner?.round?.()??1)}window(phase,round,deps){const key=`${phase}:${round}`;this.validateWindow(phase,round,key);const existing=this.#windows.get(key);if(existing)return existing;const access=new ResourceAccess(this.#phaseRequirements.get(phase)??deps,this.supply,this.#owner,{validate:__name(()=>this.validateWindow(phase,round,key),"validate"),bound:__name(entry=>this.first(this.#bound,entry),"bound"),available:__name(entry=>this.first(this.#available,entry),"available")});this.#windows.set(key,access);try{return access.start(),access}catch(error){throw access.close(),this.#closed.add(key),error}}validateWindow(phase,round,key){try{if(this.#ended||this.#closed.has(key))throw new ResourceAccessClosed;if(this.#owner&&!this.#started)throw new Error("Resource access requires a started invocation");if(phase!==this.#phase)throw new ResourceAccessClosed("Resource access belongs to an inactive declaration phase");if(round!==this.round())throw new ResourceAccessClosed("Resource access belongs to an inactive declaration round");this.#restriction?.()}catch(error){throw this.#owner?.error?.(error),error}}first(entries,entry){return entries.has(entry)?!1:(entries.add(entry),!0)}}export{InvocationResources};

package/dist/invocation/resources.d.ts

@@ -0,0 +1,8 @@
+import { InvocationResources } from './resource-access.js';
+import type { InvocationContext } from '../context/context.js';
+import type { ResourceFailurePolicy } from '@weiliang0121/capix-resources';
+import type { Invocation } from './invocation.js';
+export declare const invocationResourceFailures: ResourceFailurePolicy;
+export declare function attachInvocationResources<Input, Output, Context extends InvocationContext<Input, Output> & {
+    readonly signal: AbortSignal;
+}>(invocation: Invocation<Input, Output, Context>, resources: InvocationResources): void;

package/dist/invocation/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"./resource-access.js";import{isProtectedOperationFailure}from"../operation/failure.js";import{RuntimeErrorHelper}from"@weiliang0121/capix-diagnostics";import{isInvocationCancelled}from"./cancellation.js";const invocationResourceFailures=Object.freeze({isProtected:isProtectedOperationFailure,isCancellation:isInvocationCancelled,describe:RuntimeErrorHelper.format});function attachInvocationResources(invocation,resources){resources.attach({contextId:invocation.context.id,failures:invocationResourceFailures,signal:invocation.context.signal,round:__name(()=>invocation.context.progress.round,"round"),reception:__name(()=>invocation.children.reception,"reception"),nextSequence:__name(()=>invocation.nextResourceSequence(),"nextSequence"),validate:__name(()=>invocation.requireActive(),"validate"),observation:invocation.observation?.resource,transcript:invocation.observation?.transcript,memory:invocation.observation?.memory,error:__name((error,allowException)=>invocation.reject(error,allowException),"error")})}__name(attachInvocationResources,"attachInvocationResources");export{attachInvocationResources,invocationResourceFailures};

package/dist/invocation/result.d.ts

@@ -0,0 +1,12 @@
+import type { InvocationFailure } from './failure.js';
+import type { RuntimeErrorValue, Stable } from '@weiliang0121/capix-contracts';
+export type InvocationResult<Output> = Readonly<{
+    status: 'succeeded';
+    output: Stable<Output>;
+} | {
+    status: 'failed';
+    error: unknown;
+    failure?: InvocationFailure;
+    diagnostic?: Stable<RuntimeErrorValue>;
+}>;
+export declare function receiveResult<Output>(result: InvocationResult<Output>): Stable<Output>;

package/dist/invocation/result.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 receiveResult(result){if(result.status==="failed")throw result.error;return result.output}__name(receiveResult,"receiveResult");export{receiveResult};

package/dist/invocation/stop.d.ts

@@ -0,0 +1,3 @@
+import { RuntimeError } from '@weiliang0121/capix-contracts';
+export declare class InvocationStopped extends RuntimeError {
+}

package/dist/invocation/stop.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{RuntimeError}from"@weiliang0121/capix-contracts";class InvocationStopped extends RuntimeError{static{__name(this,"InvocationStopped")}}export{InvocationStopped};

package/dist/invocation/view.d.ts

@@ -0,0 +1,30 @@
+import type { Stable } from '@weiliang0121/capix-contracts';
+import type { InvocationFailure } from './failure.js';
+import type { InvocationContextView } from '../context/view.js';
+import type { InvocationResult } from './result.js';
+import type { InvocationRelationReception } from './relation.js';
+export interface InvocationRelationView {
+    readonly invocation: InvocationView;
+    readonly round: number;
+    readonly key?: string;
+    readonly returned: InvocationResult<unknown> | undefined;
+    readonly reception: InvocationRelationReception;
+}
+export interface InvocationView<Input = unknown, Output = unknown, ContextView extends InvocationContextView<Input, Output> = InvocationContextView<Input, Output>> {
+    readonly context: ContextView;
+    readonly origin: Readonly<{
+        contextId: string;
+    }>;
+    readonly sequence: number;
+    readonly failure?: InvocationFailure;
+    readonly children: {
+        get(invocation: InvocationView): InvocationRelationView;
+        values(): readonly InvocationRelationView[];
+    };
+}
+export interface ChildInvocationView<Input = unknown, Output = unknown, ContextView extends InvocationContextView<Input, Output> = InvocationContextView<Input, Output>> extends InvocationView<Input, Output, ContextView> {
+    run(): Promise<Stable<Output>>;
+}
+export type InvocationViewSource = Pick<InvocationView, 'origin' | 'sequence' | 'failure' | 'children'>;
+export declare function invocationView<Input, Output, Context extends InvocationContextView<Input, Output>>(source: InvocationViewSource, context: Context): InvocationView<Input, Output, Context>;
+export declare function childInvocationView<Input, Output, Context extends InvocationContextView<Input, Output>>(source: InvocationViewSource, context: Context, run: () => Promise<Stable<Output>>): ChildInvocationView<Input, Output, Context>;

package/dist/invocation/view.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 viewProperties(source,context){return{context,origin:source.origin,get sequence(){return source.sequence},get failure(){return source.failure},children:source.children}}__name(viewProperties,"viewProperties");function invocationView(source,context){return Object.freeze(viewProperties(source,context))}__name(invocationView,"invocationView");function childInvocationView(source,context,run){return Object.freeze(Object.assign(viewProperties(source,context),{run}))}__name(childInvocationView,"childInvocationView");export{childInvocationView,invocationView};

package/dist/invocation/work.d.ts

@@ -0,0 +1,31 @@
+import type { InvocationCheckpointWork } from '../checkpoint/work.js';
+import type { OperationOutcome, OutputDeclaration, Stable } from '@weiliang0121/capix-contracts';
+import type { Invocation } from './invocation.js';
+import type { InvocationContext } from '../context/context.js';
+import type { InvocationFailure } from './failure.js';
+export interface InvocationWork<Input, Output, Context extends InvocationContext<Input, Output>> {
+    readonly output?: OutputDeclaration<Output, unknown>;
+    readonly checkpoint?: InvocationCheckpointWork<Input, Output, Context>;
+    execute(context: Context, invocation: Invocation<Input, Output, Context>): Output | Stable<Output> | Promise<Output | Stable<Output>>;
+    close?(context: Context, invocation: Invocation<Input, Output, Context>): OperationOutcome<void>;
+}
+export type InvocationProcess = {
+    stage: 'execute';
+    type: 'start';
+    input: unknown;
+} | {
+    stage: 'execute';
+    type: 'return';
+    output: unknown;
+} | {
+    stage: 'execute';
+    type: 'throw';
+    error: unknown;
+    failure?: InvocationFailure;
+};
+export interface InvocationExecutionWork<Output> {
+    readonly output?: OutputDeclaration<Output, unknown>;
+    execute(): Output | Stable<Output> | Promise<Output | Stable<Output>>;
+    close(): OperationOutcome<void>;
+}
+export declare function connectInvocationWork<Input, Output, Context extends InvocationContext<Input, Output>>(work: InvocationWork<Input, Output, Context>, context: Context, invocation: Invocation<Input, Output, Context>): InvocationExecutionWork<Output>;

package/dist/invocation/work.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{InvocationStopped}from"./stop.js";function connectInvocationWork(work,context,invocation){return{output:work.output,execute:__name(()=>work.execute(context,invocation),"execute"),close:__name(()=>closeInvocationWork(work,context,invocation),"close")}}__name(connectInvocationWork,"connectInvocationWork");function closeInvocationWork(work,context,invocation){try{if(work.close===void 0)return{status:"succeeded",value:void 0};const result=work.close(context,invocation);if(result&&typeof result=="object"&&"then"in result)throw Promise.resolve(result).catch(()=>{}),new InvocationStopped("INVALID_WORK_CLOSE","Work close must return a synchronous outcome");if(!result||typeof result!="object"||!("status"in result))throw new InvocationStopped("INVALID_WORK_CLOSE","Work close must return an outcome");if(result.status==="succeeded"&&"value"in result&&result.value===void 0)return{status:"succeeded",value:void 0};if(result.status==="failed"&&"failure"in result)return{status:"failed",failure:result.failure};throw new InvocationStopped("INVALID_WORK_CLOSE","Work close returned an invalid outcome")}catch(failure){return{status:"failed",failure}}}__name(closeInvocationWork,"closeInvocationWork");export{connectInvocationWork};

package/dist/observation/error.d.ts

@@ -0,0 +1,4 @@
+export declare class ObservationError extends Error {
+    readonly code = "OBSERVATION_FAILED";
+    constructor(cause: unknown);
+}

package/dist/observation/error.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 ObservationError extends Error{static{__name(this,"ObservationError")}code="OBSERVATION_FAILED";constructor(cause){super("Observation failed",{cause}),this.name="ObservationError"}}export{ObservationError};

package/dist/observation/facts.d.ts

@@ -0,0 +1,64 @@
+import type { InvocationRelationIdentity } from '@weiliang0121/capix-protocol';
+import type { BusinessEvent } from '@weiliang0121/capix-contracts';
+import type { InvocationIdentity } from '@weiliang0121/capix-contracts';
+import type { ContextState } from '../context/context.js';
+import type { InvocationProcess } from '../invocation/work.js';
+import type { InvocationResult } from '../invocation/result.js';
+import type { InvocationFailure } from '../invocation/failure.js';
+export type { InvocationRelationIdentity } from '@weiliang0121/capix-protocol';
+export type { InvocationIdentity } from '@weiliang0121/capix-contracts';
+export interface InvocationDescription {
+    readonly role?: string;
+    readonly id?: string;
+    readonly name?: string;
+    readonly label?: string;
+    readonly source?: string;
+    readonly callee?: string;
+}
+export type InvocationRelationChange = {
+    readonly kind: 'attached';
+} | {
+    readonly kind: 'returned';
+    readonly result: InvocationResult<unknown>;
+} | {
+    readonly kind: 'receiving';
+} | {
+    readonly kind: 'accepted' | 'handled';
+    readonly output: unknown;
+} | {
+    readonly kind: 'failed';
+    readonly error: unknown;
+    readonly source: 'work' | 'observation';
+    readonly failure?: InvocationFailure;
+};
+export type InvocationChange = {
+    readonly kind: 'started';
+    readonly input: unknown;
+} | {
+    readonly kind: 'process';
+    readonly process: InvocationProcess;
+    readonly processSequence: number;
+    readonly round: number;
+} | {
+    readonly kind: 'relation';
+    readonly relation: InvocationRelationIdentity;
+    readonly change: InvocationRelationChange;
+} | {
+    readonly kind: 'finished';
+    readonly state: ContextState<unknown>;
+};
+export type InvocationFact = InvocationChange & {
+    readonly identity: InvocationIdentity;
+    readonly description?: InvocationDescription;
+    readonly eventSequence: number;
+    readonly occurredAt: string;
+    readonly monotonicTime: number;
+};
+export type { ResourceObservation } from '@weiliang0121/capix-resources';
+export type { BusinessEvent } from '@weiliang0121/capix-contracts';
+export interface BusinessObservation {
+    readonly identity: InvocationIdentity;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly event: Readonly<BusinessEvent>;
+}

package/dist/observation/facts.js

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

package/dist/observation/invocation.d.ts

@@ -0,0 +1,17 @@
+import type { TranscriptEvent, MemoryEvent } from '@weiliang0121/capix-protocol';
+import type { InvocationFact, ResourceObservation, BusinessObservation } from './facts.js';
+import type { EventConsumer } from '@weiliang0121/capix-changes';
+import type { InvocationObserver } from './observer.js';
+import { type ObserverSession } from './session.js';
+export declare class InvocationObservation {
+    #private;
+    constructor(sessions: readonly ObserverSession[], installed: ReadonlyMap<object, ObserverSession>);
+    observerFor(installation: object): InvocationObserver | undefined;
+    sessionFor(installation: object): ObserverSession | undefined;
+    publish(fact: InvocationFact): unknown | undefined;
+    readonly resource: EventConsumer<ResourceObservation>;
+    readonly business: EventConsumer<BusinessObservation>;
+    readonly transcript: EventConsumer<TranscriptEvent>;
+    readonly memory: EventConsumer<MemoryEvent>;
+    private dispatch;
+}

package/dist/observation/invocation.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{publishSessions}from"./session.js";class InvocationObservation{static{__name(this,"InvocationObservation")}#sessions;#installed;constructor(sessions,installed){this.#sessions=Object.freeze([...sessions]),this.#installed=new Map(installed)}observerFor(installation){const session=this.#installed.get(installation);return session?.available()?session.observer:void 0}sessionFor(installation){return this.#installed.get(installation)}publish(fact){return this.dispatch(observer=>observer.observe(fact))}resource={publish:__name(event=>this.dispatch(observer=>observer.resource?.(event)),"publish")};business={publish:__name(event=>this.dispatch(observer=>observer.business?.(event)),"publish")};transcript={publish:__name(event=>this.dispatch(observer=>observer.transcript?.(event)),"publish")};memory={publish:__name(event=>this.dispatch(observer=>observer.memory?.(event)),"publish")};dispatch(work){return publishSessions(this.#sessions,work)}}export{InvocationObservation};

package/dist/observation/observer.d.ts

@@ -0,0 +1,13 @@
+import { InvocationResources } from '../invocation/resource-access.js';
+import type { TranscriptEvent, MemoryEvent } from '@weiliang0121/capix-protocol';
+import type { InvocationFact, ResourceObservation, BusinessObservation } from './facts.js';
+export type { EventConsumer } from '@weiliang0121/capix-changes';
+export interface InvocationObserver {
+    readonly resources?: InvocationResources;
+    observe(fact: InvocationFact): void;
+    business?(fact: BusinessObservation): void;
+    resource?(fact: ResourceObservation): void;
+    transcript?(event: TranscriptEvent): void;
+    memory?(event: MemoryEvent): void;
+    available?(): boolean;
+}

package/dist/observation/observer.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import"../invocation/resource-access.js";

package/dist/observation/session.d.ts

@@ -0,0 +1,17 @@
+import type { InvocationObserver } from './observer.js';
+export declare class ObserverSession<Observer extends {
+    available?(): boolean;
+} = InvocationObserver> {
+    readonly observer: Observer;
+    readonly failure: 'isolate' | 'propagate';
+    private readonly invalidated?;
+    private readonly parent?;
+    active: boolean;
+    constructor(observer: Observer, failure: 'isolate' | 'propagate', invalidated?: ((error: unknown) => void) | undefined, parent?: ObserverSession | undefined);
+    available(): boolean;
+    stop(error: unknown): void;
+    publish(work: (observer: Observer) => unknown): unknown | undefined;
+}
+export declare function publishSessions<Observer extends {
+    available?(): boolean;
+}>(sessions: readonly ObserverSession<Observer>[], work: (observer: Observer) => unknown): unknown | undefined;

package/dist/observation/session.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{isUndefined}from"es-toolkit/predicate";import{ObservationError}from"./error.js";import{combineFaults}from"@weiliang0121/capix-changes";class ObserverSession{static{__name(this,"ObserverSession")}observer;failure;invalidated;parent;active=!0;constructor(observer,failure,invalidated,parent){this.observer=observer,this.failure=failure,this.invalidated=invalidated,this.parent=parent}available(){return this.active&&this.parent?.available()!==!1&&this.observer.available?.()!==!1}stop(error){this.active&&(this.active=!1,this.invalidated?.(error))}publish(work){if(this.active)try{if(!this.available()){this.active=!1;return}const value=work(this.observer);if(value&&typeof value.then=="function")throw Promise.resolve(value).catch(()=>{}),new TypeError("Observation must complete synchronously");return}catch(cause){this.active=!1;const error=new ObservationError(cause);return this.invalidated?.(error),this.failure==="propagate"?error:void 0}}}function publishSessions(sessions,work){const faults=[];for(const session of sessions){const fault=session.publish(work);isUndefined(fault)||faults.push(fault)}return combineFaults(faults)}__name(publishSessions,"publishSessions");export{ObserverSession,publishSessions};

package/dist/operation/failure.d.ts

@@ -0,0 +1 @@
+export declare function isProtectedOperationFailure(error: unknown): boolean;

package/dist/operation/failure.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{InvocationStopped}from"../invocation/stop.js";import{ObservationError}from"../observation/error.js";import{ChangeCaptureError}from"@weiliang0121/capix-changes";import{PersistenceError}from"@weiliang0121/capix-diagnostics";import{ResourceAccessClosed,ResourcePortError}from"@weiliang0121/capix-resources";import{StableValueError}from"@weiliang0121/capix-contracts";function isProtectedOperationFailure(error){const pending=[error],visited=new Set;for(;pending.length;){const current=pending.pop();if(!(current===null||typeof current!="object"&&typeof current!="function"||visited.has(current))){visited.add(current);try{if(current instanceof StableValueError||current instanceof InvocationStopped||current instanceof ObservationError||current instanceof ChangeCaptureError||current instanceof PersistenceError||current instanceof ResourceAccessClosed||current instanceof ResourcePortError)return!0;if(!(current instanceof AggregateError))continue;const errors=Object.getOwnPropertyDescriptor(current,"errors");if(!errors||!("value"in errors)||!Array.isArray(errors.value))return!0;for(const[key,item]of Object.entries(Object.getOwnPropertyDescriptors(errors.value)))if(/^(0|[1-9]\d*)$/.test(key)){if(!("value"in item))return!0;pending.push(item.value)}}catch{return!0}}}return!1}__name(isProtectedOperationFailure,"isProtectedOperationFailure");export{isProtectedOperationFailure};

package/dist/output/delivery.d.ts

@@ -0,0 +1,2 @@
+import type { InvocationOutputReceiver } from '@weiliang0121/capix-contracts';
+export declare function combineOutputReceivers<Result, Delta = unknown>(...receivers: readonly (InvocationOutputReceiver<Result, Delta> | undefined)[]): InvocationOutputReceiver<Result, Delta> | undefined;

package/dist/output/delivery.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";function combineOutputReceivers(...receivers){const channels=receivers.filter(receiver=>receiver!==void 0).map(receiver=>new ProgressChannel(receiver));if(channels.length)return{receive:__name(event=>{for(const channel of channels)channel.publish(event)},"receive")}}__name(combineOutputReceivers,"combineOutputReceivers");export{combineOutputReceivers};

package/dist/output/section.d.ts

@@ -0,0 +1,21 @@
+import { ProgressChannel } from '@weiliang0121/capix-changes';
+import type { InvocationOutputEvent, InvocationOutputWriter, OutputDeclaration, Stable } from '@weiliang0121/capix-contracts';
+export declare class InvocationOutputSection<Result> {
+    #private;
+    readonly contextId: string;
+    readonly round: number;
+    private readonly declaration;
+    private readonly controls;
+    readonly writer: InvocationOutputWriter<unknown>;
+    constructor(contextId: string, round: number, declaration: OutputDeclaration<Result, unknown> | undefined, controls: {
+        active(): void;
+        reject(error: unknown): void;
+    }, delivery?: ProgressChannel<InvocationOutputEvent<Result>>);
+    start(): void;
+    private emit;
+    seal(): void;
+    discard(reason: 'exception' | 'continue' | 'failed'): void;
+    validateResult(value: Stable<Result>): Stable<Result>;
+    complete(result: Stable<Result>): void;
+    private publish;
+}

package/dist/output/section.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"@weiliang0121/capix-changes";import{RuntimeError,stableValue}from"@weiliang0121/capix-contracts";class InvocationOutputSection{static{__name(this,"InvocationOutputSection")}contextId;round;declaration;controls;writer;#state="open";#sequence=0;#delivery;constructor(contextId,round,declaration,controls,delivery){this.contextId=contextId,this.round=round,this.declaration=declaration,this.controls=controls,this.#delivery=delivery,this.writer=Object.freeze({emit:__name(value=>this.emit(value),"emit")})}start(){this.publish({kind:"started"}),this.controls.active()}emit(value){if(this.#state!=="open")throw new RuntimeError("OUTPUT_CLOSED","This output writer no longer belongs to an executing segment");this.controls.active();let delta;try{if(!this.declaration?.delta)throw new RuntimeError("OUTPUT_UNDECLARED","This declaration does not produce incremental output");delta=this.declaration.delta(value),rejectPromise(delta),delta=stableValue(delta)}catch(cause){const error=new RuntimeError("OUTPUT_CONTRACT","Produced incremental output violates its declaration",void 0,{cause});throw this.controls.reject(error),error}if(this.controls.active(),this.publish({kind:"delta",delta}),this.controls.active(),this.#state!=="open")throw new RuntimeError("OUTPUT_CLOSED","The output segment ended during delivery")}seal(){this.#state==="open"&&(this.#state="sealed",this.publish({kind:"sealed"}))}discard(reason){this.#state==="discarded"||this.#state==="completed"||(this.#state="discarded",this.publish({kind:"discarded",reason}))}validateResult(value){try{const result=this.declaration?this.declaration.result(value):value;if(this.declaration&&rejectPromise(result),result!==value&&!Object.is(result,value))throw new TypeError("Output validation must preserve the final value identity");return value}catch(cause){const error=new RuntimeError("OUTPUT_CONTRACT","The final output violates its declaration",void 0,{cause});throw this.controls.reject(error),error}}complete(result){if(this.#state==="open"||this.#state==="completed")throw new Error("Output segment cannot complete from this state");const discarded=this.#state==="discarded";this.#state="completed",this.publish({kind:"completed",result,discarded})}publish(event){this.#delivery?.publish(Object.freeze({...event,contextId:this.contextId,round:this.round,sequence:++this.#sequence}))}}function rejectPromise(value){if(value&&(typeof value=="object"||typeof value=="function")&&"then"in value&&typeof value.then=="function")throw Promise.resolve(value).catch(()=>{}),new TypeError("Output contracts must return synchronously")}__name(rejectPromise,"rejectPromise");export{InvocationOutputSection};

package/dist/value/array.d.ts

@@ -0,0 +1,2 @@
+export declare function isNonEmptyArray(value: unknown): value is [unknown, ...unknown[]];
+export declare function hasUniqueItems(values: readonly unknown[]): boolean;

package/dist/value/array.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{isArray}from"es-toolkit/compat";function isNonEmptyArray(value){return isArray(value)&&value.length>0}__name(isNonEmptyArray,"isNonEmptyArray");function hasUniqueItems(values){return new Set(values).size===values.length}__name(hasUniqueItems,"hasUniqueItems");export{hasUniqueItems,isNonEmptyArray};

package/dist/value/object.d.ts

@@ -0,0 +1,2 @@
+export declare const isObjectLike: (value: unknown) => value is object;
+export declare function isObject(value: unknown): value is Record<string, unknown>;

package/dist/value/object.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{isArray,isObjectLike as toolkitIsObjectLike}from"es-toolkit/compat";const isObjectLike=toolkitIsObjectLike;function isObject(value){return isObjectLike(value)&&!isArray(value)}__name(isObject,"isObject");export{isObject,isObjectLike};

package/dist/value/string.d.ts

@@ -0,0 +1,2 @@
+export declare const nonBlankStringPattern: RegExp;
+export declare function isNonBlankString(value: unknown): value is string;

package/dist/value/string.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{isString}from"es-toolkit/predicate";const nonBlankStringPattern=/\S/;function isNonBlankString(value){return isString(value)&&nonBlankStringPattern.test(value)}__name(isNonBlankString,"isNonBlankString");export{isNonBlankString,nonBlankStringPattern};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@weiliang0121/capix-invocation",
-  "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"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "1.52.0",
+    "@weiliang0121/capix-contracts": "0.1.0",
+    "@weiliang0121/capix-protocol": "0.1.0",
+    "@weiliang0121/capix-diagnostics": "0.1.0",
+    "@weiliang0121/capix-resources": "0.1.0",
+    "@weiliang0121/capix-changes": "0.1.0",
+    "@weiliang0121/capix-checkpoint": "0.1.0"
+  },
+  "description": "Invocation lifecycle, child relations, reception, output, and checkpoint activity for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "server/invocation"
+  },
+  "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"
+  }
 }