@codenotch/process 0.0.0-dev

package/README.md

@@ -0,0 +1,51 @@
+# @codenotch/process
+
+The standard library and type surface of Codenotch script processes.
+
+Script processes execute **on the server only**: the engine embeds this package's
+compiled runtime and serves it to `require('@codenotch/process')` inside the V8 workflow
+sandbox. What the package distributes to process authors is the **type declarations**
+(`dist/types`) — there is no client-side execution, and the runtime never ships in a
+process bundle (the deploy bundler treats the package as external).
+
+## Layout
+
+```
+src/lib       the public library: process()/triggers, ctx (Context), errors,
+              Instant, Duration, Decimal, encodings, url, canonicalJson, is, hash.
+              Pure TypeScript; talks to the engine only through the EngineBindings
+              seam (bindings.ts). dist/types is emitted from here.
+src/runtime   the wire-protocol layer: sandbox hardening, the command channel over
+              the __host adapter, and the engine entry points (__start, __deliver,
+              __cancelDeliver, __deliverChildEvent, __processMetadataJson,
+              __concurrencyKey). Engine-internal — never part of the public types.
+src/activity  the '@codenotch/process/activity' entry: activity() and the activity-side
+              types. Ships as runtime JS (dist/activity.mjs) — the deploy bundler
+              inlines it into each activity bundle (activities run on Node).
+src/testing   the '@codenotch/process/testing' entry: the process-test facade
+              (test/expect/env — see doc/reference/process-tests.md). Its bundle
+              (dist/test-prelude.js) is the engine's V8 test-host prelude; the entry
+              distributes types only, like the root.
+```
+
+## Build
+
+`node build.mjs` — type-checks, emits `dist/types` and bundles the three runtimes:
+`src/runtime/prelude.ts` → `dist/prelude.js` (IIFE), `src/activity/index.ts` →
+`dist/activity.mjs`, `src/testing/main.ts` → `dist/test-prelude.js` (IIFE). Output files
+are rewritten only when content changed. The `Echino.Services.Framework.Processes`
+csproj runs this automatically when sources changed and embeds `dist/prelude.js`
+(`ScriptEngine.WorkflowPrelude.js`) and `dist/test-prelude.js`
+(`ScriptEngine.TestPrelude.js`), so the engine and the types can never drift.
+
+`dist/` is committed: a .NET-only checkout builds without running npm as long as the
+TypeScript sources are untouched.
+
+## Rules (doc/reference/process-stdlib.md holds the user-facing docs)
+
+- Every `ctx` method and library function is documented (JSDoc here, reference doc there)
+  and covered by an example-grade fixture in
+  `test/Echino.Services.Framework.Processes.Test/testSchemas/StdlibTests`.
+- Strong typing first, dynamic as fallback (`ctx.call(handle)` over `ctx.call<In, Out>('name')`).
+- The library layer stays pure: anything touching the world goes through the bindings
+  seam and is journaled by the engine.

package/dist/activity.mjs

@@ -0,0 +1,14 @@
+// src/activity/index.ts
+function activity(first, second) {
+  const impl = typeof first === "function" ? first : second;
+  const defaults = typeof first === "function" ? {} : first;
+  if (typeof impl !== "function")
+    throw new Error("activity() requires the implementation function (io, args) => result");
+  return Object.assign(
+    (io, args) => impl(io, args),
+    { __codenotchActivity: true, __options: defaults ?? {} }
+  );
+}
+export {
+  activity
+};

package/dist/template.mjs

@@ -0,0 +1,21 @@
+// src/template/index.ts
+var declare = (kind, render, page) => Object.freeze(page === void 0 ? { __codenotchTemplate: true, kind, render } : { __codenotchTemplate: true, kind, page, render });
+var template = Object.freeze({
+  /** Declares an email template: render(data) returns { subject, html, text? }. */
+  email: (render) => declare("email", render),
+  /**
+   * Declares a pdf template: render(data) returns { html } (print CSS; Chromium paged
+   * media — @page margin boxes, counter(page/pages) — works natively). The optional
+   * first argument sets the page: template.pdf({ format: 'A4' }, render).
+   */
+  pdf: ((pageOrRender, render) => {
+    if (typeof pageOrRender === "function")
+      return declare("pdf", pageOrRender);
+    if (typeof render !== "function")
+      throw new Error("template.pdf requires a render function");
+    return declare("pdf", render, pageOrRender);
+  })
+});
+export {
+  template
+};

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

