@codenotch/process 0.0.0-dev

package/dist/types/lib/instant.d.ts

@@ -0,0 +1,41 @@
+import { Duration } from './duration';
+import type { DurationLike } from './types';
+export type InstantUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
+/**
+ * An instant in time — a thin ISO-8601 UTC wrapper, culture-safe by construction.
+ * Immutable; serializes to an ISO string (toJSON) in records, queries and history.
+ * A datetime without a zone offset is read as UTC — never as the host's local time.
+ */
+export declare class Instant {
+    private readonly ms;
+    private constructor();
+    /** Parses an ISO-8601 string (or adopts an Instant / epoch milliseconds). */
+    static from(value: string | number | Instant): Instant;
+    /** An Instant from milliseconds since the Unix epoch (UTC). */
+    static fromEpochMillis(epochMillis: number): Instant;
+    /** Standard comparator: negative when a < b, 0 when equal, positive when a > b. */
+    static compare(a: Instant | string, b: Instant | string): number;
+    /** This instant shifted forward. Calendar components (months/years) clamp the day (Jan 31 + 1 month = Feb 28/29). */
+    plus(duration: DurationLike): Instant;
+    /** This instant shifted backward. */
+    minus(duration: DurationLike): Instant;
+    /** The exact elapsed time from `other` to this instant, as a fixed Duration. */
+    diff(other: Instant | string): Duration;
+    isBefore(other: Instant | string): boolean;
+    isAfter(other: Instant | string): boolean;
+    equals(other: Instant | string): boolean;
+    /** The start of the containing unit, in UTC. Weeks start on Monday (ISO-8601). */
+    startOf(unit: InstantUnit): Instant;
+    /** The last millisecond of the containing unit, in UTC. */
+    endOf(unit: InstantUnit): Instant;
+    /** Milliseconds since the Unix epoch. */
+    epochMillis(): number;
+    /** ISO-8601 UTC text with millisecond precision ('2026-01-31T09:30:00.000Z'). */
+    toISOString(): string;
+    toJSON(): string;
+    toString(): string;
+    /** Epoch milliseconds — makes <, >, <=, >= comparisons between Instants work. */
+    valueOf(): number;
+}
+/** @internal Instant factory used by the runtime (ctx.now). */
+export declare const instantFromEpochMillis: (epochMillis: number) => Instant;

package/dist/types/lib/meters.d.ts

@@ -0,0 +1,61 @@
+import type { ActivityOptions } from './context';
+/** Who the units belong to: a user, or nobody ({} — still counted, recorded without a user). */
+export type MeterTarget = {
+    user?: string;
+};
+export interface MeterAddOptions {
+    /**
+     * Optional dedup reference: the same reference never counts twice on this meter.
+     * Defaults to the activity execution's identity, so a crash re-run counts once anyway.
+     */
+    reference?: string;
+}
+export interface MeterAddResult {
+    /** False = the meter's period total is at its configured cap; nothing was counted. */
+    applied: boolean;
+    /** True when the reference was already recorded. */
+    replayed: boolean;
+    /** The addressed total after the add (or as-is when refused/replayed). */
+    total: number;
+}
+export interface MeterTotalQuery {
+    user?: string;
+    /** 'YYYY-MM'; default the current period. */
+    period?: string;
+}
+export interface MeterBreakdownQuery {
+    /** 'YYYY-MM'; default the current period. */
+    period?: string;
+    /** Page size, default 100. */
+    limit?: number;
+    /** The previous page's `next` cursor. */
+    after?: string;
+}
+export interface MeterBreakdownRow {
+    /** Null = the usage recorded without a user. */
+    user: string | null;
+    total: number;
+}
+export interface MeterBreakdownPage {
+    items: MeterBreakdownRow[];
+    totalCount: number;
+    /** Pass as `after` to continue; null = no more rows. */
+    next: string | null;
+}
+export interface MeterHandle {
+    /**
+     * Count units on a custom meter (framework meters refuse with metering.reserved). A
+     * refusal ({applied: false}) means the configured cap is reached — a result to branch
+     * on, not an error.
+     */
+    add(target: MeterTarget, amount: number, opts?: MeterAddOptions & ActivityOptions): Promise<MeterAddResult>;
+    /** The addressed total; 0 when nothing was recorded. Omit user for the no-user row. */
+    total(query?: MeterTotalQuery, opts?: ActivityOptions): Promise<number>;
+    /** Per-user totals of one period, cursor-paged — the billing loop's iterator. */
+    breakdown(query?: MeterBreakdownQuery, opts?: ActivityOptions): Promise<MeterBreakdownPage>;
+}
+/** @internal Same call channel as the connector handles. */
+type MeterCall = <T>(name: string, input: Record<string, unknown>, opts: ActivityOptions | undefined) => Promise<T>;
+/** @internal ctx.meter factory over the activity channel — bound by createContext. */
+export declare const createMeterFactory: (call: MeterCall) => (name: string) => MeterHandle;
+export {};

