@weiliang0121/capix-interaction 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,19 @@
-# Temporary Holding Version
+# @weiliang0121/capix-interaction
 
-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.
+Independent external interactions, persisted feedback, and bounded progress streams for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-interaction
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-interaction`
+
+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/contract.d.ts

@@ -0,0 +1,60 @@
+import type { RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+import type { ProgressReceiver } from '@weiliang0121/capix-changes';
+export interface InteractionContract<Request, Reply, Delta = never> {
+    readonly key: string;
+    request(value: unknown): Request;
+    reply(value: unknown): Reply;
+    progress?(value: unknown): Delta;
+}
+export interface InteractionFeedback<Reply> {
+    readonly id: string;
+    readonly payload: Readonly<Reply>;
+}
+export interface InteractionState<Request = unknown, Reply = unknown> {
+    readonly id: string;
+    readonly contract: string;
+    readonly revision: number;
+    readonly request: Readonly<Request>;
+    readonly delivery: 'prepared' | 'started';
+    readonly feedback?: InteractionFeedback<Reply>;
+    readonly failure?: RuntimeErrorValue;
+}
+export interface InteractionCommit<Request = unknown, Reply = unknown> {
+    readonly expectedRevision: number;
+    readonly state: InteractionState<Request, Reply>;
+}
+export interface InteractionPersistence<Request = unknown, Reply = unknown> {
+    create(state: InteractionState<Request, Reply>): undefined;
+    commit(change: InteractionCommit<Request, Reply>): undefined;
+}
+export interface InteractionOptions<Request, Reply> {
+    readonly contract: Pick<InteractionContract<Request, Reply>, 'key' | 'request' | 'reply'>;
+    readonly persistence?: InteractionPersistence<Request, Reply>;
+    readonly observation?: ProgressReceiver<InteractionFact<Request, Reply>>;
+}
+export type InteractionFact<Request = unknown, Reply = unknown> = {
+    readonly type: 'changed';
+    readonly state: InteractionState<Request, Reply>;
+} | {
+    readonly type: 'unavailable';
+    readonly state: InteractionState<Request, Reply>;
+    readonly error: RuntimeErrorValue;
+};
+export type InteractionRead<Reply> = {
+    readonly kind: 'pending';
+} | {
+    readonly kind: 'received';
+    readonly feedback: InteractionFeedback<Reply>;
+} | {
+    readonly kind: 'unavailable';
+    readonly error: unknown;
+};
+export type InteractionWait<Reply> = Exclude<InteractionRead<Reply>, {
+    readonly kind: 'pending';
+}> | {
+    readonly kind: 'wait-expired';
+};
+export interface InteractionWaitOptions {
+    readonly waitMs: number;
+    readonly signal?: AbortSignal;
+}

package/dist/contract.js

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './contract.js';
+export { Interaction } from './interaction.js';
+export { Interactions, type InteractionReference, type InteractionChannel, type InteractionRegistration } from './interactions.js';
+export type { InteractionCursor, InteractionProgressRead, InteractionProgressReader, InteractionProgressLimits, InteractionProgressBudgetLimits, InteractionProgressFact, InteractionPublisher, InteractionPublication } from './progress/types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+export*from"./contract.js";import{Interaction}from"./interaction.js";import{Interactions}from"./interactions.js";export{Interaction,Interactions};

package/dist/interaction.d.ts

@@ -0,0 +1,17 @@
+import type { InteractionFeedback, InteractionOptions, InteractionRead, InteractionState, InteractionWait, InteractionWaitOptions } from './contract.js';
+export declare class Interaction<Request, Reply> {
+    #private;
+    constructor(request: Request, options: InteractionOptions<Request, Reply>);
+    get id(): string;
+    exportState(): InteractionState<Request, Reply>;
+    static restore<Request, Reply>(state: InteractionState, options: InteractionOptions<Request, Reply>): Interaction<Request, Reply>;
+    start(dispatch: (request: Readonly<Request>) => Reply | Promise<Reply>): void;
+    receive(feedback: InteractionFeedback<Reply>): void;
+    read(): InteractionRead<Reply>;
+    wait(options: InteractionWaitOptions): Promise<InteractionWait<Reply>>;
+    settled(): Promise<void>;
+    private fail;
+    private requireMutable;
+    private commit;
+    private notify;
+}

package/dist/interaction.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{RuntimeError}from"@weiliang0121/capix-contracts";import{PersistenceError,RuntimeErrorHelper}from"@weiliang0121/capix-diagnostics";import{isNonBlankString}from"./value.js";import{captureInteractionValue,sameInteractionValue}from"./value.js";import{ProgressChannel}from"@weiliang0121/capix-changes";class Interaction{static{__name(this,"Interaction")}#state;#options;#observation;#listeners=new Set;#settled=Promise.resolve();#fault;#deliveryFailure;#mutating=!1;#restored=!1;constructor(request,options){if(!isNonBlankString(options.contract.key))throw new TypeError("Interaction contract key must be nonempty");this.#options=Object.freeze({...options,contract:Object.freeze({key:options.contract.key,request:options.contract.request.bind(options.contract),reply:options.contract.reply.bind(options.contract)})}),this.#observation=options.observation?new ProgressChannel(options.observation):void 0;const captured=captureInteractionValue(request);this.#state=Object.freeze({id:randomUUID(),contract:this.#options.contract.key,revision:0,request:captureInteractionValue(this.#options.contract.request(captured)),delivery:"prepared"});try{const committed=this.#options.persistence?.create(this.#state);if(committed!==void 0)throw Promise.resolve(committed).catch(()=>{}),new TypeError("Interaction persistence must be synchronous")}catch(cause){throw new PersistenceError("interaction.create",cause)}this.#observation?.publish(Object.freeze({type:"changed",state:this.#state}))}get id(){return this.#state.id}exportState(){return this.#state}static restore(state,options){const saved=captureInteractionValue(state),allowed=new Set(["id","contract","revision","request","delivery","feedback","failure"]);if(Object.keys(saved).some(key=>!allowed.has(key))||!Object.hasOwn(saved,"request")||Object.hasOwn(saved,"feedback")&&!saved.feedback||Object.hasOwn(saved,"failure")&&!saved.failure)throw new TypeError("Invalid persisted interaction fields");if(!isNonBlankString(saved.id)||saved.contract!==options.contract.key||!Number.isSafeInteger(saved.revision)||saved.revision<0||saved.delivery!=="prepared"&&saved.delivery!=="started")throw new TypeError("Invalid persisted interaction identity or delivery");const expectedRevision=(saved.delivery==="started"?1:0)+(saved.feedback?1:0)+(saved.failure?1:0);if(saved.revision!==expectedRevision||saved.delivery==="prepared"&&(saved.feedback||saved.failure))throw new TypeError("Invalid persisted interaction progress");if(saved.feedback&&!isNonBlankString(saved.feedback.id))throw new TypeError("Invalid persisted interaction feedback identity");if(saved.failure&&(!isNonBlankString(saved.failure.code)||typeof saved.failure.message!="string"))throw new TypeError("Invalid persisted interaction diagnostic");const interaction=new Interaction(saved.request,{contract:options.contract}),request=interaction.#state.request;if(!sameInteractionValue(request,saved.request))throw new TypeError("Persisted interaction request does not match its contract");const feedback=saved.feedback?Object.freeze({id:saved.feedback.id,payload:captureInteractionValue(options.contract.reply(saved.feedback.payload))}):void 0;if(feedback&&!sameInteractionValue(feedback.payload,saved.feedback.payload))throw new TypeError("Persisted interaction feedback does not match its contract");return interaction.#state=Object.freeze({id:saved.id,contract:saved.contract,revision:saved.revision,request,delivery:saved.delivery,...feedback?{feedback}:{},...saved.failure?{failure:saved.failure}:{}}),interaction.#restored=!0,saved.failure&&(interaction.#deliveryFailure={error:new RuntimeError(saved.failure.code,saved.failure.message,saved.failure)}),interaction}start(dispatch){if(this.requireMutable(),this.#state.delivery!=="prepared")throw new RuntimeError("INTERACTION_ALREADY_STARTED","This interaction has already started");this.commit(Object.freeze({...this.#state,revision:this.#state.revision+1,delivery:"started"})),this.#settled=Promise.resolve().then(()=>dispatch(this.#state.request)).then(payload=>{try{this.receive({id:randomUUID(),payload})}catch(error){if(this.#fault)throw error;this.fail(error)}},error=>this.fail(error)).catch(error=>{this.#state.feedback||(this.#fault={error}),this.notify()})}receive(feedback){if(this.requireMutable(),this.#state.delivery!=="started")throw new RuntimeError("INTERACTION_NOT_STARTED","An unstarted interaction cannot receive feedback");const captured=captureInteractionValue(feedback);if(!isNonBlankString(captured.id))throw new TypeError("Interaction feedback identity must be nonempty");const accepted=Object.freeze({id:captured.id,payload:captureInteractionValue(this.#options.contract.reply(captured.payload))});if(this.#state.feedback){if(this.#state.feedback.id===accepted.id&&sameInteractionValue(this.#state.feedback.payload,accepted.payload))return;throw new RuntimeError("INTERACTION_FEEDBACK_CONFLICT","Interaction feedback cannot replace a previously received reply")}this.commit(Object.freeze({...this.#state,revision:this.#state.revision+1,feedback:accepted})),this.notify()}read(){return this.#fault?{kind:"unavailable",error:this.#fault.error}:this.#state.feedback?{kind:"received",feedback:this.#state.feedback}:this.#state.failure?{kind:"unavailable",error:this.#deliveryFailure?.error??new RuntimeError(this.#state.failure.code,this.#state.failure.message)}:this.#restored?{kind:"unavailable",error:new RuntimeError("INTERACTION_RESTORED_PENDING","Saved interaction has no received reply and no active delivery owner")}:{kind:"pending"}}wait(options){if(!Number.isSafeInteger(options.waitMs)||options.waitMs<0||options.waitMs>2147483647)return Promise.reject(new RangeError("Interaction waitMs must be a nonnegative timer duration"));if(options.signal?.aborted)return Promise.reject(options.signal.reason);const current=this.read();return current.kind!=="pending"?Promise.resolve(current):new Promise((resolve,reject)=>{let finished=!1,timer;const cleanup=__name(()=>{timer!==void 0&&clearTimeout(timer),this.#listeners.delete(check),options.signal?.removeEventListener("abort",cancel)},"cleanup"),finish=__name(result=>{finished||(finished=!0,cleanup(),resolve(result))},"finish"),cancel=__name(()=>{finished||(finished=!0,cleanup(),reject(options.signal?.reason))},"cancel"),check=__name(()=>{const result=this.read();result.kind!=="pending"&&finish(result)},"check");this.#listeners.add(check),options.signal?.addEventListener("abort",cancel,{once:!0}),options.signal?.aborted&&cancel(),finished||check(),finished||(timer=setTimeout(()=>{check(),finished||finish({kind:"wait-expired"})},options.waitMs))})}settled(){return this.#settled}fail(error){if(this.#state.feedback)return;const failure=captureInteractionValue(RuntimeErrorHelper.format(error));this.commit(Object.freeze({...this.#state,revision:this.#state.revision+1,failure})),this.#deliveryFailure={error},this.notify()}requireMutable(){if(this.#restored)throw new RuntimeError("INTERACTION_RESTORED","Restored interactions are read-only and cannot be sent again");if(this.#fault)throw this.#fault.error;if(this.#mutating)throw new RuntimeError("INTERACTION_REENTRANT_MUTATION","Interaction mutation cannot reenter persistence")}commit(state){this.requireMutable(),this.#mutating=!0;try{try{const committed=this.#options.persistence?.commit(Object.freeze({expectedRevision:this.#state.revision,state}));if(committed!==void 0)throw Promise.resolve(committed).catch(()=>{}),new TypeError("Interaction persistence must be synchronous")}catch(cause){throw new PersistenceError("interaction.commit",cause)}this.#state=state,this.#observation?.publish(Object.freeze({type:"changed",state}))}catch(error){throw this.#fault={error},this.#observation?.publish(Object.freeze({type:"unavailable",state:this.#state,error:RuntimeErrorHelper.format(error)})),this.notify(),error}finally{this.#mutating=!1}}notify(){for(const listener of this.#listeners)listener()}}export{Interaction};

package/dist/interactions.d.ts

@@ -0,0 +1,36 @@
+import type { InteractionContract, InteractionOptions, InteractionPersistence, InteractionRead, InteractionState, InteractionWait, InteractionWaitOptions } from './contract.js';
+import type { ProgressReceiver } from '@weiliang0121/capix-changes';
+import type { InteractionCursor, InteractionProgressBudgetLimits, InteractionProgressFact, InteractionProgressLimits, InteractionProgressReader, InteractionPublisher } from './progress/types.js';
+export interface InteractionReference {
+    readonly id: string;
+    readonly contract: string;
+}
+export interface InteractionChannel<Request, Reply, Delta = never> {
+    start(request: Request): InteractionReference;
+    read(ref: InteractionReference): InteractionRead<Reply>;
+    wait(ref: InteractionReference, options: InteractionWaitOptions): Promise<InteractionWait<Reply>>;
+    openProgress(ref: InteractionReference, after?: InteractionCursor): InteractionProgressReader<Delta>;
+}
+export interface InteractionRegistration<Request, Reply, Delta = never> {
+    readonly send: (request: Readonly<Request>, progress: InteractionPublisher<Delta>) => Reply | Promise<Reply>;
+    readonly progress?: InteractionProgressLimits;
+    readonly progressObservation?: ProgressReceiver<InteractionProgressFact>;
+    readonly persistence?: InteractionPersistence<Request, Reply> & {
+        read?(id: string): InteractionState | undefined;
+    };
+    readonly observation?: InteractionOptions<Request, Reply>['observation'];
+}
+export declare class Interactions {
+    #private;
+    constructor(options?: {
+        readonly retained?: number;
+        readonly progress?: InteractionProgressBudgetLimits;
+    });
+    register<Request, Reply, Delta = never>(contract: InteractionContract<Request, Reply, Delta>, registration: InteractionRegistration<NoInfer<Request>, NoInfer<Reply>, NoInfer<Delta>>): this;
+    bind<Request, Reply, Delta = never>(contract: InteractionContract<Request, Reply, Delta>): InteractionChannel<Request, Reply, Delta>;
+    get active(): boolean;
+    get pendingCount(): number;
+    settled(): Promise<void>;
+    close(): void;
+    private requireOpen;
+}

package/dist/interactions.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{isPromise}from"node:util/types";import{RuntimeError}from"@weiliang0121/capix-contracts";import{PersistenceError}from"@weiliang0121/capix-diagnostics";import{isNonBlankString}from"./value.js";import{Interaction}from"./interaction.js";import{InteractionProgress,unavailableProgressReader,validateProgressLimits}from"./progress/buffer.js";import{ProgressBudget}from"./progress/budget.js";import{progressObservation}from"./observation.js";class Interactions{static{__name(this,"Interactions")}#registrations=new Map;#keys=new Set;#retained;#progressBudget;#closed=!1;constructor(options={}){if(this.#retained=options.retained??128,!Number.isSafeInteger(this.#retained)||this.#retained<1)throw new RangeError("Interaction retention must be a positive integer");this.#progressBudget=new ProgressBudget(options.progress)}register(contract,registration){if(this.requireOpen(),!isNonBlankString(contract.key)||typeof contract.request!="function"||typeof contract.reply!="function")throw new TypeError("Interaction registration requires a valid contract");if(this.#registrations.has(contract)||this.#keys.has(contract.key))throw new RuntimeError("INTERACTION_ALREADY_REGISTERED","Interaction identity and key can each be registered only once");const registered=new RegisteredInteractions(contract,registration,this.#retained,()=>this.requireOpen(),this.#progressBudget);return this.#registrations.set(contract,{key:contract.key,channel:registered.channel,active:__name(()=>registered.active,"active"),pendingCount:__name(()=>registered.pendingCount,"pendingCount"),settled:__name(()=>registered.settled(),"settled"),clear:__name(()=>registered.clear(),"clear")}),this.#keys.add(contract.key),this}bind(contract){this.requireOpen();const registration=this.#registrations.get(contract);if(!registration)throw new RuntimeError(this.#keys.has(contract.key)?"INTERACTION_CONTRACT_IDENTITY":"INTERACTION_NOT_REGISTERED","The exact interaction contract must be registered before it is bound");if(registration.key!==contract.key)throw new RuntimeError("INTERACTION_CONTRACT_CHANGED","A registered interaction contract key cannot change");return registration.channel}get active(){return[...this.#registrations.values()].some(registration=>registration.active())}get pendingCount(){let count=0;for(const registration of this.#registrations.values())count+=registration.pendingCount();return count}async settled(){for(;this.active;)await Promise.all([...this.#registrations.values()].map(registration=>registration.settled()))}close(){if(this.active)throw new RuntimeError("INTERACTIONS_ACTIVE","Cannot close interactions while exchanges are active");this.#closed=!0;for(const registration of this.#registrations.values())registration.clear();this.#registrations.clear(),this.#keys.clear()}requireOpen(){if(this.#closed)throw new RuntimeError("INTERACTIONS_CLOSED","Interactions are closed")}}class RegisteredInteractions{static{__name(this,"RegisteredInteractions")}retained;requireOpen;progressBudget;channel;#options;#send;#decodeProgress;#progressLimits;#progressObservation;#read;#exchanges=new Map;#active=new Set;#preparing=0;#pruning=!1;constructor(contract,registration,retained,requireOpen,progressBudget){if(this.retained=retained,this.requireOpen=requireOpen,this.progressBudget=progressBudget,typeof registration.send!="function")throw new TypeError("Interaction registration requires a sender");if(contract.progress!==void 0&&typeof contract.progress!="function")throw new TypeError("Interaction progress requires a synchronous decoder");if(registration.progress&&!contract.progress)throw new TypeError("Progress limits require an interaction progress contract");this.#decodeProgress=contract.progress?.bind(contract),this.#progressLimits=validateProgressLimits(registration.progress),this.#progressObservation=progressObservation(registration.progressObservation);const persistence=registration.persistence;if(persistence&&(typeof persistence.create!="function"||typeof persistence.commit!="function"||persistence.read!==void 0&&typeof persistence.read!="function"))throw new TypeError("Interaction registration requires synchronous persistence methods");this.#send=registration.send.bind(registration),this.#read=persistence?.read?.bind(persistence);const observation=registration.observation;this.#options=Object.freeze({contract:Object.freeze({key:contract.key,request:contract.request.bind(contract),reply:contract.reply.bind(contract)}),...persistence?{persistence:Object.freeze({create:persistence.create.bind(persistence),commit:persistence.commit.bind(persistence)})}:{},...observation?{observation:Object.freeze({receive:observation.receive.bind(observation),...observation.failed?{failed:observation.failed.bind(observation)}:{}})}:{}}),this.channel=Object.freeze({start:__name(request=>this.start(request),"start"),read:__name(ref=>this.get(ref).interaction.read(),"read"),wait:__name(async(ref,options)=>this.get(ref).interaction.wait(options),"wait"),openProgress:__name((ref,after)=>(this.requireReference(ref),this.#exchanges.get(ref.id)?.progress?.open(after)??unavailableProgressReader(ref.id,this.#decodeProgress?"not-retained":"not-enabled",after)),"openProgress")})}get active(){return this.#preparing>0||this.#active.size>0}get pendingCount(){return this.#active.size}async settled(){await Promise.all([...this.#active].map(interaction=>interaction.settled()))}clear(){for(const entry of this.#exchanges.values())entry.progress?.invalidate("closed");this.#exchanges.clear()}start(request){this.requireOpen(),this.#preparing+=1;let interaction,progress;try{interaction=new Interaction(request,this.#options),this.#decodeProgress&&(progress=new InteractionProgress(interaction.id,this.#decodeProgress,this.#progressLimits,this.progressBudget,this.#progressObservation)),this.#exchanges.set(interaction.id,{interaction,progress}),this.#active.add(interaction),progress?.installed();const output=progress,publisher=Object.freeze({publish:__name(value=>output?.publish(value)??Object.freeze({kind:"unavailable",reason:"not-enabled"}),"publish")});interaction.start(async request2=>{try{return await this.#send(request2,publisher)}finally{output?.seal()}});const started=interaction;return started.settled().then(()=>{this.#active.delete(started),this.prune()}),Object.freeze({id:interaction.id,contract:this.#options.contract.key})}catch(error){throw progress?.invalidate("start-failed"),interaction&&this.#active.delete(interaction),this.prune(),error}finally{this.#preparing-=1}}get(ref){this.requireReference(ref);let entry=this.#exchanges.get(ref.id);if(!entry){let saved;try{if(saved=this.#read?.(ref.id),isPromise(saved))throw saved.catch(()=>{}),new TypeError("Interaction persistence reads must be synchronous")}catch(cause){throw new PersistenceError("interaction.read",cause)}if(this.requireOpen(),saved!==void 0){try{const interaction=Interaction.restore(saved,this.#options);if(interaction.id!==ref.id)throw new RuntimeError("INTERACTION_IDENTITY","Saved interaction does not match the requested identity");entry={interaction}}catch(cause){throw new PersistenceError("interaction.restore",cause)}this.requireOpen(),this.#exchanges.set(entry.interaction.id,entry),this.prune()}}if(!entry)throw new RuntimeError("INTERACTION_UNKNOWN","Interaction is not retained or persisted; it cannot be sent again from a reference");return entry}requireReference(ref){if(this.requireOpen(),!ref||!isNonBlankString(ref.id)||ref.contract!==this.#options.contract.key)throw new RuntimeError("INTERACTION_CONTRACT_MISMATCH","Interaction reference must belong to this registered contract")}prune(){if(!this.#pruning){this.#pruning=!0;try{for(const[id,entry]of this.#exchanges){if(this.#exchanges.size-this.#active.size<=this.retained)return;this.#active.has(entry.interaction)||(this.#exchanges.delete(id),entry.progress?.invalidate("evicted"))}}finally{this.#pruning=!1}}}}export{Interactions};

package/dist/observation.d.ts

@@ -0,0 +1,3 @@
+import { type ProgressReceiver } from '@weiliang0121/capix-changes';
+import type { InteractionProgressFact } from './progress/types.js';
+export declare function progressObservation(receiver?: ProgressReceiver<InteractionProgressFact>): ProgressReceiver<InteractionProgressFact> | undefined;

package/dist/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";function progressObservation(receiver){if(!receiver)return;const receive=receiver.receive.bind(receiver);let delivering=!1;const channel=new ProgressChannel({receive(fact){if(delivering)throw new TypeError("Interaction progress observation cannot recursively deliver facts");delivering=!0;try{return receive(fact)}finally{delivering=!1}},failed:receiver.failed?.bind(receiver)});return Object.freeze({receive:__name(fact=>{channel.publish(fact)},"receive")})}__name(progressObservation,"progressObservation");export{progressObservation};

package/dist/progress/budget.d.ts

@@ -0,0 +1,10 @@
+import type { InteractionProgressBudgetLimits } from './types.js';
+export declare function positiveLimit(value: number, name: string): number;
+export declare class ProgressBudget {
+    #private;
+    constructor(limits?: InteractionProgressBudgetLimits);
+    reserveBytes(bytes: number): boolean;
+    releaseBytes(bytes: number): void;
+    reserveReader(): boolean;
+    releaseReader(): void;
+}

package/dist/progress/budget.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 positiveLimit(value,name){if(!Number.isSafeInteger(value)||value<1)throw new RangeError(`${name} must be a positive safe integer`);return value}__name(positiveLimit,"positiveLimit");class ProgressBudget{static{__name(this,"ProgressBudget")}#maxBytes;#maxReaders;#bytes=0;#readers=0;constructor(limits={}){this.#maxBytes=positiveLimit(limits.maxBytes??32*1024*1024,"Progress budget maxBytes"),this.#maxReaders=positiveLimit(limits.maxReaders??256,"Progress budget maxReaders")}reserveBytes(bytes){return positiveLimit(bytes,"Reserved progress bytes"),bytes>this.#maxBytes-this.#bytes?!1:(this.#bytes+=bytes,!0)}releaseBytes(bytes){if(!Number.isSafeInteger(bytes)||bytes<0||bytes>this.#bytes)throw new RangeError("Invalid progress byte release");this.#bytes-=bytes}reserveReader(){return this.#readers>=this.#maxReaders?!1:(this.#readers+=1,!0)}releaseReader(){if(this.#readers===0)throw new RangeError("Invalid progress reader release");this.#readers-=1}}export{ProgressBudget,positiveLimit};

package/dist/progress/buffer.d.ts

@@ -0,0 +1,47 @@
+import { type ProgressReceiver } from '@weiliang0121/capix-changes';
+import { ProgressBudget } from './budget.js';
+import type { InteractionCursor, InteractionProgressFact, InteractionProgressLimits, InteractionProgressRead, InteractionProgressReader, InteractionPublication } from './types.js';
+type Item<Delta> = Extract<InteractionProgressRead<Delta>, {
+    kind: 'item';
+}>;
+type Terminal = Extract<InteractionProgressRead<never>, {
+    kind: 'sealed' | 'unavailable';
+}>;
+type Inspection<Delta> = Item<Delta> | Terminal | {
+    readonly kind: 'pending';
+};
+export declare function validateProgressLimits(limits?: InteractionProgressLimits): Required<InteractionProgressLimits>;
+export declare class InteractionProgress<Delta> {
+    #private;
+    readonly interactionId: string;
+    constructor(interactionId: string, decode: (value: unknown) => Delta, limits?: InteractionProgressLimits, budget?: ProgressBudget, observation?: ProgressReceiver<InteractionProgressFact>);
+    installed(): void;
+    get revision(): number;
+    publish(value: Delta): InteractionPublication;
+    seal(): void;
+    invalidate(reason: string): Extract<Terminal, {
+        kind: 'unavailable';
+    }>;
+    open(after?: InteractionCursor): InteractionProgressReader<Delta>;
+    inspectAfter(sequence: number): Inspection<Delta>;
+    listen(wake: () => void): () => void;
+    release(reader: ProgressReader<Delta>): void;
+    private observe;
+    private changed;
+}
+export declare function unavailableProgressReader<Delta>(interactionId: string, reason: string, after?: InteractionCursor): InteractionProgressReader<Delta>;
+declare class ProgressReader<Delta> implements InteractionProgressReader<Delta> {
+    #private;
+    constructor(source: InteractionProgress<Delta> | undefined, cursor: InteractionCursor, terminal?: Terminal);
+    get position(): InteractionCursor;
+    next(options: {
+        readonly waitMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<InteractionProgressRead<Delta>>;
+    close(reason?: unknown): void;
+    finish(terminal: Terminal): void;
+    private detach;
+    private read;
+    private wait;
+}
+export {};

package/dist/progress/buffer.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{isPromise}from"node:util/types";import{RuntimeError}from"@weiliang0121/capix-contracts";import{ProgressChannel}from"@weiliang0121/capix-changes";import{captureInteractionValue,isNonBlankString}from"../value.js";import{positiveLimit,ProgressBudget}from"./budget.js";function validateProgressLimits(limits={}){return Object.freeze({maxBytes:positiveLimit(limits.maxBytes??4*1024*1024,"Progress maxBytes"),maxEntries:positiveLimit(limits.maxEntries??16384,"Progress maxEntries"),maxReaders:positiveLimit(limits.maxReaders??64,"Progress maxReaders")})}__name(validateProgressLimits,"validateProgressLimits");function position(interactionId,sequence){return Object.freeze({interactionId,sequence})}__name(position,"position");function checkCursor(interactionId,after,head){if(after!==void 0&&(!after||typeof after!="object"))throw new RuntimeError("INTERACTION_PROGRESS_CURSOR","Progress cursor must be a position in this interaction");const sequence=after===void 0?0:after.sequence;if(after!==void 0&&after.interactionId!==interactionId||!Number.isSafeInteger(sequence)||sequence<0||head!==void 0&&sequence>head)throw new RuntimeError("INTERACTION_PROGRESS_CURSOR","Progress cursor must refer to an existing position in this interaction");return position(interactionId,sequence)}__name(checkCursor,"checkCursor");class InteractionProgress{static{__name(this,"InteractionProgress")}interactionId;#limits;#budget;#decode;#observation;#items=[];#readers=new Set;#waiters=new Set;#bytes=0;#head=0;#revision=0;#sealed=!1;#unavailable;#publishing=!1;#observing=!1;#installed=!1;constructor(interactionId,decode,limits={},budget=new ProgressBudget,observation){if(this.interactionId=interactionId,!isNonBlankString(interactionId)||typeof decode!="function")throw new TypeError("Progress requires an interaction identity and synchronous data contract");if(this.#decode=decode,this.#limits=validateProgressLimits(limits),this.#budget=budget,observation){const receive=observation.receive.bind(observation);this.#observation=new ProgressChannel({receive:__name(fact=>{if(this.#observing)throw new RuntimeError("INTERACTION_PROGRESS_OBSERVATION_REENTRY","Progress observation cannot recursively publish lifecycle changes");this.#observing=!0;try{return receive(fact)}finally{this.#observing=!1}},"receive"),failed:observation.failed?.bind(observation)})}}installed(){this.#installed||(this.#installed=!0,this.observe("created"))}get revision(){return this.#revision}publish(value){if(this.#unavailable)return this.#unavailable;if(this.#sealed)return Object.freeze({kind:"sealed"});if(this.#publishing)return this.invalidate("invalid-data");this.#publishing=!0;try{const decoded=this.#decode(captureInteractionValue(value));if(isPromise(decoded))throw decoded.catch(()=>{}),new TypeError("Progress data contract must be synchronous");const captured=captureInteractionValue(decoded);if(this.#unavailable)return this.#unavailable;if(this.#sealed)return Object.freeze({kind:"sealed"});const bytes=Buffer.byteLength(JSON.stringify(captured),"utf8");if(bytes>this.#limits.maxBytes-this.#bytes||this.#items.length>=this.#limits.maxEntries||!this.#budget.reserveBytes(bytes))return this.invalidate("capacity");this.#bytes+=bytes;const cursor=position(this.interactionId,++this.#head);return this.#items.push(Object.freeze({kind:"item",cursor,value:captured})),this.changed(),Object.freeze({kind:"published",cursor})}catch{return this.#unavailable?this.#unavailable:this.#sealed?Object.freeze({kind:"sealed"}):this.invalidate("invalid-data")}finally{this.#publishing=!1}}seal(){if(!this.#sealed){this.#sealed=!0,this.observe("sealed");for(const reader of[...this.#readers])this.#unavailable?reader.finish(this.#unavailable):reader.position.sequence===this.#head&&reader.finish(Object.freeze({kind:"sealed",lastSequence:this.#head}));this.changed()}}invalidate(reason){if(this.#unavailable)return this.#unavailable;this.#unavailable=Object.freeze({kind:"unavailable",reason}),this.#items.length=0,this.#budget.releaseBytes(this.#bytes),this.#bytes=0,this.observe("unavailable",reason);for(const reader of[...this.#readers])reader.finish(this.#unavailable);return this.changed(),this.#unavailable}open(after){const cursor=checkCursor(this.interactionId,after,this.#head),state=this.inspectAfter(cursor.sequence);if(state.kind==="unavailable"||state.kind==="sealed")return new ProgressReader(void 0,cursor,state);if(this.#readers.size>=this.#limits.maxReaders||!this.#budget.reserveReader())throw new RuntimeError("INTERACTION_PROGRESS_READERS","Progress reader capacity is exhausted");const reader=new ProgressReader(this,cursor);return this.#readers.add(reader),this.observe("reader-opened"),reader}inspectAfter(sequence){if(this.#unavailable)return this.#unavailable;const item=this.#items[sequence];return item||(this.#sealed?Object.freeze({kind:"sealed",lastSequence:this.#head}):{kind:"pending"})}listen(wake){return this.#waiters.add(wake),()=>this.#waiters.delete(wake)}release(reader){this.#readers.delete(reader)&&(this.#budget.releaseReader(),this.observe("reader-closed"))}observe(phase,reason){!this.#installed||!this.#observation||this.#observation.publish(Object.freeze({interactionId:this.interactionId,phase,lastSequence:this.#head,entries:this.#items.length,bytes:this.#bytes,readers:this.#readers.size,...reason?{reason}:{}}))}changed(){this.#revision+=1;for(const wake of[...this.#waiters])wake()}}function unavailableProgressReader(interactionId,reason,after){return new ProgressReader(void 0,checkCursor(interactionId,after),Object.freeze({kind:"unavailable",reason}))}__name(unavailableProgressReader,"unavailableProgressReader");class ProgressReader{static{__name(this,"ProgressReader")}#position;#source;#terminal;#closed;#busy=!1;#wake;constructor(source,cursor,terminal){this.#source=source,this.#position=cursor,this.#terminal=terminal}get position(){return this.#position}next(options){return this.#busy?Promise.reject(new RuntimeError("INTERACTION_PROGRESS_CONCURRENT_READ","A progress reader permits only one pending next operation")):(this.#busy=!0,this.read(options).finally(()=>{this.#busy=!1}))}close(reason=new RuntimeError("INTERACTION_PROGRESS_READER_CLOSED","Progress reader is closed")){this.#closed||(this.#closed={reason},this.detach(),this.#wake?.())}finish(terminal){this.#closed||this.#terminal||(this.#terminal=terminal,this.detach(),this.#wake?.())}detach(){const source=this.#source;this.#source=void 0,source?.release(this)}async read(options){const{waitMs,signal}=options;if(!Number.isSafeInteger(waitMs)||waitMs<0||waitMs>2147483647)throw new RangeError("Progress waitMs must be a nonnegative timer duration");const deadline=performance.now()+waitMs;for(;;){if(signal?.aborted)throw signal.reason;if(this.#closed)throw this.#closed.reason;if(this.#terminal)return this.#terminal;const source=this.#source,revision=source.revision,result=source.inspectAfter(this.#position.sequence);if(result.kind==="item")return this.#position=result.cursor,result;if(result.kind!=="pending")return this.finish(result),result;const remaining=deadline-performance.now();if(remaining<=0)return{kind:"wait-expired"};await this.wait(source,revision,remaining,signal)}}wait(source,revision,remaining,signal){return new Promise(resolve=>{let finished=!1,timer;const wake=__name(()=>{finished||(finished=!0,remove(),timer!==void 0&&clearTimeout(timer),signal?.removeEventListener("abort",wake),this.#wake=void 0,resolve())},"wake"),remove=source.listen(wake);this.#wake=wake,signal?.addEventListener("abort",wake,{once:!0}),(source.revision!==revision||this.#closed||this.#terminal||signal?.aborted)&&wake(),finished||(timer=setTimeout(wake,remaining))})}}export{InteractionProgress,unavailableProgressReader,validateProgressLimits};

package/dist/progress/types.d.ts

@@ -0,0 +1,55 @@
+export interface InteractionCursor {
+    readonly interactionId: string;
+    readonly sequence: number;
+}
+export interface InteractionProgressLimits {
+    readonly maxBytes?: number;
+    readonly maxEntries?: number;
+    readonly maxReaders?: number;
+}
+export interface InteractionProgressBudgetLimits {
+    readonly maxBytes?: number;
+    readonly maxReaders?: number;
+}
+export interface InteractionProgressFact {
+    readonly interactionId: string;
+    readonly phase: 'created' | 'sealed' | 'unavailable' | 'reader-opened' | 'reader-closed';
+    readonly lastSequence: number;
+    readonly entries: number;
+    readonly bytes: number;
+    readonly readers: number;
+    readonly reason?: string;
+}
+export type InteractionProgressRead<Delta> = {
+    readonly kind: 'item';
+    readonly cursor: InteractionCursor;
+    readonly value: Readonly<Delta>;
+} | {
+    readonly kind: 'sealed';
+    readonly lastSequence: number;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'wait-expired';
+};
+export interface InteractionProgressReader<Delta> {
+    readonly position: InteractionCursor;
+    next(options: {
+        readonly waitMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<InteractionProgressRead<Delta>>;
+    close(reason?: unknown): void;
+}
+export type InteractionPublication = {
+    readonly kind: 'published';
+    readonly cursor: InteractionCursor;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'sealed';
+};
+export interface InteractionPublisher<Delta> {
+    publish(value: Delta): InteractionPublication;
+}

package/dist/progress/types.js

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

package/dist/value.d.ts

@@ -0,0 +1,3 @@
+export declare function captureInteractionValue<T>(value: T): T;
+export declare function sameInteractionValue(left: unknown, right: unknown): boolean;
+export declare function isNonBlankString(value: unknown): value is string;

package/dist/value.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isProxy}from"node:util/types";import{isArray}from"es-toolkit/compat";const limits=Object.freeze({depth:64,values:1e5,characters:16*1024*1024});function captureInteractionValue(value){let values=0,characters=0;const ancestors=new Set,visit=__name((current,depth)=>{if(values+=1,depth>limits.depth||values>limits.values)throw new TypeError("Interaction data exceeds its structural limit");if(current===null||typeof current=="boolean"||typeof current=="number"&&Number.isFinite(current))return current;if(typeof current=="string"){if(characters+=current.length,characters>limits.characters)throw new TypeError("Interaction data exceeds its text limit");return current}if(typeof current!="object"||isProxy(current))throw new TypeError("Interaction data must contain only JSON values");const prototype=Object.getPrototypeOf(current);if(!isArray(current)&&prototype!==Object.prototype&&prototype!==null)throw new TypeError("Interaction data must contain only JSON values");if(ancestors.has(current))throw new TypeError("Interaction data must not contain cycles");ancestors.add(current);try{const descriptors=Object.getOwnPropertyDescriptors(current);if(isArray(current)){const result2=[];if(Reflect.ownKeys(descriptors).length!==current.length+1)throw new TypeError("Interaction arrays must be dense and contain only indexed values");for(let index=0;index<current.length;index+=1){const descriptor=descriptors[String(index)];if(!descriptor||!("value"in descriptor)||!descriptor.enumerable)throw new TypeError("Interaction data must not contain accessors or missing array values");result2.push(visit(descriptor.value,depth+1))}return Object.freeze(result2)}const result={};for(const key of Reflect.ownKeys(descriptors)){const descriptor=descriptors[key];if(typeof key!="string"||!("value"in descriptor)||!descriptor.enumerable)throw new TypeError("Interaction data must contain only enumerable data properties");if(characters+=key.length,characters>limits.characters)throw new TypeError("Interaction data exceeds its text limit");Object.defineProperty(result,key,{value:visit(descriptor.value,depth+1),enumerable:!0})}return Object.freeze(result)}finally{ancestors.delete(current)}},"visit");return visit(value,0)}__name(captureInteractionValue,"captureInteractionValue");function sameInteractionValue(left,right){if(left===right)return!0;if(left===null||right===null||typeof left!="object"||typeof right!="object"||isArray(left)!==isArray(right))return!1;const leftKeys=Object.keys(left),rightKeys=Object.keys(right);return leftKeys.length===rightKeys.length&&leftKeys.every(key=>Object.hasOwn(right,key)&&sameInteractionValue(Reflect.get(left,key),Reflect.get(right,key)))}__name(sameInteractionValue,"sameInteractionValue");function isNonBlankString(value){return typeof value=="string"&&/\S/.test(value)}__name(isNonBlankString,"isNonBlankString");export{captureInteractionValue,isNonBlankString,sameInteractionValue};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@weiliang0121/capix-interaction",
-  "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-diagnostics": "0.1.0",
+    "@weiliang0121/capix-changes": "0.1.0"
+  },
+  "description": "Independent external interactions, persisted feedback, and bounded progress streams for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "server/interaction"
+  },
+  "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"
+  }
 }