@justscale/core 0.1.0

package/dist/process/createProcess.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @justscale/process - Process Factory
+ *
+ * Creates durable process definitions that are transformed by the compiler
+ * into opcode-based execution graphs.
+ */
+import type { ServiceToken } from '../core/index.js';
+import type { ExtractPathParams, ProcessConfig, ProcessDefinition } from './types.js';
+/**
+ * Symbol marking a process definition for compiler detection.
+ * The compiler uses this to identify and transform process handlers.
+ */
+export declare const PROCESS_DEFINITION: unique symbol;
+export declare const SUBPROCESS_DEFINITION: unique symbol;
+/**
+ * Creates a durable process definition.
+ *
+ * Process definitions are compiled by the JustScale compiler into opcode-based
+ * execution graphs that support:
+ * - Durable execution across restarts
+ * - Signal-based suspension and resumption
+ * - Transactional state persistence
+ * - Race conditions between signals and timers
+ *
+ * The runtime stub returned by this function throws at runtime - the actual
+ * implementation is injected by the compiler transform.
+ *
+ * @example
+ * ```typescript
+ * import { createProcess } from '@justscale/process'
+ *
+ * const OrderFulfillment = createProcess({
+ *   path: '/order/:orderId/fulfillment',
+ *   inject: { payments: PaymentService, shipping: ShippingService },
+ *   async handler({ payments, shipping }, [orderId]) {
+ *     // Suspend until payment is received
+ *     const payment = await payments.received(orderId)
+ *
+ *     // Continue with shipping
+ *     await shipping.dispatch(orderId, payment.address)
+ *
+ *     return { status: 'fulfilled' }
+ *   },
+ * })
+ *
+ * // Start a process instance
+ * const handle = await OrderFulfillment(['order-123'])
+ * ```
+ *
+ * @param config - Process configuration including path, dependencies, and handler
+ * @returns A process definition that can start and query process instances
+ */
+export declare function createProcess<TPath extends string, TDeps extends Record<string, ServiceToken>, TResult, TExports = void, TTypes extends Record<string, import('./types.js').ModelClass> = {}>(config: ProcessConfig<TPath, TDeps, TResult, TExports, TTypes>): ProcessDefinition<TPath, ExtractPathParams<TPath>, TResult, TExports>;
+export interface SubProcessConfig<THandler extends (...args: any[]) => Promise<any> = (...args: any[]) => Promise<unknown>> {
+    name: string;
+    path: string;
+    handler: THandler;
+}
+/**
+ * Declares a named subprocess inside a process handler.
+ * The compiler transforms this into nested state within the parent process.
+ * At runtime, the returned callable spawns subprocess instances.
+ */
+export declare function createSubProcess<THandler extends (...args: any[]) => Promise<any>>(config: SubProcessConfig<THandler>): THandler & {
+    [SUBPROCESS_DEFINITION]: true;
+};
+//# sourceMappingURL=createProcess.d.ts.map

package/dist/process/createProcess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createProcess.d.ts","sourceRoot":"","sources":["../../src/process/createProcess.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AAIH,eAAO,MAAM,kBAAkB,eAA4C,CAAC;AAC5E,eAAO,MAAM,qBAAqB,eAA+C,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,aAAa,CAC3B,KAAK,SAAS,MAAM,EACpB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC1C,OAAO,EACP,QAAQ,GAAG,IAAI,EACf,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,EAEnE,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,GAC7D,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CA8DvE;AAED,MAAM,WAAW,gBAAgB,CAAC,QAAQ,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC;IACxH,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,QAAQ,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAChF,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GACjC,QAAQ,GAAG;IAAE,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAA;CAAE,CAU9C"}

package/dist/process/createProcess.js