package/dist/types/lib/registry.d.ts

@@ -0,0 +1,131 @@
+import type { ConnectorKindEvents, ProjectConnectors } from './connectors';
+import type { Context } from './context';
+import type { DeliveryOptions, Json, Serializable } from './types';
+/** Event ids a process can send to its caller, with their payload types. */
+export type EventMap = Record<string, Serializable>;
+/** Phantom carrier for the declared event map (the value exists only for type inference). */
+export interface EventsDecl<E extends EventMap> {
+    readonly __events?: E;
+}
+/**
+ * Declares the events this process can send to its caller, typed on both sides:
+ * `events: events<{ 'sla.breach': { ticketId: string } }>()`.
+ */
+export declare const events: <E extends EventMap>() => EventsDecl<E>;
+/** Opaque, typed handle to a defined process — what process() returns. */
+export interface Process<In = unknown, Out = unknown, E extends EventMap = {}> {
+    readonly id: string;
+    /** @internal Phantom fields carrying the type parameters. */
+    readonly __types?: {
+        input: In;
+        output: Out;
+        events: E;
+    };
+}
+/** Auth scope of a process. Gates EXTERNAL starts only. */
+export type AuthScope = 'public' | 'external' | 'internal' | 'system';
+export interface ProcessAuth {
+    scope: AuthScope;
+    /** Required roles of the caller. */
+    roles?: string[];
+}
+/**
+ * Start concurrency control. The key is GLOBAL to the project — any process claiming
+ * the same key conflicts; scope a key to one process by prefixing its name.
+ * limit > 1 turns the mutex into a semaphore.
+ */
+export interface Concurrency<In> {
+    key: (input: In) => string;
+    /** Max live instances holding this key. Default 1. */
+    limit?: number;
+    /**
+     * ignore = skip the new start; replace = supersede a holder (the replaced run is
+     * cancelled and unwinds its compensation chain); queue = run when a slot frees.
+     */
+    onConflict: 'ignore' | 'replace' | 'queue';
+}
+export interface ProcessOptions {
+    logs?: 'on' | 'off';
+}
+/** Opaque start trigger. Triggers gate external starts; ctx.call bypasses them. */
+export interface Trigger {
+    /** @internal */
+    readonly kind: string;
+}
+/**
+ * API start triggers. Path/query params and body merge into the input. The HTTP
+ * response is what ctx.respond sent — or, when the process returns without
+ * responding, 200 with the output as JSON body. Uncaught errors map to defaults
+ * (NotFoundError → 404, ProcessError → 400 with its code, anything else → 500).
+ */
+export declare const api: Readonly<{
+    get: (route: string) => Trigger;
+    post: (route: string) => Trigger;
+    put: (route: string) => Trigger;
+    delete: (route: string) => Trigger;
+}>;
+/** Signal start trigger. Hierarchical refs: 'ticket' receives 'ticket.done.1'. */
+export declare const signal: (ref: string, opts?: DeliveryOptions) => Trigger;
+/**
+ * A connector binding name. The generated connectors.d.ts (augmenting ProjectConnectors)
+ * makes the project's binding names autocomplete; any string stays accepted.
+ */
+export type ConnectorBindingName = (keyof ProjectConnectors & string) | (string & {});
+/**
+ * The event types a binding can receive: its kind's union when the binding and the kind
+ * are known (ProjectConnectors + ConnectorKindEvents), any string otherwise.
+ */
+export type ConnectorEventName<B> = B extends keyof ProjectConnectors ? ProjectConnectors[B] extends keyof ConnectorKindEvents ? ConnectorKindEvents[ProjectConnectors[B]] | (string & {}) : string : string;
+/**
+ * Connector-event start trigger: starts the process when the connector bound to the
+ * named manifest parameter receives a verified provider event — a Slack message
+ * ('message'), a payment webhook ('payment.succeeded'), … The binding must be named (a
+ * trigger cannot infer the kind). Input = { type, eventRef, payload }. With a generated
+ * connectors.d.ts both arguments autocomplete; plain strings always compile.
+ */
+export declare const connectorEvent: <B extends ConnectorBindingName>(binding: B, event: ConnectorEventName<B>, opts?: DeliveryOptions) => Trigger;
+/**
+ * Timer start trigger — a cron expression ('0 6 * * 1-5'), an ISO-8601 recurrence
+ * ('R/PT4H'), a one-shot ISO date, or any DurationLike repeat interval.
+ */
+export declare const timer: (schedule: string | number | object, opts?: DeliveryOptions) => Trigger;
+/**
+ * Deploy-lifecycle start: runs after every successful install or version update of
+ * the project. install({ once: true }) runs on the first install only. A failure
+ * lands in the deployment report; it does not roll the deploy back.
+ */
+export declare const install: (opts?: {
+    once?: boolean;
+}) => Trigger;
+/** Manual start — started via API/portal only. This is the default when trigger is absent. */
+export declare const manual: () => Trigger;
+export interface ProcessDefinition<In, Out, E extends EventMap = {}> {
+    /** Unique per project. */
+    id: string;
+    description?: string;
+    /** MANDATORY start authorization. */
+    auth: ProcessAuth;
+    /**
+     * How the process can be started. Absent = manual(). An array makes one process
+     * reachable several ways: [signal('order.paid'), api.post('/orders/paid')].
+     */
+    trigger?: Trigger | Trigger[];
+    concurrency?: Concurrency<In>;
+    /** Events this process can send to its caller (typed on both sides). */
+    events?: EventsDecl<E>;
+    options?: ProcessOptions;
+    run(ctx: Context<E>, input: In): Promise<Out>;
+}
+/**
+ * Declares a process. The definition is registered at bundle load; the returned
+ * handle is what ctx.call takes for a fully typed call.
+ */
+export declare const process: <In, Out, E extends EventMap = {}>(def: ProcessDefinition<In, Out, E>) => Process<In, Out, E>;
+/** @internal Deploy-time metadata of every declared process. */
+export declare const processMetadata: () => Json[];
+/** @internal Lookup for the bootstrap (__start / __concurrencyKey). */
+export declare const getProcessDefinition: (id: string | null | undefined) => ProcessDefinition<never, unknown, EventMap> | undefined;
+/** @internal */
+export declare const registrySize: () => number;
+/** @internal The single declared process, when there is exactly one. */
+export declare const singleProcessDefinition: () => ProcessDefinition<never, unknown, EventMap> | undefined;