@@ -0,0 +1,52 @@
+import type { Activity, DurationLike, RetryPolicy } from '../lib/types';
+export type ActivityLogger = {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+};
+/**
+ * Resolves to the real AbortSignal when the consumer's environment declares it
+ * (activities type-check with node types); a minimal structural shape otherwise
+ * (this package itself compiles against pure ES2022).
+ */
+export type ActivityAbortSignal = typeof globalThis extends {
+    AbortSignal: {
+        prototype: infer T;
+    };
+} ? T : {
+    readonly aborted: boolean;
+};
+/** The activity-side services handed to every invocation. */
+export type ActivityIo = {
+    log: ActivityLogger;
+    /** Stable across retries of one journaled execution — pass to providers that dedupe. */
+    idempotencyKey: string;
+    /** Aborts when the invocation's timeout elapses; long I/O should honor it. */
+    signal: ActivityAbortSignal;
+    project: string;
+    /** Base URL + auth header/token for calling back into the platform APIs. */
+    baseUrl: string;
+    token: string;
+    tokenHeader: string;
+};
+/**
+ * Reserved for enforced defaults (a later milestone extracts them into the deploy
+ * metadata); v1 enforces the options given at the ctx.activity call site.
+ */
+export type ActivityDefaults = {
+    retry?: RetryPolicy;
+    timeout?: DurationLike;
+};
+export type ActivityImpl<In, Out> = (io: ActivityIo, args: In) => Out | PromiseLike<Out>;
+/**
+ * The defined activity: directly callable on the Node side (unit tests), and a
+ * typed Activity handle from workflow code (via the bundler's reference stub).
+ */
+export type ActivityHandle<In, Out> = ActivityImpl<In, Out> & Activity<In, Out>;
+/**
+ * Declares an activity. Export the result from a *.activity.ts module; workflow
+ * code imports it and passes it to ctx.activity for a fully typed invocation.
+ */
+export declare function activity<In, Out>(impl: ActivityImpl<In, Out>): ActivityHandle<In, Out>;
+export declare function activity<In, Out>(defaults: ActivityDefaults, impl: ActivityImpl<In, Out>): ActivityHandle<In, Out>;

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

@@ -0,0 +1,48 @@
+/** @internal Hooks the library attaches to one emitted command's outcome. */
+export interface CommandAwaiterHooks {
+    /** Called synchronously when the outcome is delivered (ok=false carries the serialized error). */
+    settle(ok: boolean, value: unknown): void;
+    /**
+     * Present → the command is a PARK (timer/signal/child await): instance cancellation
+     * rejects it. Absent → an in-flight effect (activity): its outcome still settles so
+     * the compensation chain stays complete.
+     */
+    cancel?(reason: string | null): void;
+    /** Present on child calls: a declared event the callee sent. */
+    childEvent?(eventId: string, payload: unknown): void;
+}
+/** @internal What the wire-protocol layer provides to the library. */
+export interface EngineBindings {
+    /** Emits a command and returns its emission index. */
+    emit(kind: string, args?: unknown): number;
+    /** Registers the outcome hooks of an emitted command. */
+    awaitOutcome(commandIndex: number, hooks: CommandAwaiterHooks): void;
+    /** True once the instance received a cancellation. */
+    isCancelled(): boolean;
+    cancelReason(): string | null;
+    /** Whether the command at the index is beyond the journaled history (live). */
+    isLive(commandIndex: number): boolean;
+    /** Journals the result of a live ctx.run closure. */
+    sideEffectResult(commandIndex: number, resultJson: string | null): void;
+    /** Toggles the real clock/randomness (inside a live ctx.run closure only). */
+    setRealTime(on: boolean): void;
+    log(level: string, message: string, dataJson: string | null): void;
+    /** Deterministic journal time (ms since epoch). */
+    nowMs(): number;
+    /** Deterministic seeded random in [0,1). */
+    nextRandom(): number;
+    /** Deterministic uuid derived from the seeded PRNG. */
+    nextUuid(): string;
+    patched(marker: string): boolean;
+    continueAsNew(inputJson: string | null): void;
+    /** SHA-256 over base64 bytes, result base64. Pure function — safe outside the journal. */
+    hashSha256(dataBase64: string): string;
+    /** HMAC-SHA-256 over base64 key/data, result base64. */
+    hashHmacSha256(keyBase64: string, dataBase64: string): string;
+    /** Constant-time byte equality over base64 inputs. */
+    timingSafeEqual(aBase64: string, bBase64: string): boolean;
+}
+/** @internal Called once by the runtime prelude before any process code runs. */
+export declare const setEngineBindings: (value: EngineBindings) => void;
+/** @internal The active bindings; throws outside the server sandbox. */
+export declare const engine: () => EngineBindings;