@@ -0,0 +1,111 @@
+/**
+ * @justscale/process - Process Factory
+ *
+ * Creates durable process definitions that are transformed by the compiler
+ * into opcode-based execution graphs.
+ */
+/**
+ * Symbol marking a process definition for compiler detection.
+ * The compiler uses this to identify and transform process handlers.
+ */
+// Cross-realm: tests forge these via Symbol.for() and the compiler emits
+// references in user code. Keep interned so identity matches across module
+// instances and across the test/runtime boundary.
+export const PROCESS_DEFINITION = Symbol.for('justscale:processDefinition');
+export const SUBPROCESS_DEFINITION = Symbol.for('justscale:subprocessDefinition');
+/**
+ * Creates a durable process definition.
+ *
+ * Process definitions are compiled by the JustScale compiler into opcode-based
+ * execution graphs that support:
+ * - Durable execution across restarts
+ * - Signal-based suspension and resumption
+ * - Transactional state persistence
+ * - Race conditions between signals and timers
+ *
+ * The runtime stub returned by this function throws at runtime - the actual
+ * implementation is injected by the compiler transform.
+ *
+ * @example
+ * ```typescript
+ * import { createProcess } from '@justscale/process'
+ *
+ * const OrderFulfillment = createProcess({
+ *   path: '/order/:orderId/fulfillment',
+ *   inject: { payments: PaymentService, shipping: ShippingService },
+ *   async handler({ payments, shipping }, [orderId]) {
+ *     // Suspend until payment is received
+ *     const payment = await payments.received(orderId)
+ *
+ *     // Continue with shipping
+ *     await shipping.dispatch(orderId, payment.address)
+ *
+ *     return { status: 'fulfilled' }
+ *   },
+ * })
+ *
+ * // Start a process instance
+ * const handle = await OrderFulfillment(['order-123'])
+ * ```
+ *
+ * @param config - Process configuration including path, dependencies, and handler
+ * @returns A process definition that can start and query process instances
+ */
+export function createProcess(config) {
+    const storedConfig = config;
+    const processCallable = async (_params) => {
+        throw new Error(`Process "${config.path}" not compiled. ` +
+            'Run the JustScale compiler to transform process definitions into executable opcodes.');
+    };
+    const get = async (_params) => {
+        throw new Error(`Process "${config.path}" not compiled. ` +
+            'The get() method requires the compiler transform to be applied.');
+    };
+    const query = (_pattern) => {
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        throw new Error(`Process "${config.path}" not compiled. ` +
+                            'The query() method requires the compiler transform to be applied.');
+                    }
+                };
+            }
+        };
+    };
+    /**
+     * Emit a signal to processes waiting for it.
+     * @deprecated Use service methods instead. Provided for testing.
+     */
+    const emit = async (_signal, _identity, _payload) => {
+        throw new Error(`Process "${config.path}" not compiled. ` +
+            'The emit() method requires the compiler transform to be applied.');
+    };
+    const definition = Object.assign(processCallable, {
+        path: config.path,
+        get,
+        query,
+        emit,
+        exports: undefined,
+        [PROCESS_DEFINITION]: true,
+        __config: storedConfig,
+        deps: config.inject,
+        factory: (_resolvedDeps) => processCallable,
+    });
+    return definition;
+}
+/**
+ * Declares a named subprocess inside a process handler.
+ * The compiler transforms this into nested state within the parent process.
+ * At runtime, the returned callable spawns subprocess instances.
+ */
+export function createSubProcess(config) {
+    const callable = (..._args) => {
+        throw new Error(`createSubProcess("${config.name}") not compiled. ` +
+            'Run the JustScale compiler to transform subprocess definitions.');
+    };
+    callable[SUBPROCESS_DEFINITION] = true;
+    callable.__config = config;
+    return callable;
+}
+//# sourceMappingURL=createProcess.js.map

