@codenotch/process 0.0.0-dev

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

@@ -0,0 +1,307 @@
+import { engine, type EngineBindings } from './bindings';
+import { type ChatHandle, type ConnectorBindingOf, type EmailHandle, type FileTransferHandle, type LlmHandle, type ObjectStorageHandle, type PaymentHandle, type SmsHandle } from './connectors';
+import { type CreditsHandle } from './credits';
+import { type MeterHandle } from './meters';
+import { type SubscriptionHandle } from './subscriptions';
+import { type UserTaskDefinition, type UserTaskHandle, type UserTaskOptions } from './userTasks';
+import { type RenderApi } from './renderings';
+import { type WebPushApi } from './webPush';
+import { Instant } from './instant';
+import type { EventMap, Process } from './registry';
+import type { Activity, DeliveryOptions, DurationLike, Json, JsonPatchOp, RetryPolicy, Serializable } from './types';
+/** Armed subscription handle. Auto-disposed when run() exits (any path). */
+export interface ArmedHandler {
+    stop(): void;
+}
+export interface RecordGrant {
+    user: string;
+    /** r = read, u = update, d = delete. */
+    access: 'r' | 'ru' | 'rud';
+}
+export interface WriteOptions {
+    /** Per-record RLS grants. */
+    grants?: RecordGrant[];
+}
+/** Typed handle to one of the project's tables. */
+export interface TableHandle<T> {
+    /** Single-record lookup by id (string) or key match ({ Email: '…' }). Null when absent. */
+    read(key: string | Partial<T>): Promise<T | null>;
+    /** read() or throw NotFoundError. */
+    require(key: string | Partial<T>): Promise<T>;
+    /**
+     * Merge-upsert by record id. Only the fields present in `data` are written:
+     * `null` clears a field, `undefined`/absent means no change. Id/CreatedAt/UpdatedAt
+     * are storage-managed and ignored. A write that creates the row must carry every
+     * non-nullable field. A write the database rejects (any constraint) throws a
+     * catchable `datastore.writeRejected` error and nothing is written.
+     */
+    write(id: string, data: Partial<T>, opts?: WriteOptions): Promise<void>;
+    /** JSON-patch ops for transformations merge can't express. */
+    patch(id: string, ops: JsonPatchOp[], opts?: WriteOptions): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/** Handle to one of the project's document stores. Same field rules as TableHandle. */
+export interface DocStoreHandle<T> {
+    read(id: string): Promise<T | null>;
+    /** read() or throw NotFoundError. */
+    require(id: string): Promise<T>;
+    /** Merge-upsert; `null` stores an explicit null under the key — removing the key is a patch remove op. */
+    write(id: string, data: Partial<T>): Promise<void>;
+    patch(id: string, ops: JsonPatchOp[]): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * The project's tables, keyed by name — augmented via declaration merging by the
+ * generated db-schema.d.ts so every table and row type autocompletes.
+ */
+export interface ProjectTables {
+    [name: string]: TableHandle<Json>;
+}
+export interface ProjectDocs {
+    [name: string]: DocStoreHandle<Json>;
+}
+export interface CallTarget {
+    /** Absent = own project. */
+    project?: string;
+    process: string;
+}
+export interface CallOptions {
+    /**
+     * detached: true — the callee outlives this instance (fire-and-forget).
+     * Default false: a non-detached, un-awaited callee still running when this
+     * instance completes is cancelled (structured concurrency).
+     */
+    detached?: boolean;
+}
+/**
+ * Thenable handle to a called process instance. Await it now, hold it and await
+ * later, or never await it (see CallOptions).
+ */
+export interface CallHandle<Out, E extends EventMap = EventMap> extends PromiseLike<Out> {
+    /**
+     * Park until the callee sends this declared event once. Rejects with
+     * CallCompletedError if the callee completes first — for "event or done,
+     * whichever first", race it: ctx.race({ ev: call.waitEvent('x'), done: call }).
+     */
+    waitEvent<K extends keyof E & string>(event: K): Promise<E[K]>;
+    /** Armed listener for a declared callee event. Buffered from start. */
+    onEvent<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void | Promise<void>): ArmedHandler;
+    /** Send a signal targeted at this instance (not broadcast). */
+    sendSignal(ref: string, data?: Serializable): Promise<void>;
+    cancel(reason?: string): Promise<void>;
+}
+export interface CallerIdentity {
+    id: string;
+    email?: string;
+    name?: string;
+    roles: string[];
+    /** A logged-in user is either internal or external (public/system cannot log in). */
+    group: 'internal' | 'external';
+    language?: string;
+}
+export interface ProcessLogger {
+    debug(message: string, data?: Serializable): void;
+    info(message: string, data?: Serializable): void;
+    warn(message: string, data?: Serializable): void;
+    error(message: string, data?: Serializable): void;
+}
+export interface ActivityOptions {
+    /** Retries happen inside ONE journaled execution — a policy change never diverges an old replay. */
+    retry?: RetryPolicy;
+    timeout?: DurationLike;
+}
+export interface FetchOptions {
+    /** HTTP method. Default GET. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    headers?: Record<string, string>;
+    /** A string is sent as-is; any object is JSON-serialized (content-type json unless set). */
+    body?: string | Serializable;
+    /**
+     * Adds an 'Idempotency-Key' header carrying this execution's stable key
+     * (instance:generation:seq) — the same value on every at-least-once re-run, so
+     * providers that honor the header dedupe non-idempotent calls (POSTs).
+     */
+    idempotencyKey?: boolean;
+    retry?: RetryPolicy;
+    timeout?: DurationLike;
+}
+export interface FetchResponse<T = Json> {
+    /** HTTP status code. Non-2xx is NOT thrown — check ok/status. */
+    status: number;
+    /** True for 2xx. */
+    ok: boolean;
+    /** Response headers, lowercase names; repeated headers joined with ', '. */
+    headers: Record<string, string>;
+    /** Raw response body text. */
+    body: string;
+    /** The body parsed as JSON (throws on non-JSON bodies). */
+    json(): T;
+}
+/** Keyed race outcome: which arm won and its value. */
+export type RaceOutcome<T extends Record<string, PromiseLike<unknown>>> = {
+    [K in keyof T]: {
+        key: K;
+        value: Awaited<T[K]>;
+    };
+}[keyof T];
+/**
+ * The workflow context — the boundary between deterministic workflow code and the
+ * world. Everything on ctx is journaled; everything off ctx must be pure.
+ */
+export interface Context<E extends EventMap = {}> {
+    /** The authenticated starter. */
+    readonly user: CallerIdentity;
+    /** Project parameters, snapshot at start. */
+    readonly params: Readonly<Record<string, Json>>;
+    readonly instanceId: string;
+    /** Journal-fed time; advances only at awaits. Same value on every replay. */
+    now(): Instant;
+    /** Seeded, replay-stable random in [0,1). */
+    random(): number;
+    /** Replay-stable UUID. */
+    uuid(): string;
+    /** Structured instance logging (journal-adjacent telemetry, not workflow state). */
+    log: ProcessLogger;
+    /** Park for a duration — milliseconds, 'PT5M', '00:05:00' or { minutes: 5 }. Durable: survives restarts. */
+    wait(duration: DurationLike): Promise<void>;
+    /** Park until an absolute time (Instant or ISO-8601 string). */
+    waitUntil(at: Instant | string): Promise<void>;
+    /** Park until ONE occurrence of the signal. Hierarchical refs: 'ticket' receives 'ticket.done.1'. */
+    waitSignal<T = unknown>(ref: string, opts?: DeliveryOptions): Promise<T>;
+    /** Broadcast a signal (parked processes, start triggers, webhooks, clients). Durable fire-and-forget. */
+    sendSignal(ref: string, data?: Serializable): Promise<void>;
+    /** First arm wins; losing PARKS are cancelled (in-flight activities still settle). */
+    race<T extends Record<string, PromiseLike<unknown>>>(arms: T): Promise<RaceOutcome<T>>;
+    /** Parallel map over items with bounded concurrency. Results keep item order. */
+    map<T, R>(items: readonly T[], opts: {
+        concurrency: number;
+    }, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+    /** Rejects with TimeoutError when the promise does not settle in time (v1: the losing work is not cancelled). */
+    withTimeout<T>(duration: DurationLike, promise: Promise<T>): Promise<T>;
+    /** Typed, string-free access to the project's own tables: ctx.tables.Books.write(id, …). */
+    readonly tables: ProjectTables;
+    readonly docs: ProjectDocs;
+    /** By-name table access — for dynamic names and cross-project stores. */
+    table<T = Json>(name: string, opts?: {
+        project?: string;
+    }): TableHandle<T>;
+    /** By-name document-store access. */
+    doc<T = Json>(store: string, opts?: {
+        project?: string;
+    }): DocStoreHandle<T>;
+    /**
+     * CNQL query — a file reference ('queries/x.cnql') or inline CNQL; args bound
+     * safely. The result is journaled and replayed on every wake-up, so return
+     * conclusions, not datasets: filter and aggregate in the query.
+     */
+    query<Row = Json>(query: string, args?: Record<string, Serializable>): Promise<Row[]>;
+    /**
+     * An activity execution (at-least-once, result journaled). Retries and the
+     * timeout apply inside one journaled execution. Pass the imported activity
+     * handle for a fully typed invocation resolved against this deployment's
+     * activity artifacts — or a registered host activity by name (string form).
+     */
+    activity<In, Out>(target: Activity<In, Out>, input: In, opts?: ActivityOptions): Promise<Out>;
+    activity<T = Json>(name: string, input?: Serializable, opts?: ActivityOptions): Promise<T>;
+    /**
+     * Outbound HTTP, executed host-side as a journaled activity (at-least-once — set
+     * idempotencyKey for non-idempotent calls). Follows redirects; private/internal
+     * targets are rejected by the server's SSRF policy. Non-2xx responses return
+     * normally — check res.ok; only transport/policy failures throw.
+     */
+    fetch<T = Json>(url: string, opts?: FetchOptions): Promise<FetchResponse<T>>;
+    /** Call another process — a statically imported handle (fully typed) or a { project?, process } target. */
+    call<In, Out, CE extends EventMap>(target: Process<In, Out, CE>, input: In, opts?: CallOptions): CallHandle<Out, CE>;
+    call<Out = unknown, CE extends EventMap = EventMap>(target: CallTarget, input?: Serializable, opts?: CallOptions): CallHandle<Out, CE>;
+    /** The email connector — bound to the named manifest parameter, or the project's only one of kind 'email'. */
+    email(binding?: ConnectorBindingOf<'email'>): EmailHandle;
+    /** The SMS connector — the named manifest parameter, or the project's only one of kind 'sms'. */
+    sms(binding?: ConnectorBindingOf<'sms'>): SmsHandle;
+    /** The chat connector (Slack, Teams, …) — the named manifest parameter, or the project's only one of kind 'chat'. */
+    chat(binding?: ConnectorBindingOf<'chat'>): ChatHandle;
+    /** The object store (S3, Azure Blob, …) — the named manifest parameter, or the project's only one of kind 'objectStorage'. */
+    objectStorage(binding?: ConnectorBindingOf<'objectStorage'>): ObjectStorageHandle;
+    /** The file-transfer server (SFTP) — the named manifest parameter, or the project's only one of kind 'fileTransfer'. */
+    fileTransfer(binding?: ConnectorBindingOf<'fileTransfer'>): FileTransferHandle;
+    /** The payment provider — the named manifest parameter, or the project's only one of kind 'payment'. */
+    payment(binding?: ConnectorBindingOf<'payment'>): PaymentHandle;
+    /** The language model (Claude, GPT, Gemini, or a local runtime) — the named manifest parameter, or the project's only one of kind 'llm'. */
+    llm(binding?: ConnectorBindingOf<'llm'>): LlmHandle;
+    /**
+     * The credit ledger, scoped to this project and one balance name: named integer balances
+     * per user (or anonymous pools by account id), conditional spend that never goes below
+     * zero, and a mandatory idempotency reference on every movement.
+     */
+    credits(name: string): CreditsHandle;
+    /**
+     * A usage meter, scoped to this project: per-period unit counters the framework
+     * accumulates. Framework meters (dotted names: email.sent, llm.tokens.*) count
+     * themselves and are read-only here; custom meters record the project's own business
+     * units.
+     */
+    meter(name: string): MeterHandle;
+    /**
+     * The subscription registry, scoped to this project (or tenant-wide with
+     * { tenant: true }): the framework tracks the term and raises a signal per transition;
+     * entitlement and renewal are this project's process code.
+     */
+    subscription(plan: string, scope?: {
+        tenant?: boolean;
+    }): SubscriptionHandle;
+    /**
+     * Web push to the devices a user subscribed for one of the project's react
+     * applications. Subscriptions, keys and delivery are platform built-ins — nothing to
+     * bind; send() is a journaled activity with the same one-attempt default as the
+     * connector sends.
+     */
+    readonly webPush: WebPushApi;
+    /**
+     * Render a manifest-declared template into its channel payload — the imported template
+     * handle (fully typed, kind-checked) or its manifest name. One journaled activity: the
+     * template bundle executes server-side on the Node pool. Email results carry send();
+     * pdf results are stored references whose bytes never enter the process.
+     */
+    readonly render: RenderApi;
+    /**
+     * Creates a user task — a form somebody must fill in the portal (or via a share link) —
+     * and returns its handle: await handle.outcome to park until a human completes it (the
+     * BPMN user-task shape), race it with a timer for escalation, reassign or cancel it.
+     * Unless detached, the task is cancelled with the run's compensation.
+     */
+    userTask(definition: UserTaskDefinition, opts?: UserTaskOptions): Promise<UserTaskHandle>;
+    /**
+     * Send the HTTP response of an api-triggered process. Call it EARLY to answer the
+     * caller while the process keeps running, or just before returning to control
+     * status/headers. Once per instance.
+     */
+    respond(status: number, body?: Serializable, headers?: Record<string, string>): Promise<void>;
+    /** Send a DECLARED event to the caller without terminating. */
+    sendEvent<K extends keyof E & string>(event: K, payload: E[K]): Promise<void>;
+    /** Register compensation AFTER the action it undoes succeeded. LIFO on failure/cancel. */
+    onCompensate(handler: () => void | Promise<void>): void;
+    /** Run the compensation chain NOW without failing. */
+    compensate(): Promise<void>;
+    /** Seal this history, restart with carried input (fresh generation). */
+    continueAsNew(input: Serializable): Promise<never>;
+    /** Execute-once escape hatch: the closure runs live only (REAL Date/random inside); its result is journaled. */
+    run<T extends Serializable>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * In-flight hotfix marker: live executions journal the marker and return true;
+     * replays return what this instance recorded at this point. Normal deploys never
+     * need this — instances pin their bundle version.
+     */
+    patched(marker: string): boolean;
+}
+/** @internal The runtime pieces createContext returns beside the ctx object. */
+export interface ContextInternals {
+    ctx: Context<EventMap>;
+    /** The journaled start environment, set by the bootstrap before run() executes. */
+    setEnvironment(user: CallerIdentity, params: Record<string, Json>, instanceId: string | null): void;
+    /** LIFO compensation chain length (bootstrap: skip the unwind when empty). */
+    compensationCount(): number;
+    /** Runs the compensation chain to exhaustion (failures logged, chain continues). */
+    runCompensation(): Promise<void>;
+}
+/** @internal Builds the ctx facade over the protocol bindings. Called once per run session. */
+export declare const createContext: (host: EngineBindings) => ContextInternals;
+export { engine };

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

@@ -0,0 +1,71 @@
+import type { ActivityOptions } from './context';
+/** Exactly one of user (the user's account of the handle's name) and account (an account id). */
+export type CreditTarget = {
+    user: string;
+} | {
+    account: string;
+};
+export type CreditGrantKind = 'purchased' | 'promotional';
+export interface CreditGrantOptions {
+    /** Idempotency reference (order id, …) — the same reference never grants twice. */
+    reference: string;
+    /** Purchased (paid for) or promotional (given away) — tagged distinctly in the history. */
+    kind: CreditGrantKind;
+    reason?: string;
+}
+export interface CreditSpendOptions {
+    /** Idempotency reference (run id, …) — the same reference never spends twice. */
+    reference: string;
+    reason?: string;
+}
+export interface CreditSpendResult {
+    /** False = refused, the balance would go below zero (or the account does not exist). Nothing moved. */
+    applied: boolean;
+    /** True when the reference was already recorded — the recorded outcome is returned. */
+    replayed: boolean;
+    /** Balance after the movement, or the current balance when refused. */
+    balance: number;
+}
+export interface CreditGrantResult {
+    replayed: boolean;
+    balance: number;
+}
+export interface CreditMovement {
+    id: string;
+    kind: 'grant.purchased' | 'grant.promotional' | 'spend';
+    /** Signed: positive grants, negative spends. */
+    amount: number;
+    balanceAfter: number;
+    reference: string;
+    reason?: string;
+    createdAt: string;
+}
+export interface CreditHistoryPage {
+    items: CreditMovement[];
+    totalCount: number;
+}
+export interface CreditsHandle {
+    /**
+     * Add credits. Creates the account when absent: a user-target creates the user's account
+     * of this name; an account-target creates an anonymous pool under the supplied id. A
+     * duplicate reference with different parameters fails with credits.referenceConflict.
+     */
+    grant(target: CreditTarget, amount: number, opts: CreditGrantOptions & ActivityOptions): Promise<CreditGrantResult>;
+    /**
+     * Remove credits when the balance suffices — never below zero, never creating an account.
+     * A refusal is a result to branch on ({applied: false}), not an error.
+     */
+    spend(target: CreditTarget, amount: number, opts: CreditSpendOptions & ActivityOptions): Promise<CreditSpendResult>;
+    /** The current balance; 0 when the account does not exist. */
+    get(target: CreditTarget, opts?: ActivityOptions): Promise<number>;
+    /** The account's movements, newest first. */
+    history(target: CreditTarget, opts?: {
+        limit?: number;
+        before?: string;
+    } & ActivityOptions): Promise<CreditHistoryPage>;
+}
+/** @internal Same call channel as the connector handles. */
+type CreditsCall = <T>(name: string, input: Record<string, unknown>, opts: ActivityOptions | undefined) => Promise<T>;
+/** @internal ctx.credits factory over the activity channel — bound by createContext. */
+export declare const createCreditsFactory: (call: CreditsCall) => (name: string) => CreditsHandle;
+export {};

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

@@ -0,0 +1,72 @@
+export type RoundingMode = 
+/** Away from zero. */
+'up'
+/** Toward zero (truncate). */
+ | 'down'
+/** Toward +Infinity. */
+ | 'ceil'
+/** Toward -Infinity. */
+ | 'floor'
+/** Nearest; ties away from zero (schoolbook rounding). */
+ | 'halfUp'
+/** Nearest; ties toward zero. */
+ | 'halfDown'
+/** Nearest; ties to the even neighbor (banker's rounding — the money default). */
+ | 'halfEven';
+/**
+ * Arbitrary-precision decimal for money and precision math (vanilla JS numbers are
+ * binary floats). Immutable; serializes to its plain decimal string (toJSON).
+ */
+export declare class Decimal {
+    private readonly coefficient;
+    private readonly scale;
+    private constructor();
+    /** Parses a decimal string ('19.99', '-1e-3') or a number (via its exact string form). */
+    static from(value: string | number | Decimal): Decimal;
+    /** Standard comparator (numeric): -1, 0 or 1. */
+    static compare(a: Decimal | number | string, b: Decimal | number | string): -1 | 0 | 1;
+    /** Exact sum. The result keeps the larger scale of the two operands. */
+    plus(other: Decimal | number | string): Decimal;
+    /** Exact difference. */
+    minus(other: Decimal | number | string): Decimal;
+    /** Exact product. Scales add ('1.25' × '0.5' → '0.625'). */
+    times(other: Decimal | number | string): Decimal;
+    /**
+     * Division at a fixed precision: `decimalPlaces` fraction digits (default 20),
+     * rounded with `rounding` (default 'halfEven'). Throws on division by zero.
+     */
+    dividedBy(other: Decimal | number | string, options?: {
+        decimalPlaces?: number;
+        rounding?: RoundingMode;
+    }): Decimal;
+    /** This value rounded to `decimalPlaces` fraction digits (default mode 'halfEven'). */
+    round(decimalPlaces: number, rounding?: RoundingMode): Decimal;
+    /**
+     * Splits this value by the given ratios without losing a unit at the current scale
+     * (largest-remainder distribution): Decimal.from('100.00').allocate([1, 1, 1]) →
+     * ['33.34', '33.33', '33.33']. Ratios must be non-negative with a positive sum.
+     */
+    allocate(ratios: readonly number[]): Decimal[];
+    /** Numeric comparison (scale-independent): -1, 0 or 1. */
+    compare(other: Decimal | number | string): -1 | 0 | 1;
+    /** Numeric equality ('1.5' equals '1.50'). */
+    equals(other: Decimal | number | string): boolean;
+    isZero(): boolean;
+    isNegative(): boolean;
+    /** The absolute value. */
+    abs(): Decimal;
+    /** The value with its sign flipped. */
+    negated(): Decimal;
+    /** Fixed-point text with exactly `decimalPlaces` fraction digits, rounding when narrower. */
+    toFixed(decimalPlaces: number, rounding?: RoundingMode): string;
+    /**
+     * The closest JS number. Explicitly lossy for values beyond float precision —
+     * keep money in Decimal and convert only at the edges.
+     */
+    toNumber(): number;
+    /** Plain decimal text, no exponent, trailing zeros kept ('1.50' stays '1.50'). */
+    toString(): string;
+    toJSON(): string;
+    /** Approximate numeric value — lets relational operators (<, >) behave sanely. Use compare() for exactness. */
+    valueOf(): number;
+}

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

@@ -0,0 +1,40 @@
+import type { DurationLike } from './types';
+/**
+ * A length of time. Fixed components (weeks/days/hours/minutes/seconds/milliseconds)
+ * collapse to exact milliseconds; calendar components (years/months) have no fixed
+ * length and are kept apart — they only gain meaning when applied to an Instant.
+ *
+ * Accepted input everywhere a DurationLike is expected: ISO-8601 ('P3D', 'PT5M'),
+ * raw milliseconds (180000), .NET TimeSpan text ('3.00:00:00') or a components
+ * object ({ days: 3 }).
+ */
+export declare class Duration {
+    /** @internal Calendar months (years folded in). */
+    readonly calendarMonths: number;
+    /** @internal Fixed milliseconds (weeks/days/time folded in). */
+    readonly fixedMillis: number;
+    private constructor();
+    /** Parses any DurationLike. Throws on unrecognized input. */
+    static from(value: DurationLike): Duration;
+    /** The sum of this duration and another. */
+    plus(other: DurationLike): Duration;
+    /** This duration minus another. */
+    minus(other: DurationLike): Duration;
+    /** The same duration with every component negated. */
+    negated(): Duration;
+    /** True when every component is zero. */
+    isZero(): boolean;
+    /**
+     * Total milliseconds. Throws when the duration carries calendar components
+     * (years/months have no fixed length — apply the duration to an Instant instead).
+     */
+    toMillis(): number;
+    /** Total seconds (same calendar-component rule as toMillis). */
+    toSeconds(): number;
+    /** ISO-8601 text ('P1M2DT3H'). Zero durations render as 'PT0S'. */
+    toISOString(): string;
+    toJSON(): string;
+    toString(): string;
+}
+/** @internal Converts a DurationLike to exact milliseconds (rejects calendar components). */
+export declare const durationToMillis: (value: DurationLike) => number;

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

@@ -0,0 +1,27 @@
+/** UTF-8 text ↔ bytes. */
+export declare const utf8: {
+    /** Encodes text as UTF-8 bytes. */
+    encode(text: string): Uint8Array;
+    /** Decodes UTF-8 bytes to text. Throws on malformed sequences. */
+    decode(bytes: Uint8Array): string;
+};
+/** Base64 (and base64url) text ↔ bytes. Strings encode as their UTF-8 bytes. */
+export declare const base64: {
+    /** Encodes bytes (or a string's UTF-8 bytes) as base64. { url: true } gives base64url without padding. */
+    encode(data: string | Uint8Array, options?: {
+        url?: boolean;
+    }): string;
+    /** Decodes base64 or base64url text (padding optional) to bytes. */
+    decode(text: string): Uint8Array;
+    /** Decodes base64 text straight to UTF-8 text. */
+    decodeToText(text: string): string;
+};
+/** Lowercase hex text ↔ bytes. Strings encode as their UTF-8 bytes. */
+export declare const hex: {
+    /** Encodes bytes (or a string's UTF-8 bytes) as lowercase hex. */
+    encode(data: string | Uint8Array): string;
+    /** Decodes hex text (either case) to bytes. */
+    decode(text: string): Uint8Array;
+    /** Decodes hex text straight to UTF-8 text. */
+    decodeToText(text: string): string;
+};

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

@@ -0,0 +1,57 @@
+import type { Json } from './types';
+/**
+ * Structured error for failures that must cross a boundary with fidelity. A callee
+ * throwing ProcessError is rehydrated as ProcessError in its caller (instanceof works
+ * there); for a failed root process the code becomes the API error code. Throwing
+ * anything else is fine too — it crosses boundaries as CallFailedError (name/message).
+ */
+export declare class ProcessError extends Error {
+    readonly code: string;
+    readonly details?: Json;
+    constructor(code: string, options?: {
+        details?: Json;
+        cause?: unknown;
+    });
+}
+/** A called process failed with a non-ProcessError throw; carries what serialization kept. */
+export declare class CallFailedError extends Error {
+    /** Constructor name of the original thrown value (or 'Error'). */
+    readonly errorName: string;
+    readonly processId: string;
+    constructor(message?: string, errorName?: string, processId?: string);
+}
+/** Thrown by ctx.withTimeout when the wrapped promise did not settle in time. */
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/** Thrown into in-flight waits when the instance is cancelled/stopped. */
+export declare class CancelledError extends Error {
+    constructor(message?: string | null);
+}
+/** Rejects a pending call.waitEvent when the callee completes without sending that event. */
+export declare class CallCompletedError extends Error {
+    constructor(message?: string);
+}
+/** Thrown by table/doc require() when the record does not exist. */
+export declare class NotFoundError extends Error {
+    readonly store: string;
+    readonly key: string;
+    constructor(message?: string, store?: string, key?: string);
+}
+/** The serialized error value journaled for a failed run (internal). */
+export interface SerializedError {
+    name: string;
+    message: string;
+    code?: string;
+    details?: Json | null;
+}
+/** @internal Serializes a thrown value the way the journal records it. */
+export declare const serializeError: (err: unknown) => SerializedError;
+/** @internal Rehydrates a journaled error value into the matching error class. */
+export declare const reviveError: (value: SerializedError | null | undefined) => Error;
+/**
+ * @internal A failed CALL crosses the boundary as ProcessError when the callee threw one
+ * (rehydrated, instanceof works); anything else becomes CallFailedError carrying the
+ * original error name.
+ */
+export declare const reviveChildError: (value: SerializedError | null | undefined, processId: string) => Error;

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

@@ -0,0 +1,18 @@
+export type HashOutput = 'hex' | 'base64';
+/**
+ * Hashing and signature verification. Host-backed pure functions: same input, same
+ * output, on every replay — safe to call anywhere in workflow code, nothing journaled.
+ * Strings hash as their UTF-8 bytes.
+ */
+export declare const hash: {
+    /** SHA-256 digest, hex by default ('base64' on request). */
+    sha256(data: string | Uint8Array, output?: HashOutput): string;
+    /** HMAC-SHA-256 signature — the webhook-verification primitive. Hex by default. */
+    hmacSha256(key: string | Uint8Array, data: string | Uint8Array, output?: HashOutput): string;
+    /**
+     * Constant-time equality for comparing a computed signature against a received one
+     * (an early-exit === leaks match length through timing). Strings compare as UTF-8
+     * bytes; different lengths are simply unequal.
+     */
+    timingSafeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean;
+};

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

@@ -0,0 +1,25 @@
+export { process, api, signal, timer, connectorEvent, install, manual, events } from './registry';
+export type { AuthScope, Concurrency, ConnectorBindingName, ConnectorEventName, EventMap, EventsDecl, Process, ProcessAuth, ProcessDefinition, ProcessOptions, Trigger, } from './registry';
+export { ProcessError, CallFailedError, TimeoutError, CancelledError, CallCompletedError, NotFoundError, } from './errors';
+export type { Activity, Json, Serializable, DurationParts, DurationLike, RetryPolicy, DeliveryOptions, JsonPatchOp, Template, TemplateKind, } from './types';
+export type { EmailTemplatePayload, PdfPageOptions, PdfTemplatePayload, PdfRenderOptions, RenderApi, RenderOptions, RenderSendOptions, RenderedEmail, StoredRendering, } from './renderings';
+export type { WebPushApi, WebPushDeviceStatus, WebPushMessage, WebPushResult, } from './webPush';
+export type { ActivityOptions, ArmedHandler, CallerIdentity, CallHandle, CallOptions, CallTarget, Context, DocStoreHandle, FetchOptions, FetchResponse, ProcessLogger, ProjectDocs, ProjectTables, RaceOutcome, RecordGrant, TableHandle, WriteOptions, } from './context';
+export type { ChargeRequest, ChargeResult, ChatHandle, ChatMessage, CheckoutRequest, CheckoutSession, ConnectorBindingOf, ConnectorKind, ConnectorKindEvents, EmailAttachment, RenderingAttachment, EmailHandle, EmailMessage, FileTransferHandle, FileTransferItem, LlmHandle, LlmMessage, LlmRequest, LlmResult, LlmStopReason, LlmUsage, MeterAttribution, ObjectStorageHandle, ObjectStorageItem, PaymentHandle, PaymentState, PaymentStatus, ProjectConnectors, RefundResult, SmsHandle, SmsMessage, } from './connectors';
+export type { CreditGrantKind, CreditGrantOptions, CreditGrantResult, CreditHistoryPage, CreditMovement, CreditSpendOptions, CreditSpendResult, CreditsHandle, CreditTarget, } from './credits';
+export type { MeterAddOptions, MeterAddResult, MeterBreakdownPage, MeterBreakdownQuery, MeterBreakdownRow, MeterHandle, MeterTarget, MeterTotalQuery, } from './meters';
+export type { SubscriptionHandle, SubscriptionPeriod, SubscriptionSnapshot, SubscriptionState, SubscriptionTarget, SubscriptionTerm, } from './subscriptions';
+export type { UserTaskAssignment, UserTaskDefinition, UserTaskForm, UserTaskFormField, UserTaskHandle, UserTaskOptions, UserTaskOutcome, UserTaskSnapshot, } from './userTasks';
+export { Instant } from './instant';
+export type { InstantUnit } from './instant';
+export { Duration } from './duration';
+export { Decimal } from './decimal';
+export type { RoundingMode } from './decimal';
+export { base64, hex, utf8 } from './encoding';
+export * as url from './urls';
+export type { QueryValue, UrlParts } from './urls';
+export { canonicalJson } from './canonical-json';
+export { chunk, uniqueBy } from './collections';
+export { is } from './validators';
+export { hash } from './hash';
+export type { HashOutput } from './hash';