package/dist/types/lib/canonical-json.d.ts

@@ -0,0 +1,10 @@
+import type { Serializable } from './types';
+/**
+ * Canonical JSON: object keys sorted, no whitespace, stable across runs — the right
+ * form for anything derived from an object's content (concurrency keys, dedupe keys,
+ * hashes). Plain JSON.stringify is insertion-order dependent and must not feed a key.
+ *
+ * Follows JSON.stringify semantics otherwise: toJSON is honored, undefined properties
+ * drop, undefined array elements render as null. Circular references throw.
+ */
+export declare const canonicalJson: (value: Serializable) => string;

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

@@ -0,0 +1,12 @@
+/**
+ * Splits items into consecutive chunks of `size` (the last chunk may be shorter).
+ * The natural partner of ctx.map for paging work:
+ * `for (const page of chunk(ids, 100)) await ctx.map(page, { concurrency: 5 }, …)`.
+ */
+export declare const chunk: <T>(items: readonly T[], size: number) => T[][];
+/**
+ * The items with duplicates removed, judged by the given key; the FIRST occurrence of
+ * each key wins and the original order is kept. (For primitives, `[...new Set(items)]`
+ * already does the job.)
+ */
+export declare const uniqueBy: <T>(items: readonly T[], key: (item: T) => unknown) => T[];

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