package/dist/types/lib/renderings.d.ts

@@ -0,0 +1,75 @@
+import type { ActivityOptions } from './context';
+import type { EmailHandle, EmailMessage } from './connectors';
+import type { Serializable, Template } from './types';
+/** What an email template's render function returns. */
+export interface EmailTemplatePayload {
+    subject: string;
+    html: string;
+    /** Plain-text alternative. */
+    text?: string;
+}
+/** What a pdf template's render function returns: print HTML, turned into bytes server-side. */
+export interface PdfTemplatePayload {
+    html: string;
+}
+/** Page setup a pdf template declares (template.pdf({ … }, render)). A template's own @page CSS wins. */
+export interface PdfPageOptions {
+    /** Paper format; default A4. */
+    format?: 'A3' | 'A4' | 'A5' | 'Letter' | 'Legal';
+    /** Page margins: '20mm', '0.5in' or a bare number of millimeters. Default 20mm. */
+    margins?: string | number;
+    landscape?: boolean;
+}
+/**
+ * Metadata of a stored rendering. The bytes never travel through the process: consumers
+ * resolve them by id (attach to an email, or read through the renderings API).
+ */
+export interface StoredRendering {
+    renderingId: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+}
+/** Options of ctx.render.email — plain activity options; email renderings are never stored. */
+export type RenderOptions = ActivityOptions;
+/** Options of ctx.render.pdf — the stored document's name and its listing metadata. */
+export type PdfRenderOptions = ActivityOptions & {
+    /** Stored file name; default <template>.pdf. */
+    filename?: string;
+    /** The user the document is about (an invoice's customer) — opaque, filterable in the listing. */
+    user?: string;
+    /** Freeform labels ('invoice', 'pos_london', …) — filterable in the listing. No '|'. */
+    tags?: string[];
+};
+export type RenderSendOptions = ActivityOptions & {
+    /** The connector binding to send through; default: the project's only one of the kind. */
+    connector?: string;
+};
+/** A rendered email: the payload, plus send() through the project's email connector. */
+export type RenderedEmail = EmailTemplatePayload & {
+    /**
+     * Send this rendering as one email: the rendered subject/html/text merged under the
+     * given message (the message wins on conflict). Same contract as ctx.email().send —
+     * at-least-once, single attempt by default.
+     */
+    send(message: Omit<EmailMessage, 'subject' | 'html' | 'text'> & Partial<Pick<EmailMessage, 'subject' | 'html' | 'text'>>, opts?: RenderSendOptions): Promise<void>;
+};
+export interface RenderApi {
+    /** Render an email template. The template is the imported handle, or its manifest name. */
+    email<D>(template: Template<D, 'email'>, data: D, opts?: RenderOptions): Promise<RenderedEmail>;
+    email(template: string, data?: Serializable, opts?: RenderOptions): Promise<RenderedEmail>;
+    /**
+     * Render a pdf template. Always stored: the result is the rendering reference — pass it
+     * to email attachments, or hand the id to the renderings API. The bytes never enter the
+     * process. `user` and `tags` index the stored document for the listing.
+     */
+    pdf<D>(template: Template<D, 'pdf'>, data: D, opts?: PdfRenderOptions): Promise<StoredRendering>;
+    pdf(template: string, data?: Serializable, opts?: PdfRenderOptions): Promise<StoredRendering>;
+}
+/** @internal How ctx.render reaches the activity channel and the connectors — bound by createContext. */
+export interface RenderDeps {
+    call: <T>(name: string, input: Record<string, unknown>, opts: ActivityOptions | undefined) => Promise<T>;
+    email: (binding?: string) => EmailHandle;
+}
+/** @internal The ctx.render factory. */
+export declare const createRenderFactory: (deps: RenderDeps) => RenderApi;