package/dist/process/createProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createProcess.js","sourceRoot":"","sources":["../../src/process/createProcess.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;;GAGG;AACH,yEAAyE;AACzE,2EAA2E;AAC3E,kDAAkD;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,aAAa,CAO3B,MAA8D;IAI9D,MAAM,YAAY,GAAG,MAAM,CAAC;IAE5B,MAAM,eAAe,GAAG,KAAK,EAAE,OAAgB,EAA6C,EAAE;QAC5F,MAAM,IAAI,KAAK,CACb,YAAY,MAAM,CAAC,IAAI,kBAAkB;YACzC,sFAAsF,CACvF,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,KAAK,EAAE,OAAgB,EAAoD,EAAE;QACvF,MAAM,IAAI,KAAK,CACb,YAAY,MAAM,CAAC,IAAI,kBAAkB;YACzC,iEAAiE,CAClE,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,CAAC,QAAyC,EAAmD,EAAE;QAC3G,OAAO;YACL,CAAC,MAAM,CAAC,aAAa,CAAC;gBACpB,OAAO;oBACL,KAAK,CAAC,IAAI;wBACR,MAAM,IAAI,KAAK,CACb,YAAY,MAAM,CAAC,IAAI,kBAAkB;4BACzC,mEAAmE,CACpE,CAAC;oBACJ,CAAC;iBACF,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;IAEF;;;OAGG;IACH,MAAM,IAAI,GAAG,KAAK,EAChB,OAAe,EACf,SAAoB,EACpB,QAAiB,EACF,EAAE;QACjB,MAAM,IAAI,KAAK,CACb,YAAY,MAAM,CAAC,IAAI,kBAAkB;YACzC,kEAAkE,CACnE,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE;QAChD,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,GAAG;QACH,KAAK;QACL,IAAI;QACJ,OAAO,EAAE,SAAS;QAClB,CAAC,kBAAkB,CAAC,EAAE,IAAI;QAC1B,QAAQ,EAAE,YAAY;QACtB,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,OAAO,EAAE,CAAC,aAAsC,EAAE,EAAE,CAAC,eAAe;KACrE,CAAyD,CAAC;IAE3D,OAAO,UAAU,CAAC;AACpB,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAkC;IAElC,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAgB,EAAoB,EAAE;QACzD,MAAM,IAAI,KAAK,CACb,qBAAqB,MAAM,CAAC,IAAI,mBAAmB;YACnD,iEAAiE,CAClE,CAAC;IACJ,CAAC,CAAC;IACD,QAAgB,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAgB,CAAC,QAAQ,GAAG,MAAM,CAAC;IACpC,OAAO,QAAe,CAAC;AACzB,CAAC"}

package/dist/process/define-signals.d.ts