@@ -0,0 +1,299 @@
+import { Instant } from './instant';
+import type { ActivityOptions } from './context';
+import type { DurationLike, Json, RetryPolicy } from './types';
+/** The connector kinds a manifest parameter can declare. */
+export type ConnectorKind = 'payment' | 'email' | 'sms' | 'chat' | 'database' | 'objectStorage' | 'fileTransfer' | 'llm';
+/**
+ * The inbound event types per connector kind, for the kinds that have an event source.
+ * Payment events are provider-neutral (normalized by the adapters); chat events pass the
+ * provider's own type through ('message' is the common one — Slack also delivers
+ * 'app_mention', 'reaction_added', …), so the chat union stays open.
+ */
+export interface ConnectorKindEvents {
+    payment: 'checkout.completed' | 'payment.succeeded' | 'payment.failed' | 'refund.succeeded' | 'refund.failed' | 'chargeback.opened' | 'chargeback.closed' | 'other';
+    chat: 'message' | (string & {});
+}
+/**
+ * The project's connector bindings (manifest parameter name → kind) — augmented via
+ * declaration merging by the generated connectors.d.ts so binding names and their event
+ * types autocomplete in connectorEvent(...). Plain strings are always accepted too.
+ *
+ *     declare module '@codenotch/process' {
+ *         interface ProjectConnectors { payments: 'payment'; teamChat: 'chat' }
+ *     }
+ */
+export interface ProjectConnectors {
+}
+/**
+ * The project's binding names of one kind — what ctx.payment(…) & friends accept. With a
+ * generated connectors.d.ts the right bindings autocomplete; any string stays accepted.
+ */
+export type ConnectorBindingOf<K extends ConnectorKind> = ({
+    [B in keyof ProjectConnectors]: ProjectConnectors[B] extends K ? B : never;
+}[keyof ProjectConnectors] & string) | (string & {});
+/**
+ * Metered calls (the sends, llm.generate) are counted by the framework and attributed to the
+ * user who started the process; set meterUser to attribute the usage to someone else — e.g.
+ * a webhook-triggered process has no starting user but knows whose email it sends.
+ */
+export interface MeterAttribution {
+    meterUser?: string;
+}
+/** One email attachment. A string content is UTF-8 text; pass bytes for binary files. */
+export interface EmailAttachment {
+    fileName: string;
+    /** MIME type; default application/octet-stream. */
+    contentType?: string;
+    content: string | Uint8Array;
+}
+/**
+ * Attach a stored rendering by reference — pass a ctx.render.pdf result directly. The
+ * server resolves the bytes at send time; they never travel through the process.
+ */
+export interface RenderingAttachment {
+    renderingId: string;
+    /** Override the rendering's stored file name. */
+    fileName?: string;
+}
+export interface EmailMessage {
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    /** Plain-text body. At least one of text and html is required. */
+    text?: string;
+    /** HTML body. */
+    html?: string;
+    replyTo?: string;
+    /** Override the connector's default sender address (providers may refuse foreign senders). */
+    from?: string;
+    fromName?: string;
+    /** Requires the 'attachments' capability. */
+    attachments?: (EmailAttachment | RenderingAttachment)[];
+}
+export interface EmailHandle {
+    /**
+     * Send one email. At-least-once and NOT retried by default (a retry could deliver the
+     * message twice) — pass opts.retry to opt in for idempotent content.
+     */
+    send(message: EmailMessage, opts?: ActivityOptions & MeterAttribution): Promise<void>;
+}
+export interface SmsMessage {
+    /** The recipient in E.164 form (+41791234567). */
+    to: string;
+    text: string;
+    /** Alphanumeric sender override. Requires the 'senderId' capability. */
+    senderId?: string;
+}
+export interface SmsHandle {
+    /** Send one SMS. At-least-once and NOT retried by default — pass opts.retry to opt in. */
+    send(message: SmsMessage, opts?: ActivityOptions & MeterAttribution): Promise<void>;
+}
+export interface ChatMessage {
+    text: string;
+    /** Post somewhere other than the connector's configured channel. Requires the 'channelOverride' capability. */
+    channel?: string;
+}
+export interface ChatHandle {
+    /** Post one message to the connected chat channel. At-least-once and NOT retried by default. */
+    send(message: string | ChatMessage, opts?: ActivityOptions & MeterAttribution): Promise<void>;
+}
+export interface ObjectStorageItem {
+    key: string;
+    /** Bytes. */
+    size: number;
+    modified?: Instant;
+}
+export interface ObjectStorageHandle {
+    /** Store an object: a string is written as UTF-8 text, bytes as-is. Overwrites. */
+    put(key: string, body: string | Uint8Array, opts?: {
+        contentType?: string;
+    } & ActivityOptions): Promise<void>;
+    /** Read an object's bytes. */
+    get(key: string, opts: {
+        binary: true;
+    } & ActivityOptions): Promise<Uint8Array>;
+    /** Read an object as UTF-8 text (a non-text object fails with objectStorage.binaryContent). */
+    get(key: string, opts?: {
+        binary?: false;
+    } & ActivityOptions): Promise<string>;
+    /** The objects under a key prefix ('' = everything). The whole listing is journaled — keep prefixes narrow. */
+    list(prefix?: string, opts?: ActivityOptions): Promise<ObjectStorageItem[]>;
+    exists(key: string, opts?: ActivityOptions): Promise<boolean>;
+    /** Idempotent: deleting a missing key succeeds. */
+    delete(key: string, opts?: ActivityOptions): Promise<void>;
+    /**
+     * A presigned direct-download URL — the way to hand big objects to users without
+     * moving the bytes through the workflow. Requires the 'presignedUrls' capability.
+     */
+    downloadUrl(key: string, validity: DurationLike, opts?: ActivityOptions): Promise<string>;
+}
+export interface FileTransferItem {
+    name: string;
+    /** Path relative to the connector's root. */
+    path: string;
+    isDirectory: boolean;
+    /** Bytes. */
+    size: number;
+    modified?: Instant;
+}
+export interface FileTransferHandle {
+    /** Write a remote file: a string as UTF-8 text, bytes as-is. Overwrites. */
+    upload(path: string, body: string | Uint8Array, opts?: ActivityOptions): Promise<void>;
+    /** Read a remote file's bytes. */
+    download(path: string, opts: {
+        binary: true;
+    } & ActivityOptions): Promise<Uint8Array>;
+    /** Read a remote file as UTF-8 text (a binary file fails with fileTransfer.binaryContent). */
+    download(path: string, opts?: {
+        binary?: false;
+    } & ActivityOptions): Promise<string>;
+    /** The entries of a directory ('' = the connector's root), non-recursive. */
+    list(directory?: string, opts?: ActivityOptions): Promise<FileTransferItem[]>;
+    exists(path: string, opts?: ActivityOptions): Promise<boolean>;
+    delete(path: string, opts?: ActivityOptions): Promise<void>;
+}
+export interface CheckoutRequest {
+    /** Amount as a positive integer in the currency's smallest unit (4990 = CHF 49.90). */
+    amountMinor: number;
+    /** ISO 4217 code ('chf', 'eur', 'usd'). */
+    currency: string;
+    /** What the buyer sees on the provider's payment page. */
+    productName: string;
+    /** Your own reference (order id) — carried to the provider, echoed in events, idempotency basis. */
+    reference: string;
+    /** Where the provider redirects the buyer after paying. */
+    successUrl: string;
+    /** Where the provider redirects a buyer who backs out. */
+    cancelUrl: string;
+    /** Keep the payment method for later off-session charges. Requires the 'savedPaymentMethods' capability. */
+    savePaymentMethod?: boolean;
+    /** The provider's customer id from an earlier checkout, to attach this payment to it. */
+    customerRef?: string;
+    /** Prefills the provider's payment page. */
+    customerEmail?: string;
+    metadata?: Record<string, string>;
+}
+export interface CheckoutSession {
+    /** The provider-hosted payment page. Hand it to the buyer (respond redirect, link, …). */
+    redirectUrl: string;
+    /** The provider's reference for this payment — what get() polls. */
+    paymentRef: string;
+}
+export type PaymentStatus = 'pending' | 'paid' | 'canceled' | 'refunded' | 'partiallyRefunded' | 'unknown';
+export interface PaymentState {
+    status: PaymentStatus;
+    amountMinor: number;
+    currency: string;
+    refundedMinor: number;
+    /** The reference the checkout carried. */
+    reference?: string;
+    customerRef?: string;
+    /** Present after a savePaymentMethod checkout succeeded — the token chargeSavedMethod uses. */
+    savedMethodRef?: string;
+}
+export interface RefundResult {
+    /** 'accepted' is a normal outcome: refunds are asynchronous by contract. */
+    outcome: 'accepted' | 'succeeded' | 'refused';
+    refundRef?: string;
+    error?: string;
+}
+export interface ChargeRequest {
+    customerRef: string;
+    savedMethodRef: string;
+    /** Positive integer in the currency's smallest unit. */
+    amountMinor: number;
+    currency: string;
+    reference: string;
+}
+export interface ChargeResult {
+    /** 'authenticationRequired' (European SCA) is a normal outcome, not an error. */
+    outcome: 'succeeded' | 'pending' | 'authenticationRequired' | 'failed';
+    paymentRef?: string;
+    error?: string;
+}
+export interface PaymentHandle {
+    /**
+     * Create a hosted checkout: the buyer pays on the provider's page, never on one the
+     * framework renders. Idempotent per reference with providers that support it. The
+     * outcome arrives out-of-band — poll get() (durably: in a ctx.wait loop) for it.
+     */
+    checkout(request: CheckoutRequest, opts?: ActivityOptions): Promise<CheckoutSession>;
+    /** The authoritative payment state, polled from the provider. */
+    get(paymentRef: string, opts?: ActivityOptions): Promise<PaymentState>;
+    /**
+     * Refund a payment — fully, or partially with amountMinor (requires the
+     * 'partialRefunds' capability). Idempotent per execution.
+     */
+    refund(paymentRef: string, opts?: {
+        amountMinor?: number;
+    } & ActivityOptions): Promise<RefundResult>;
+    /**
+     * Charge a saved payment method off-session (renewals). Requires the
+     * 'savedPaymentMethods' capability. Idempotent per execution.
+     */
+    chargeSavedMethod(request: ChargeRequest, opts?: ActivityOptions): Promise<ChargeResult>;
+}
+export interface LlmMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface LlmUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export type LlmStopReason = 'end' | 'maxTokens' | 'refusal';
+export interface LlmRequest {
+    /** One user message — the simple form. Exactly one of prompt and messages. */
+    prompt?: string;
+    /** The full conversation, for multi-turn flows the process assembles itself. */
+    messages?: LlmMessage[];
+    system?: string;
+    /**
+     * JSON Schema the answer must conform to. The result then carries `data`, validated —
+     * or the call fails with llm.invalidJson, never mangled output. Present when
+     * stopReason is 'end' (a refusal or truncation has no data to validate).
+     */
+    schema?: Json;
+    /** Overrides the connector's default model; checked against its allow-list. */
+    model?: string;
+    /** Output ceiling; the connector's maxOutputTokens setting caps it loudly. */
+    maxTokens?: number;
+    /** 0–2. Omit for the model's default. */
+    temperature?: number;
+}
+export interface LlmResult {
+    /** The model's output text (for schema calls: the JSON text). */
+    text: string;
+    /** The model that answered. */
+    model: string;
+    /** 'refusal' (the provider's safety layer declined) is a result to branch on, not an error. */
+    stopReason: LlmStopReason;
+    /** Journaled with the result — the numbers usage metering consumes. */
+    usage: LlmUsage;
+}
+export interface LlmHandle {
+    /**
+     * One model call, executed host-side as a journaled activity: it runs once and every
+     * replay returns the recording — the activity boundary is exactly what makes a
+     * non-deterministic model safe in deterministic workflow code.
+     */
+    generate<T = Json>(request: LlmRequest & {
+        schema: Json;
+    }, opts?: ActivityOptions & MeterAttribution): Promise<LlmResult & {
+        data?: T;
+    }>;
+    generate(request: LlmRequest, opts?: ActivityOptions & MeterAttribution): Promise<LlmResult>;
+}
+/** @internal How the handles reach the activity channel — bound by createContext. */
+export type ConnectorCall = <T>(name: string, input: Record<string, unknown>, opts: ActivityOptions | undefined, defaultRetry?: RetryPolicy) => Promise<T>;
+/** @internal All six handle factories over one call binding. */
+export declare const createConnectorHandles: (call: ConnectorCall, getMeterUser?: () => string | null) => {
+    email: (bindingName?: string) => EmailHandle;
+    sms: (bindingName?: string) => SmsHandle;
+    chat: (bindingName?: string) => ChatHandle;
+    objectStorage: (bindingName?: string) => ObjectStorageHandle;
+    fileTransfer: (bindingName?: string) => FileTransferHandle;
+    payment: (bindingName?: string) => PaymentHandle;
+    llm: (bindingName?: string) => LlmHandle;
+};