package/dist/types/lib/subscriptions.d.ts

@@ -0,0 +1,61 @@
+import type { ActivityOptions } from './context';
+/** The subscriber: a subscription always belongs to a user. */
+export type SubscriptionTarget = {
+    user: string;
+};
+/** A calendar period, applied host-side in UTC (months clamp to month ends). */
+export interface SubscriptionPeriod {
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+}
+/** Exactly one of period (from now / from the current term end) and until (absolute ISO). */
+export interface SubscriptionTerm {
+    period?: SubscriptionPeriod;
+    until?: string;
+}
+export type SubscriptionState = 'pending' | 'active' | 'grace' | 'expired';
+export interface SubscriptionSnapshot {
+    id: string;
+    plan: string;
+    user: string;
+    state: SubscriptionState;
+    paidUntil: string;
+    graceUntil: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+export interface SubscriptionHandle {
+    /**
+     * A new subscription — the dev grants after taking payment. Fails with
+     * subscription.alreadyActive when the user already holds a live one of this plan
+     * (extend instead).
+     */
+    activate(target: SubscriptionTarget, term: SubscriptionTerm, opts?: ActivityOptions): Promise<SubscriptionSnapshot>;
+    /**
+     * Moves the live subscription's term: a period extends from max(paidUntil, now) — no
+     * proration, ever — and a grace subscription reactivates. Fails with
+     * subscription.notFound when there is no live one.
+     */
+    extend(target: SubscriptionTarget, term: SubscriptionTerm, opts?: ActivityOptions): Promise<SubscriptionSnapshot>;
+    /** The live subscription, or null (terminal ones are history, not addressable here). */
+    get(target: SubscriptionTarget, opts?: ActivityOptions): Promise<SubscriptionSnapshot | null>;
+    /** The one entitlement query: true while active or in grace.  */
+    isActive(target: SubscriptionTarget, opts?: ActivityOptions): Promise<boolean>;
+    /**
+     * atPeriodEnd keeps the paid term and stops it at paidUntil; without it the subscription
+     * expires immediately, remaining term forfeited (no proration).
+     */
+    cancel(target: SubscriptionTarget, opts?: {
+        atPeriodEnd?: boolean;
+    } & ActivityOptions): Promise<SubscriptionSnapshot>;
+}
+/** @internal Same call channel as the connector handles. */
+type SubscriptionCall = <T>(name: string, input: Record<string, unknown>, opts: ActivityOptions | undefined) => Promise<T>;
+/** @internal ctx.subscription factory over the activity channel — bound by createContext. */
+export declare const createSubscriptionFactory: (call: SubscriptionCall) => (plan: string, scope?: {
+    tenant?: boolean;
+}) => SubscriptionHandle;
+export {};

package/dist/types/lib/types.d.ts

@@ -0,0 +1,89 @@
+/** JSON-compatible data. Payloads, databag values, history entries. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+/** What the engine can journal: JSON plus the engine value types (ISO-serialized). */
+export type Serializable = Json | {
+    toJSON(): Json;
+} | undefined | Serializable[] | {
+    [key: string]: Serializable;
+};
+/**
+ * Typed handle to a deployed activity — what a `*.activity` import looks like from
+ * workflow code (the deploy bundler rewrites the import to a reference stub; the
+ * Node implementation never enters the sandbox). Pass it to ctx.activity for a
+ * fully typed invocation.
+ */
+export type Activity<In = never, Out = unknown> = {
+    readonly __codenotchActivity: true;
+    /** @internal Phantom carrier of the type parameters. */
+    readonly __activityTypes?: {
+        input: In;
+        output: Out;
+    };
+};
+/** The kinds of output a rendering template produces. */
+export type TemplateKind = 'email' | 'pdf';
+/**
+ * Typed handle to a manifest-declared rendering template — what a template import looks
+ * like from workflow code (the deploy bundler rewrites the import to a reference stub;
+ * the template implementation never enters the sandbox). Pass it to ctx.render.* for a
+ * fully typed, kind-checked invocation.
+ */
+export type Template<Data = never, Kind extends TemplateKind = TemplateKind> = {
+    readonly __codenotchTemplate: true;
+    /** @internal Phantom carrier of the type parameters. */
+    readonly __templateTypes?: {
+        data: Data;
+        kind: Kind;
+    };
+};
+/** Duration as a components object. Calendar components (years/months) apply calendar arithmetic. */
+export interface DurationParts {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * A duration accepted everywhere a length of time is expected:
+ *   'P3D' / 'PT5M'          ISO-8601
+ *   180000                  raw milliseconds
+ *   '3.00:00:00'            .NET TimeSpan serialization
+ *   { days: 3 }             components object
+ *   Duration.from(...)      a Duration value
+ * Dates and datetimes are always ISO-8601.
+ */
+export type DurationLike = string | number | DurationParts | {
+    toMillis(): number;
+};
+/** Retry policy of an activity execution or a delivery. */
+export interface RetryPolicy {
+    /** Total attempts (the first execution included). */
+    attempts: number;
+    /** Fixed delay between attempts. */
+    interval?: DurationLike;
+    /** Base delay for exponential backoff (alternative to interval). */
+    backoff?: DurationLike;
+}
+/** Receiver-side delivery policy of a signal wait or trigger. */
+export interface DeliveryOptions {
+    /**
+     * 'delivery' (default): ack once accepted/started. 'end': ack only when the run
+     * finishes. v1 supports only 'delivery'; declaring 'end' is a deploy error.
+     */
+    ack?: 'delivery' | 'end';
+    /** Dispatch retry: how the dispatcher retries reaching this instance. */
+    retry?: RetryPolicy;
+}
+/** One JSON-patch operation (RFC 6902) for the transformations merge can't express. */
+export interface JsonPatchOp {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    from?: string;
+    value?: Serializable;
+}

package/dist/types/lib/urls.d.ts

@@ -0,0 +1,36 @@
+/** A query value: null renders the bare key, undefined omits it, arrays repeat the key. */
+export type QueryValue = string | number | boolean | null | undefined | (string | number | boolean)[];
+/** The parts of a parsed URL. */
+export interface UrlParts {
+    /** Lowercase scheme without the colon ('https'). */
+    scheme: string;
+    /** Hostname, without port ('api.example.com'). */
+    host: string;
+    /** Port number, or null when the URL carries none. */
+    port: number | null;
+    /** Path including the leading slash ('/v1/users'); '/' when absent. */
+    path: string;
+    /** Decoded query parameters; repeated keys collect into arrays. */
+    query: Record<string, string | string[]>;
+    /** Fragment without the '#', or null. */
+    fragment: string | null;
+}
+/**
+ * Renders query parameters as a query string (no leading '?'). Arrays repeat the
+ * key, null renders the bare key, undefined entries are omitted.
+ */
+export declare const encodeQuery: (params: Record<string, QueryValue>) => string;
+/** Parses a query string ('a=1&b=2', leading '?' tolerated). Repeated keys collect into arrays. */
+export declare const parseQuery: (queryString: string) => Record<string, string | string[]>;
+/**
+ * Builds a URL from a base and optional path/query/fragment, with correct escaping:
+ * url.build('https://api.example.com', { path: ['users', id], query: { page: 2 } }).
+ * Path segments are individually encoded; a string path is appended as-is.
+ */
+export declare const build: (base: string, options?: {
+    path?: string | (string | number)[];
+    query?: Record<string, QueryValue>;
+    fragment?: string;
+}) => string;
+/** Parses an absolute URL into its parts. Throws on anything unparseable. */
+export declare const parse: (url: string) => UrlParts;

package/dist/types/lib/userTasks.d.ts

@@ -0,0 +1,119 @@
+import { Instant } from './instant';
+import type { DurationLike, Json, Serializable } from './types';
+/** One field of the declarative form (see USER_TASKS.md for the full schema rules). */
+export type UserTaskFormField = {
+    type: 'markdown';
+    content: string;
+} | {
+    key: string;
+    type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'datetime';
+    label?: string;
+    description?: string;
+    placeholder?: string;
+    required?: boolean;
+    readonly?: boolean;
+    default?: Json;
+    /** text/textarea */
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    /** number / date ('yyyy-MM-dd') / datetime (ISO-8601) */
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    /** select/multiselect */
+    options?: {
+        value: string;
+        label?: string;
+    }[];
+    minItems?: number;
+    maxItems?: number;
+};
+export interface UserTaskForm {
+    kind?: 'schema';
+    schemaVersion?: number;
+    fields: UserTaskFormField[];
+}
+/**
+ * Who is asked: one user, any holder of a project role (they claim from the queue), or —
+ * public — anyone holding the share link the handle exposes.
+ */
+export type UserTaskAssignment = {
+    user: string;
+} | {
+    role: string;
+} | {
+    public: true;
+};
+export interface UserTaskDefinition {
+    title: string;
+    description?: string;
+    form: UserTaskForm;
+    assign: UserTaskAssignment;
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    tags?: string[];
+    /** Informational absolute deadline (Instant or ISO-8601) — drives sorting/overdue badges, never a state change. */
+    due?: Instant | string;
+    /** The same deadline, relative to now. Use due or dueIn, not both. */
+    dueIn?: DurationLike;
+    /** Read-only data shown beside the form (order details, amounts, …). */
+    context?: Serializable;
+}
+export interface UserTaskOptions {
+    /**
+     * Keep the task alive when this run fails or is cancelled. Default false: the task is
+     * cancelled with the run's compensation, so no orphaned work lingers in anyone's queue.
+     */
+    detached?: boolean;
+}
+/** What a completed task resolves with. */
+export interface UserTaskOutcome {
+    /** The validated submission — exactly the editable fields' values. */
+    output: Json;
+    /** The completing user; absent when an anonymous share-link holder completed. */
+    completedBy?: string;
+    completedAt: Instant;
+}
+export interface UserTaskSnapshot {
+    id: string;
+    state: 'open' | 'inProgress' | 'completed' | 'cancelled';
+    mode: 'user' | 'role' | 'public';
+    title: string;
+    assignee?: string;
+    candidateRole?: string;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    tags: string[];
+    dueAt?: Instant;
+    output?: Json;
+    completedBy?: string;
+    completedAt?: Instant;
+    cancelledAt?: Instant;
+}
+export interface UserTaskHandle {
+    readonly id: string;
+    /** The portal share path/URL (Public tasks) — mail it, return it, put it in a chat message. */
+    readonly sharePath?: string;
+    readonly shareUrl?: string;
+    /**
+     * Parks until a human completes the task, then resolves with the validated output.
+     * Rejects with ProcessError 'userTask.cancelled' when the task is cancelled instead —
+     * race it with a timer for escalation: ctx.race({ done: task.outcome, late: ctx.wait('P2D') }).
+     */
+    readonly outcome: Promise<UserTaskOutcome>;
+    /** The task's current state, polled from the store. Null when it does not exist (yet). */
+    get(): Promise<UserTaskSnapshot | null>;
+    /** Reassign to another user (User and claimed Role tasks). */
+    assign(userId: string): Promise<void>;
+    /** Cancel the task if it is still active; false when it already reached a terminal state. */
+    cancel(): Promise<boolean>;
+}
+/** @internal What the factory needs from the context runtime. */
+export type UserTaskHooks = {
+    call: <T>(name: string, input: Record<string, unknown>) => Promise<T>;
+    park: <T>(kind: string, args: unknown) => Promise<T>;
+    nextUuid: () => string;
+    nowMs: () => number;
+    onCompensate: (fn: () => void | Promise<void>) => void;
+};
+/** @internal ctx.userTask over the runtime hooks — bound by createContext. */
+export declare const createUserTaskFactory: (hooks: UserTaskHooks) => (definition: UserTaskDefinition, opts?: UserTaskOptions) => Promise<UserTaskHandle>;

package/dist/types/lib/validators.d.ts

@@ -0,0 +1,22 @@
+/**
+ * String validators: is.email(value), is.uuid(value), … Every check returns a boolean
+ * and never throws — non-string input is simply false.
+ */
+export declare const is: {
+    /** A plausible email address (practical single-address shape, not full RFC 5322). */
+    email: (value: unknown) => boolean;
+    /** A UUID in canonical hyphenated form, any version. */
+    uuid: (value: unknown) => boolean;
+    /** An absolute http(s) URL with a valid host. */
+    url: (value: unknown) => boolean;
+    /** An ISO-8601 calendar date ('2026-01-31'), month/day ranges checked. */
+    isoDate: (value: unknown) => boolean;
+    /** An ISO-8601 datetime ('2026-01-31T09:30:00Z', offset or zoneless). */
+    isoDateTime: (value: unknown) => boolean;
+    /** An ISO-8601 duration ('P3D', 'PT1H30M'). */
+    isoDuration: (value: unknown) => boolean;
+    /** A dotted-quad IPv4 address. */
+    ipv4: (value: unknown) => boolean;
+    /** An IPv6 address (compressed forms and IPv4-mapped tails included). */
+    ipv6: (value: unknown) => boolean;
+};

package/dist/types/lib/webPush.d.ts

@@ -0,0 +1,30 @@
+import type { ActivityOptions } from './context';
+import type { ConnectorCall } from './connectors';
+import type { Json } from './types';
+export interface WebPushMessage {
+    /** The id of the user to notify. */
+    user: string;
+    /** The react application whose subscription receives it (its service worker shows the notification). */
+    app: string;
+    title: string;
+    body: string;
+    icon?: string;
+    /** Arbitrary payload handed to the app's service worker along with the notification. */
+    data?: Json;
+}
+export type WebPushDeviceStatus = 'success' | 'disconnected' | 'error';
+export interface WebPushResult {
+    /** Devices delivered to. 0 when the user has no subscription — push is best-effort, not an error. */
+    sent: number;
+    /** Per-device outcome; 'disconnected' means the subscription was gone and has been removed. */
+    devices: Record<string, WebPushDeviceStatus>;
+}
+export interface WebPushApi {
+    /**
+     * Send one notification to every device the user subscribed. At-least-once and NOT
+     * retried by default (a retry could notify twice) — pass opts.retry to opt in.
+     */
+    send(message: WebPushMessage, opts?: ActivityOptions): Promise<WebPushResult>;
+}
+/** @internal The ctx.webPush factory — same activity channel as the connector handles. */
+export declare const createWebPushApi: (call: ConnectorCall) => WebPushApi;