@@ -0,0 +1,113 @@
+/**
+ * defineSignals — declarative signal group with DI-wired executor.
+ *
+ * Replaces the manual pattern of injecting AbstractProcessExecutor and
+ * calling executor.createSignal() in every signal service.
+ *
+ * @example
+ * ```typescript
+ * export class PaymentSignals extends defineSignals(signal => ({
+ *   confirmed: signal('/payment/:order/confirmed').types({ Order }),
+ *   failed: signal<{ reason: string }>('/payment/:order/failed').types({ Order }),
+ * })) {}
+ *
+ * // Inject and emit:
+ * class OrderService extends defineService({
+ *   inject: { payment: PaymentSignals },
+ *   factory: ({ payment }) => ({
+ *     async markPaid(order: Locked<Order>) {
+ *       await payment.confirmed({ order });
+ *     },
+ *   }),
+ * }) {}
+ * ```
+ */
+import type { ResolveParamType, ExtractParamNames } from '../models/apply-types-config.js';
+import type { Locked } from '../models/types.js';
+import { AbstractProcessExecutor } from '../runtime/process/executor.js';
+import { type ModelClass, type Signal } from './types.js';
+/**
+ * Per-path-param, build the emit/receive type.
+ * If the param matches a model in .types(), it's Locked<T>. Otherwise string.
+ */
+type SignalPathArgs<TPath extends string, TTypes extends Record<string, ModelClass>> = {
+    [P in ExtractParamNames<TPath>]: ResolveParamType<P, TTypes> extends never ? string : Locked<InstanceType<Extract<ResolveParamType<P, TTypes>, ModelClass>>>;
+};
+/**
+ * Full signal args: path params (typed or string) + data fields from generic.
+ * If there are no path params and no data, the arg is void (just call with ()).
+ */
+type SignalArgs<TPath extends string, TTypes extends Record<string, ModelClass>, TData> = [ExtractParamNames<TPath>] extends [never] ? (TData extends void ? void : TData) : TData extends void ? SignalPathArgs<TPath, TTypes> : SignalPathArgs<TPath, TTypes> & TData;
+/**
+ * A built, callable signal.
+ *
+ * Structurally compatible with `Signal<[], TArgs, string>`:
+ *   - Identity tuple is empty (no positional args)
+ *   - TPayload is the full args object (merged path + data fields)
+ *   - Callable signature: `(args: TArgs)` — single object
+ *
+ * This lets the existing `signal()` primitive and race narrowing work
+ * unchanged. The compiler reads `.signalName` for routing.
+ */
+export interface BuiltSignal<TPath extends string, TTypes extends Record<string, ModelClass>, TData> extends Signal<[], SignalArgs<TPath, TTypes, TData>, string> {
+    /** Path pattern for identity extraction */
+    readonly path: TPath;
+    /** Types config, if .types() was called */
+    readonly typesConfig: TTypes;
+}
+/**
+ * Intermediate builder returned by `signal(path)`.
+ * Supports:
+ *   - `.data<T>()` to attach an extra data payload type
+ *   - `.types(config)` to attach model classes to path params
+ */
+export interface SignalBuilder<TPath extends string, TData> extends BuiltSignal<TPath, {}, TData> {
+    /**
+     * Attach model types to path params.
+     * Matched params become `Locked<T>` in the emit/receive signature.
+     */
+    types<TTypes extends Record<string, ModelClass>>(config: TTypes): BuiltSignal<TPath, TTypes, TData>;
+    /**
+     * Attach an extra data payload type. Fields from the generic are merged
+     * into the signal args alongside path params.
+     *
+     * Use `.data<T>()` instead of `signal<T>('/path')` — the latter doesn't
+     * work because TypeScript can't mix explicit + inferred generics.
+     */
+    data<TNewData>(): SignalBuilder<TPath, TNewData>;
+}
+/**
+ * The `signal` factory passed to `defineSignals`.
+ * Single generic `TPath` inferred from the path argument (via `const`).
+ *
+ * To add a data payload, use `.data<T>()`:
+ *   signal('/path').data<{ code: string }>()
+ *   signal('/path').data<{ reason: string }>().types({ Order })
+ */
+export interface SignalFactory {
+    <const TPath extends string>(path: TPath): SignalBuilder<TPath, void>;
+}
+/**
+ * Factory type — no constraint on TSignals to preserve literal type inference.
+ * The factory return is just a record of signal-like values.
+ */
+type SignalsFactory<TSignals> = (signal: SignalFactory) => TSignals;
+/**
+ * Define a group of signals. Returns a class that can be injected via DI.
+ *
+ * The factory receives a `signal` builder that's wired to the executor
+ * internally — no need to inject AbstractProcessExecutor manually.
+ *
+ * @example
+ * ```typescript
+ * export class PaymentSignals extends defineSignals(signal => ({
+ *   confirmed: signal('/payment/:order/confirmed').types({ Order }),
+ *   failed: signal<{ reason: string }>('/payment/:order/failed').types({ Order }),
+ * })) {}
+ * ```
+ */
+export declare function defineSignals<TSignals>(factory: SignalsFactory<TSignals>): import("../core/service.js").Service<Awaited<TSignals>, {
+    readonly executor: typeof AbstractProcessExecutor;
+}>;
+export {};
+//# sourceMappingURL=define-signals.d.ts.map

package/dist/process/define-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-signals.d.ts","sourceRoot":"","sources":["../../src/process/define-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAG3F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAgB,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAMxE;;;GAGG;AACH,KAAK,cAAc,CACjB,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IACvC;KACD,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,GAC9B,gBAAgB,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,KAAK,GACrC,MAAM,GACN,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;CAC3E,CAAC;AAEF;;;GAGG;AACH,KAAK,UAAU,CACb,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACzC,KAAK,IACH,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1C,CAAC,KAAK,SAAS,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC,GACnC,KAAK,SAAS,IAAI,GAChB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW,CAC1B,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACzC,KAAK,CACL,SAAQ,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAC5D,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAC5B,KAAK,SAAS,MAAM,EACpB,KAAK,CACL,SAAQ,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC;IACrC;;;OAGG;IACH,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAErC;;;;;;OAMG;IACH,IAAI,CAAC,QAAQ,KAAK,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;CACvE;AAqLD;;;GAGG;AACH,KAAK,cAAc,CAAC,QAAQ,IAAI,CAAC,MAAM,EAAE,aAAa,KAAK,QAAQ,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC;;GA0BxE"}

package/dist/process/define-signals.js

@@ -0,0 +1,222 @@
+/**
+ * defineSignals — declarative signal group with DI-wired executor.
+ *
+ * Replaces the manual pattern of injecting AbstractProcessExecutor and
+ * calling executor.createSignal() in every signal service.
+ *
+ * @example
+ * ```typescript
+ * export class PaymentSignals extends defineSignals(signal => ({
+ *   confirmed: signal('/payment/:order/confirmed').types({ Order }),
+ *   failed: signal<{ reason: string }>('/payment/:order/failed').types({ Order }),
+ * })) {}
+ *
+ * // Inject and emit:
+ * class OrderService extends defineService({
+ *   inject: { payment: PaymentSignals },
+ *   factory: ({ payment }) => ({
+ *     async markPaid(order: Locked<Order>) {
+ *       await payment.confirmed({ order });
+ *     },
+ *   }),
+ * }) {}
+ * ```
+ */
+import { defineService } from '../core/index.js';
+import { ADAPTER_KEY } from '../models/symbols.js';
+import { isReference } from '../models/reference/reference.js';
+import { AbstractProcessExecutor } from '../runtime/process/executor.js';
+import { SIGNAL_BRAND } from './types.js';
+// ============================================================================
+// Runtime: build a signal from a path + options
+// ============================================================================
+/**
+ * Derive the signal name (for routing) from a path.
+ * `/payment/:order/confirmed` → `payment.order.confirmed`
+ * (strips leading `/`, replaces `/` with `.`, strips `:` prefix from params)
+ */
+function pathToSignalName(path) {
+    if (!path)
+        return `anonymous.${Math.random().toString(36).slice(2, 10)}`;
+    return path
+        .replace(/^\//, '')
+        .replace(/\//g, '.')
+        .replace(/:/g, '');
+}
+/**
+ * Extract path param names from a path string.
+ * `/payment/:order/confirmed` → ['order']
+ */
+function extractPathParams(path) {
+    if (!path)
+        return [];
+    const params = [];
+    const regex = /:([a-zA-Z_][a-zA-Z0-9_]*)/g;
+    let match;
+    while ((match = regex.exec(path)) !== null) {
+        params.push(match[1]);
+    }
+    return params;
+}
+/**
+ * Resolve path param name against a types config using the same matching
+ * rules as applyTypesConfig: direct key, lowercased key, lowercased + "Ref".
+ */
+function resolveModelForParam(paramName, typesConfig) {
+    if (!typesConfig)
+        return undefined;
+    for (const [key, model] of Object.entries(typesConfig)) {
+        if (key === paramName)
+            return model;
+        if (key.toLowerCase() === paramName)
+            return model;
+        if (key.toLowerCase() + 'Ref' === paramName)
+            return model;
+    }
+    return undefined;
+}
+/**
+ * Extract identifier from a value that could be:
+ *   - A string (raw ID)
+ *   - A Reference (has .identifier)
+ *   - A Persistent or Lock entity (has ADAPTER_KEY)
+ *   - A plain object with .id
+ *
+ * Throws on null/undefined: silent string coercion to "null"/"undefined"
+ * produces valid-looking but colliding identities that stomp unrelated
+ * runs on the same path.
+ */
+function extractIdentifier(value) {
+    if (value === null || value === undefined) {
+        throw new Error('extractIdentifier: identifier is null/undefined');
+    }
+    if (typeof value === 'string')
+        return value;
+    // Reference
+    if (isReference(value)) {
+        return value.identifier;
+    }
+    // Persistent/Lock entity — check ADAPTER_KEY symbol
+    const rec = value;
+    const adapterKey = rec[ADAPTER_KEY];
+    if (adapterKey !== undefined)
+        return String(adapterKey);
+    // Fallback: .id property
+    if (rec.id !== undefined)
+        return String(rec.id);
+    throw new Error(`Cannot extract identifier from value: ${JSON.stringify(value)}`);
+}
+/**
+ * Build a callable signal for a given path + types config.
+ * The signal is wired to the executor for emission.
+ */
+function buildSignal(executor, path, typesConfig) {
+    const signalName = pathToSignalName(path);
+    const pathParams = extractPathParams(path);
+    // Duplicate path params collapse into a single identity key on emit
+    // (last write wins), which silently conflates two distinct entities.
+    // Fail at definition time so '/order/:id/line/:id' can't ship.
+    const seenParams = new Set();
+    for (const name of pathParams) {
+        if (seenParams.has(name)) {
+            throw new Error(`defineSignals: path '${path}' has duplicate param ':${name}'`);
+        }
+        seenParams.add(name);
+    }
+    const signal = async (argsOrVoid) => {
+        const args = argsOrVoid ?? {};
+        // Extract identity: for each path param, pull from args and get its identifier
+        const identity = {};
+        for (const param of pathParams) {
+            const value = args[param];
+            if (value === undefined) {
+                throw new Error(`Signal "${signalName}" missing required path param: ${param}`);
+            }
+            identity[param] = extractIdentifier(value);
+        }
+        // Build payload. Path params passed as Locked<T> cannot cross the wire —
+        // lock guarantees are local. Replace each typed path param with its
+        // Reference equivalent via Model.ref(locked) — receivers get Reference<T>
+        // and re-acquire a lock themselves if they need mutating access.
+        // Non-path-param fields pass through unchanged; the encoder throws on Locked<T>.
+        const payload = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (pathParams.includes(key)) {
+                const model = resolveModelForParam(key, typesConfig);
+                if (model && value && typeof value === 'object') {
+                    payload[key] = model.ref(value);
+                    continue;
+                }
+            }
+            payload[key] = value;
+        }
+        await executor.emit(signalName, identity, payload);
+    };
+    // Add signal metadata
+    Object.defineProperty(signal, SIGNAL_BRAND, {
+        value: SIGNAL_BRAND,
+        enumerable: false,
+    });
+    Object.defineProperty(signal, 'signalName', {
+        value: signalName,
+        enumerable: false,
+    });
+    Object.defineProperty(signal, '__identityParams', {
+        value: pathParams,
+        enumerable: false,
+    });
+    Object.defineProperty(signal, 'path', {
+        value: path,
+        enumerable: false,
+    });
+    Object.defineProperty(signal, 'typesConfig', {
+        value: typesConfig,
+        enumerable: false,
+    });
+    // Block direct `await signal` outside of process handlers
+    Object.defineProperty(signal, 'then', {
+        value: () => {
+            throw new Error(`Cannot await signal "${signalName}" directly. Use signal() inside a process handler.`);
+        },
+        enumerable: false,
+    });
+    return signal;
+}
+/**
+ * Define a group of signals. Returns a class that can be injected via DI.
+ *
+ * The factory receives a `signal` builder that's wired to the executor
+ * internally — no need to inject AbstractProcessExecutor manually.
+ *
+ * @example
+ * ```typescript
+ * export class PaymentSignals extends defineSignals(signal => ({
+ *   confirmed: signal('/payment/:order/confirmed').types({ Order }),
+ *   failed: signal<{ reason: string }>('/payment/:order/failed').types({ Order }),
+ * })) {}
+ * ```
+ */
+export function defineSignals(factory) {
+    return defineService({
+        inject: { executor: AbstractProcessExecutor },
+        factory: ({ executor }) => {
+            const makeBuilder = (resolvedPath, typesConfig) => {
+                const s = buildSignal(executor, resolvedPath, typesConfig);
+                // .types() → new builder with types config (runtime identical)
+                Object.defineProperty(s, 'types', {
+                    value: (config) => makeBuilder(resolvedPath, config),
+                    enumerable: false,
+                });
+                // .data<T>() → type-level only; runtime returns the same signal
+                Object.defineProperty(s, 'data', {
+                    value: () => s,
+                    enumerable: false,
+                });
+                return s;
+            };
+            const signalFactory = ((path) => makeBuilder(path, {}));
+            return factory(signalFactory);
+        },
+    });
+}
+//# sourceMappingURL=define-signals.js.map

package/dist/process/define-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-signals.js","sourceRoot":"","sources":["../../src/process/define-signals.ts"],"names":[],"mappings":"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"}

package/dist/process/delay-controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Process Delay Controller
+ *
+ * Handles process delay timers via the ScheduledTask transport.
+ * Add this controller to your cluster to enable durable process delays.
+ *
+ * @example
+ * ```typescript
+ * import '@justscale/process/cluster'
+ * import '@justscale/core/cluster/scheduled-task'
+ * import { ProcessDelayController } from '@justscale/process/delay-controller'
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(InMemoryScheduledTaskRepository)
+ *   .add(ProcessDelayController)
+ *   .build()
+ * ```
+ */
+import { ProcessRuntimeService } from './cluster-plugin.js';
+/**
+ * Controller that handles process delay timers.
+ *
+ * When a process calls `delay.seconds(30)`, the runtime schedules a task
+ * with namespace 'process' and type 'delay'. This controller receives
+ * those tasks when they're due and resumes the waiting process.
+ */
+export declare const ProcessDelayController: import("@justscale/core").ControllerDef<{
+    readonly runtime: typeof ProcessRuntimeService;
+}, {
+    readonly handleDelay: import("../cluster/scheduled-task/types.js").ScheduledTaskRouteDef<Record<string, unknown>, {
+        instanceId: string;
+        branchId?: string | undefined;
+    }>;
+}, import("@justscale/core").ControllerSettings>;
+//# sourceMappingURL=delay-controller.d.ts.map

package/dist/process/delay-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay-controller.d.ts","sourceRoot":"","sources":["../../src/process/delay-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAY5D;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;gDAejC,CAAC"}

package/dist/process/delay-controller.js

@@ -0,0 +1,55 @@
+/**
+ * Process Delay Controller
+ *
+ * Handles process delay timers via the ScheduledTask transport.
+ * Add this controller to your cluster to enable durable process delays.
+ *
+ * @example
+ * ```typescript
+ * import '@justscale/process/cluster'
+ * import '@justscale/core/cluster/scheduled-task'
+ * import { ProcessDelayController } from '@justscale/process/delay-controller'
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(InMemoryScheduledTaskRepository)
+ *   .add(ProcessDelayController)
+ *   .build()
+ * ```
+ */
+import { createController } from '../index.js';
+import { z } from 'zod';
+import { ScheduledTask } from '../cluster/scheduled-task/index.js';
+import { ProcessRuntimeService } from './cluster-plugin.js';
+import { TIMER_NAMESPACE, TIMER_TYPE } from '../runtime/process/scheduled-task-timer.js';
+import { ADAPTER_KEY } from '../models/symbols.js';
+/**
+ * Zod schema for process delay task payloads.
+ */
+const TimerPayloadSchema = z.object({
+    instanceId: z.string(),
+    branchId: z.string().optional(),
+});
+/**
+ * Controller that handles process delay timers.
+ *
+ * When a process calls `delay.seconds(30)`, the runtime schedules a task
+ * with namespace 'process' and type 'delay'. This controller receives
+ * those tasks when they're due and resumes the waiting process.
+ */
+export const ProcessDelayController = createController({
+    inject: {
+        runtime: ProcessRuntimeService,
+    },
+    routes: ({ runtime }) => ({
+        handleDelay: ScheduledTask(TIMER_NAMESPACE, TIMER_TYPE)
+            .payload(TimerPayloadSchema)
+            .handle(async ({ task, payload }) => {
+            runtime.handleTimerFired({
+                timerId: task[ADAPTER_KEY],
+                instanceId: payload.instanceId,
+                branchId: payload.branchId,
+            });
+        }),
+    }),
+});
+//# sourceMappingURL=delay-controller.js.map

package/dist/process/delay-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay-controller.js","sourceRoot":"","sources":["../../src/process/delay-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;GAEG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;IACrD,MAAM,EAAE;QACN,OAAO,EAAE,qBAAqB;KAC/B;IACD,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QACxB,WAAW,EAAE,aAAa,CAAC,eAAe,EAAE,UAAU,CAAC;aACpD,OAAO,CAAC,kBAAkB,CAAC;aAC3B,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;YAClC,OAAO,CAAC,gBAAgB,CAAC;gBACvB,OAAO,EAAG,IAA2C,CAAC,WAAW,CAAW;gBAC5E,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAC;QACL,CAAC,CAAC;KACL,CAAC;CACH,CAAC,CAAC"}