@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/wire.js

@@ -0,0 +1,35 @@
+import { Schema, SchemaTransformation } from "effect";
+/** An unknown-key message names at most this many accepted keys and counts the rest. */
+const MAX_LISTED_KEYS = 30;
+/**
+ * `Unknown operator. Expected one of: eq, ne, in`: what a closed struct reports for a key it does
+ * not declare, so that a caller can correct the key without guessing. Long lists are cut short.
+ */
+export function expectedOneOf(problem, accepted) {
+    if (accepted.length === 0) {
+        return `${problem}; there are none`;
+    }
+    const listed = accepted.slice(0, MAX_LISTED_KEYS).join(", ");
+    const rest = accepted.length - MAX_LISTED_KEYS;
+    return `${problem}. Expected one of: ${listed}${rest > 0 ? `, and ${rest} more` : ""}`;
+}
+/** A closed wire object with explicit key mappings and an unchanged decoded TypeScript shape. */
+export function wireStruct(fields, mapping, unknownKey = "Unknown key") {
+    const codec = Schema.Struct(fields).pipe(Schema.encodeKeys(mapping));
+    const encodedFields = Object.fromEntries(Object.entries(fields).map(([key, field]) => [
+        mapping[key] ?? key,
+        field,
+    ]));
+    const encodedKeys = Object.keys(encodedFields);
+    const unknown = Schema.String.check(Schema.isPattern(new RegExp(`^(?!(?:${encodedKeys.join("|")})$)`)));
+    const reverse = Object.fromEntries(Object.entries(mapping).map(([key, value]) => [value, key]));
+    const rename = (value, keys) => Object.fromEntries(Object.entries(value).map(([key, child]) => [keys[key] ?? key, child]));
+    const encoded = Schema.StructWithRest(Schema.Struct(encodedFields), [
+        Schema.Record(unknown, Schema.Never.annotate({ message: expectedOneOf(unknownKey, encodedKeys) })),
+    ]);
+    const decoded = Schema.toType(codec);
+    return encoded.pipe(Schema.decodeTo(decoded, SchemaTransformation.transform({
+        decode: (value) => rename(value, reverse),
+        encode: (value) => rename(value, mapping),
+    })));
+}

package/dist/workflow-runtime.d.ts

@@ -0,0 +1,116 @@
+import type { Effect } from "effect";
+import type { AgentTaskResult, AgentTaskStart, AgentTaskStarted } from "./agent-task-contract.js";
+import type { Connection } from "./connection.js";
+import type { Files } from "./files.js";
+import type { OntologyActions, OntologyReads, OntologyWrites } from "./runtime.js";
+import type { StartRecoveryInput, StartRecoveryOutcome } from "./start-recovery-contract.js";
+import type { WorkflowReservation } from "./runtime/workflow-admission.js";
+/**
+ * The ontology service's workflow runtime, shared through `globalThis` so that every copy of this
+ * module a bundler makes sees the same one. This module imports none of the Workflow SDK: the
+ * service reaches it, and so does every process that bundles the service, such as the platform's
+ * backend on another SDK major; `installWorkflowRuntime()` in the `server` entry loads the SDK.
+ *
+ * Binding: the ontology service installs a {@link WorkflowBinding} when it builds its routes; the
+ * step callback that `ontologyWorkflows()` mounts builds the service first when nothing has. Inside
+ * a `"use step"` function, `run(effect)` reads the run from the Workflow SDK's step context (an
+ * AsyncLocalStorage the SDK sets around every step), and the binding checks the run's workflow,
+ * resolves its user and runs the effect with the ontology runtime bound to it.
+ */
+export { WORKFLOW_BASE_PATH } from "./workflow-topics.js";
+/** The Workflow SDK's routes below the base path: `flow`, `step` and `webhook/<token>`. */
+export declare const WORKFLOW_ROUTE_BASE = "/.well-known/workflow/v1";
+/** What a step's effect may require: the ontology runtime, its actions and its connections. */
+export type WorkflowStepServices = OntologyReads | OntologyWrites | OntologyActions | Connection<string> | Files;
+/** The step that calls `run`, as the Workflow SDK's step context names it. */
+export interface WorkflowStepContext {
+    /** The SDK's id of the run's workflow function, as the step's queue message names it. */
+    readonly workflowName: string;
+    readonly workflowRunId: string;
+    readonly stepId: string;
+    readonly attempt: number;
+}
+/**
+ * Runs a step's effect as the workflow user of the run's workflow, and the steps of `agentTask`: its
+ * start, which hands the agent the task, and its expiry, when the task's timeout passed first.
+ */
+export interface WorkflowBinding {
+    /** Checks that an authenticated queue delivery names a workflow this ontology declares. */
+    readonly admitWorkflow?: (workflowName: string) => void;
+    readonly run: (step: WorkflowStepContext, effect: Effect.Effect<unknown, unknown, WorkflowStepServices>) => Promise<unknown>;
+    readonly startAgentTask: (step: WorkflowStepContext, input: AgentTaskStart) => Promise<AgentTaskStarted>;
+    readonly expireAgentTask: (step: WorkflowStepContext, taskId: string) => Promise<AgentTaskResult>;
+    /** One sweep of the pending action-trigger starts, for the platform's start recovery run. */
+    readonly recoverStarts: (step: WorkflowStepContext, input: StartRecoveryInput) => Promise<StartRecoveryOutcome>;
+}
+/**
+ * The platform's own workflow functions, which `ontologyWorkflows()` writes beside the workspace's
+ * and the Workflow SDK compiles with them. The generated Nitro plugin registers them at startup,
+ * compiled, so that the service starts them like a declared workflow's `run`.
+ */
+export interface PlatformWorkflows {
+    /** Sleeps, then starts the pending starts an action's request left; see `start-recovery.ts`. */
+    readonly recoverStarts: (...args: Array<never>) => Promise<unknown>;
+}
+/**
+ * The Workflow SDK's `start`, world and `resumeHook`, loaded on first use. {@link installWorkflowRuntime}
+ * registers them for the service's workflow routes: the service itself imports none of the Workflow
+ * SDK, so a process that bundles the service without workflows, such as the platform's backend,
+ * carries none of it.
+ */
+export interface WorkflowSdk {
+    readonly allocateRun?: () => Promise<WorkflowReservation>;
+    /** Installs admission around the world's decoded queue handler, before the flow handler loads. */
+    readonly prepareCallback?: () => Promise<void>;
+    readonly start: (workflow: unknown, args: Array<unknown>, options: {
+        readonly namespace: string;
+        readonly attributes?: Readonly<Record<string, string>>;
+        readonly reservation?: WorkflowReservation;
+    }) => Promise<{
+        readonly runId: string;
+    }>;
+    readonly world: () => Promise<unknown>;
+    /** Hydrate only an error payload; inputs and outputs stay unresolved. */
+    readonly hydrateError?: (value: unknown, run: {
+        readonly runId: string;
+        readonly deploymentId?: string;
+    }, kind: "step" | "run") => Promise<unknown>;
+    /** `resumeHook` from `workflow/api`: it rejects with `HookNotFoundError` for a gone hook. */
+    readonly resumeHook: (token: string, payload: unknown) => Promise<unknown>;
+}
+/** Registers the Workflow SDK for the service's workflow routes; the first registration stays. */
+export declare function setWorkflowSdk(sdk: WorkflowSdk): void;
+/** Installs the binding of the service that serves this process's runs; the latest one wins. */
+export declare function setWorkflowBinding(binding: WorkflowBinding | undefined): void;
+export declare function workflowBinding(): WorkflowBinding | undefined;
+/** Registers the platform's compiled workflow functions; the latest registration wins. */
+export declare function setPlatformWorkflows(workflows: PlatformWorkflows | undefined): void;
+/** The platform's workflow functions as the generated plugin registered them; `undefined` before. */
+export declare function platformWorkflows(): PlatformWorkflows | undefined;
+/** The Workflow SDK as `installWorkflowRuntime()` registered it; `undefined` before. */
+export declare function workflowSdk(): WorkflowSdk | undefined;
+/** `run` was called where no step runs: in a `"use workflow"` body or outside any workflow. */
+export declare class WorkflowStepRequired extends Error {
+    constructor();
+}
+/** The step that is executing; throws outside a step. */
+export declare function currentWorkflowStep(): WorkflowStepContext | undefined;
+/**
+ * Runs an Effect inside a `"use step"` function with the ontology runtime provided and bound to the
+ * run's workflow user: entity handles (`Lead.find`, `Lead.actions.addNote(…)`) and the workflow's
+ * connections work as in an action handler, with each read and action checked against the
+ * workflow user's permissions and recorded in history like any caller's. A failure rejects the
+ * promise, so the SDK records a failed step; a refusal that would repeat (a missing permission, a
+ * rejected action, an invalid input) is marked fatal and not retried. The rejection carries a
+ * sanitized message and the service logs the full cause. Outside a step it throws
+ * {@link WorkflowStepRequired}.
+ */
+export declare function run<A, E>(effect: Effect.Effect<A, E, WorkflowStepServices>): Promise<A>;
+/**
+ * The step that is executing and the binding of the service that serves it. Throws
+ * {@link WorkflowStepRequired} outside a step, and before any service bound this process's runs.
+ */
+export declare function boundStep(): {
+    readonly binding: WorkflowBinding;
+    readonly step: WorkflowStepContext;
+};

package/dist/workflow-runtime.js

@@ -0,0 +1,109 @@
+import { deploymentFromEnv, requireDeploymentCapability } from "./deployment.js";
+/**
+ * The ontology service's workflow runtime, shared through `globalThis` so that every copy of this
+ * module a bundler makes sees the same one. This module imports none of the Workflow SDK: the
+ * service reaches it, and so does every process that bundles the service, such as the platform's
+ * backend on another SDK major; `installWorkflowRuntime()` in the `server` entry loads the SDK.
+ *
+ * Binding: the ontology service installs a {@link WorkflowBinding} when it builds its routes; the
+ * step callback that `ontologyWorkflows()` mounts builds the service first when nothing has. Inside
+ * a `"use step"` function, `run(effect)` reads the run from the Workflow SDK's step context (an
+ * AsyncLocalStorage the SDK sets around every step), and the binding checks the run's workflow,
+ * resolves its user and runs the effect with the ontology runtime bound to it.
+ */
+export { WORKFLOW_BASE_PATH } from "./workflow-topics.js";
+/** The Workflow SDK's routes below the base path: `flow`, `step` and `webhook/<token>`. */
+export const WORKFLOW_ROUTE_BASE = "/.well-known/workflow/v1";
+const BINDING = Symbol.for("@segmentstream/ontology/workflow-binding");
+const SDK = Symbol.for("@segmentstream/ontology/workflow-sdk");
+const PLATFORM = Symbol.for("@segmentstream/ontology/platform-workflows");
+const globals = globalThis;
+/** Registers the Workflow SDK for the service's workflow routes; the first registration stays. */
+export function setWorkflowSdk(sdk) {
+    globals[SDK] ??= sdk;
+}
+/** Installs the binding of the service that serves this process's runs; the latest one wins. */
+export function setWorkflowBinding(binding) {
+    globals[BINDING] = binding;
+}
+export function workflowBinding() {
+    return globals[BINDING];
+}
+/** Registers the platform's compiled workflow functions; the latest registration wins. */
+export function setPlatformWorkflows(workflows) {
+    globals[PLATFORM] = workflows;
+}
+/** The platform's workflow functions as the generated plugin registered them; `undefined` before. */
+export function platformWorkflows() {
+    return globals[PLATFORM];
+}
+/** The Workflow SDK as `installWorkflowRuntime()` registered it; `undefined` before. */
+export function workflowSdk() {
+    return globals[SDK];
+}
+/** `run` was called where no step runs: in a `"use workflow"` body or outside any workflow. */
+export class WorkflowStepRequired extends Error {
+    constructor() {
+        super('run(effect) runs only inside a "use step" function of a declared workflow. The ' +
+            '"use workflow" body orchestrates steps and does no I/O of its own; code outside a ' +
+            "workflow reads and changes records through the ontology service's API.");
+        this.name = "WorkflowStepRequired";
+    }
+}
+/**
+ * The Workflow SDK's process-wide step context: an AsyncLocalStorage the SDK keeps on
+ * `globalThis` under this symbol and runs every step inside (`@workflow/core`'s
+ * `step/context-storage`). Reading it needs no import of the SDK, which a deployed function may not
+ * be able to resolve.
+ */
+const STEP_CONTEXT = Symbol.for("WORKFLOW_STEP_CONTEXT_STORAGE");
+/** The step that is executing; throws outside a step. */
+export function currentWorkflowStep() {
+    const storage = globalThis[STEP_CONTEXT];
+    const store = storage?.getStore();
+    const step = store?.stepMetadata;
+    const run = store?.workflowMetadata;
+    // A "use workflow" body has no step metadata, and code outside a run has no store at all.
+    if (typeof step?.stepId !== "string" ||
+        typeof run?.workflowName !== "string" ||
+        typeof run.workflowRunId !== "string") {
+        return undefined;
+    }
+    return {
+        workflowName: run.workflowName,
+        workflowRunId: run.workflowRunId,
+        stepId: step.stepId,
+        attempt: typeof step.attempt === "number" ? step.attempt : 1,
+    };
+}
+/**
+ * Runs an Effect inside a `"use step"` function with the ontology runtime provided and bound to the
+ * run's workflow user: entity handles (`Lead.find`, `Lead.actions.addNote(…)`) and the workflow's
+ * connections work as in an action handler, with each read and action checked against the
+ * workflow user's permissions and recorded in history like any caller's. A failure rejects the
+ * promise, so the SDK records a failed step; a refusal that would repeat (a missing permission, a
+ * rejected action, an invalid input) is marked fatal and not retried. The rejection carries a
+ * sanitized message and the service logs the full cause. Outside a step it throws
+ * {@link WorkflowStepRequired}.
+ */
+export async function run(effect) {
+    const { binding, step } = boundStep();
+    return (await binding.run(step, effect));
+}
+/**
+ * The step that is executing and the binding of the service that serves it. Throws
+ * {@link WorkflowStepRequired} outside a step, and before any service bound this process's runs.
+ */
+export function boundStep() {
+    requireDeploymentCapability(deploymentFromEnv(), "workflows");
+    const step = currentWorkflowStep();
+    if (step === undefined) {
+        throw new WorkflowStepRequired();
+    }
+    const binding = workflowBinding();
+    if (binding === undefined) {
+        throw new Error("No ontology service serves workflow runs in this process; the step callback that " +
+            "ontologyWorkflows() mounts builds it first.");
+    }
+    return { binding, step };
+}

package/dist/workflow-topics.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The ontology's queue and callback names, shared by the build (`./nitro.ts`) and the runtime
+ * (`./service/workflows.ts`). This module imports nothing.
+ */
+/** The path the Workflow SDK's callbacks for the ontology's runs live under. */
+export declare const WORKFLOW_BASE_PATH = "/api/ontology";
+/**
+ * The queue namespace of the ontology's runs, fixed at build time. The app and the agent of the
+ * same deployment run their own workflows on the SDK's default topics and on `eve<hex>`; this one
+ * keeps the ontology's messages on `__ontology_wkf_workflow_*`.
+ */
+export declare const ONTOLOGY_QUEUE_NAMESPACE = "ontology";
+/** The topic prefix of the ontology's queue: `__ontology_wkf_workflow_`. */
+export declare const ONTOLOGY_QUEUE_PREFIX = "__ontology_wkf_workflow_";
+/**
+ * The route of the Workflow SDK's queue callback, below the ontology service's path. Since
+ * Workflow SDK 5 a run's steps execute inside the flow callback and background steps come back on
+ * the workflow topic: there is no step route.
+ */
+export declare const WORKFLOW_FLOW_ROUTE = "/api/ontology/.well-known/workflow/v1/flow";
+/** The queue trigger of the flow function: the ontology's namespaced workflow topic. */
+export declare const WORKFLOW_QUEUE_TRIGGER: {
+    readonly type: "queue/v2beta";
+    readonly topic: "__ontology_wkf_workflow_*";
+    readonly consumer: "default";
+    readonly retryAfterSeconds: 5;
+    readonly initialDelaySeconds: 0;
+};

package/dist/workflow-topics.js

@@ -0,0 +1,28 @@
+/**
+ * The ontology's queue and callback names, shared by the build (`./nitro.ts`) and the runtime
+ * (`./service/workflows.ts`). This module imports nothing.
+ */
+/** The path the Workflow SDK's callbacks for the ontology's runs live under. */
+export const WORKFLOW_BASE_PATH = "/api/ontology";
+/**
+ * The queue namespace of the ontology's runs, fixed at build time. The app and the agent of the
+ * same deployment run their own workflows on the SDK's default topics and on `eve<hex>`; this one
+ * keeps the ontology's messages on `__ontology_wkf_workflow_*`.
+ */
+export const ONTOLOGY_QUEUE_NAMESPACE = "ontology";
+/** The topic prefix of the ontology's queue: `__ontology_wkf_workflow_`. */
+export const ONTOLOGY_QUEUE_PREFIX = `__${ONTOLOGY_QUEUE_NAMESPACE}_wkf_workflow_`;
+/**
+ * The route of the Workflow SDK's queue callback, below the ontology service's path. Since
+ * Workflow SDK 5 a run's steps execute inside the flow callback and background steps come back on
+ * the workflow topic: there is no step route.
+ */
+export const WORKFLOW_FLOW_ROUTE = `${WORKFLOW_BASE_PATH}/.well-known/workflow/v1/flow`;
+/** The queue trigger of the flow function: the ontology's namespaced workflow topic. */
+export const WORKFLOW_QUEUE_TRIGGER = {
+    type: "queue/v2beta",
+    topic: `${ONTOLOGY_QUEUE_PREFIX}*`,
+    consumer: "default",
+    retryAfterSeconds: 5,
+    initialDelaySeconds: 0,
+};

package/dist/workflow.d.ts

@@ -0,0 +1,284 @@
+import type { Schema } from "effect";
+import type { ActionInput, ActionResult, AnyAction } from "./action.js";
+import type { AnyConnectionHandle } from "./connection.js";
+import type { ActionHandle, AnyStoredEntity } from "./entity.js";
+import type { Edit } from "./runtime/history.js";
+import type { Principal } from "./runtime.js";
+import type { WebhookSignatureScheme } from "./webhooks.js";
+/** Marks the values `workflow(…)` returns, so that `check` can tell them from look-alikes. */
+export declare const WorkflowTypeId: unique symbol;
+/** Marks the values trigger constructors such as `cron(…)` and `after(…)` return. */
+export declare const WorkflowTriggerTypeId: unique symbol;
+/** The most workflows one ontology may declare. */
+export declare const MAX_WORKFLOWS = 50;
+/** The most action triggers, `after(…)`, one ontology may declare across its workflows. */
+export declare const MAX_ACTION_TRIGGERS = 20;
+/**
+ * A cron trigger, `cron(name, expression, { description, input })`: the platform writes it into
+ * the workspace deployment's crons, and each invocation starts the workflow with `input`. Five
+ * fields, read in UTC.
+ */
+export interface CronTrigger<Name extends string = string, Input = unknown> {
+    readonly [WorkflowTriggerTypeId]: typeof WorkflowTriggerTypeId;
+    readonly kind: "cron";
+    /** A camelCase name, unique within its workflow: `weekdayMorning`. */
+    readonly name: Name;
+    /** When and why the workflow starts, for people, agents and the catalog. */
+    readonly description: string;
+    /** minute hour day-of-month month day-of-week, in UTC: `"0 8 * * 1-5"`. */
+    readonly cron: string;
+    /** The workflow's input, in TypeScript names; `undefined` when the trigger declares none. */
+    readonly input: Input | undefined;
+}
+export interface CronOptions<Input = unknown> {
+    /** Required, like every declaration: when and why the workflow starts. */
+    readonly description: string;
+    /** The workflow's input for this trigger. May be omitted when the workflow's input accepts `{}`. */
+    readonly input?: Input;
+}
+/** Declares a cron trigger; list it in `workflow(name, { triggers })`. UTC, five fields. */
+export declare function cron<const Name extends string, Input = unknown>(name: Name, expression: string, options: CronOptions<Input>): CronTrigger<Name, Input>;
+/**
+ * One committed run of an action, as an action trigger's `when` and `input` receive it: the facts
+ * history stores, as one value. `input` and `result` are typed from the action handle; for a trigger
+ * on an entity they are `unknown`.
+ */
+export interface ActionEvent<Input = unknown, Result = unknown> {
+    /** The qualified action as history records it: `<entity>.<action>`. */
+    readonly action: string;
+    /** Shared by every history row the run wrote, and carried by the run's `startedBy`. */
+    readonly actionId: string;
+    /** When the action ran, ISO 8601. */
+    readonly at: string;
+    /** Who ran the action, as after-commit hooks receive it. */
+    readonly principal: Principal;
+    /** The decoded input, in TypeScript names. */
+    readonly input: Input;
+    /** What the action's handler returned. */
+    readonly result: Result;
+    /** Every change the action made, as the action response lists them. */
+    readonly edits: ReadonlyArray<Edit>;
+}
+/**
+ * The record of the trigger's entity an action edited: its id, and the stored record before and
+ * after the action. `before` is `undefined` on a create, `after` on a delete. Only stored
+ * properties and relationship ids; warehouse-backed properties are absent.
+ */
+export interface TriggerRecord<T = unknown> {
+    readonly record: string;
+    readonly before: T | undefined;
+    readonly after: T | undefined;
+}
+/**
+ * A synchronous function of an action trigger: no `await`, no effects, no entity handles. It runs
+ * inside the action's transaction and reads only the event and the record.
+ */
+export type TriggerFunction<Event, T, Out> = (event: Event, record: TriggerRecord<T>) => Out;
+/**
+ * An action trigger, `after(name, target, { description, when, input })`: starts the workflow after
+ * an action of `entity` commits, `action` or any of them. `when` and `input` are code: the manifest
+ * records the kind, the name, the description, the entity and the action, never the functions.
+ */
+export interface ActionTrigger<Name extends string = string, Input = unknown> {
+    readonly [WorkflowTriggerTypeId]: typeof WorkflowTriggerTypeId;
+    readonly kind: "action";
+    /** A camelCase name, unique within its workflow: `qualified`. */
+    readonly name: Name;
+    /** Which actions start the workflow and why, for people, agents and the catalog. */
+    readonly description: string;
+    /** The entity's wire name, `lead`; empty when the target is not a handle, which `check` reports. */
+    readonly entity: string;
+    /** The action's wire name, `change_status`; `undefined` for a trigger on the whole entity. */
+    readonly action: string | undefined;
+    /** The handle as declared, for `check`. */
+    readonly target: unknown;
+    /** Whether the run starts; omitted means always. */
+    readonly when: TriggerFunction<ActionEvent, unknown, boolean> | undefined;
+    /** The workflow's input, in TypeScript names; omitted means `{}`. */
+    readonly input: TriggerFunction<ActionEvent, unknown, Input> | undefined;
+}
+/**
+ * Where a webhook's deliveries are checked: a provider's signature format and the workspace secret
+ * that holds its signing secret. Without one, the webhook's URL ends in a token.
+ */
+export interface WebhookSignature {
+    readonly scheme: WebhookSignatureScheme;
+    /** A workspace secret's name, such as `stripe-webhook-signing-secret`; its value stays in the platform. */
+    readonly secret: string;
+}
+/** Meta's registration handshake; the verify token is a workspace secret, separate from the app secret. */
+export interface WebhookVerification {
+    readonly scheme: "meta";
+    readonly verifyToken: string;
+}
+/**
+ * A webhook trigger, `webhook(name, { description, signature, headers })`: the ontology service
+ * starts the workflow for each genuine delivery to `/api/webhooks/<name>`, with the delivery as its
+ * input. The workflow's `input` is `webhookDelivery`.
+ */
+export interface WebhookTrigger<Name extends string = string> {
+    readonly [WorkflowTriggerTypeId]: typeof WorkflowTriggerTypeId;
+    readonly kind: "webhook";
+    /** A camelCase name, unique among the ontology's webhooks; its wire name is the URL's segment. */
+    readonly name: Name;
+    /** What the provider sends and why, for people, agents and the catalog. */
+    readonly description: string;
+    /** How deliveries are checked; `undefined` for a token in the URL. */
+    readonly signature: WebhookSignature | undefined;
+    /** Optional registration handshake, answered without starting the workflow. */
+    readonly verification?: WebhookVerification | undefined;
+    /** Lowercase names of the request headers the delivery carries. */
+    readonly headers: ReadonlyArray<string>;
+}
+export interface WebhookOptions {
+    /** Required, like every declaration: what the provider sends and why. */
+    readonly description: string;
+    /**
+     * The provider's signature format and the workspace secret holding its signing secret. Omit it
+     * for a provider that signs nothing: the URL then ends in a token.
+     */
+    readonly signature?: WebhookSignature;
+    /** Meta's GET registration handshake. Requires a Meta signature for POST deliveries. */
+    readonly verification?: WebhookVerification;
+    /** Lowercase request headers to pass to the workflow, at most ten: `["x-event-type"]`. */
+    readonly headers?: ReadonlyArray<string>;
+}
+/**
+ * Declares a webhook trigger; list it in `workflow(name, { input: webhookDelivery, triggers })`.
+ * A workflow with a webhook trigger has only webhook triggers.
+ */
+export declare function webhook<const Name extends string>(name: Name, options: WebhookOptions): WebhookTrigger<Name>;
+/**
+ * What starts a workflow on its own. A discriminated union on `kind`: `cron`, `action` and
+ * `webhook`; other kinds are additions.
+ */
+export type WorkflowTrigger<Input = unknown> = CronTrigger<string, Input> | ActionTrigger<string, Input> | WebhookTrigger;
+export interface AfterOptions<Event, T, Input> {
+    /** Required, like every declaration: which actions start the workflow and why. */
+    readonly description: string;
+    /** Whether the run starts, from the event and the record; synchronous. Omitted means always. */
+    readonly when?: TriggerFunction<Event, T, boolean>;
+    /**
+     * The workflow's input, from the event and the record; synchronous. Omitted means `{}`, which the
+     * workflow's input must accept.
+     */
+    readonly input?: TriggerFunction<Event, T, Input>;
+}
+/** An authored action handle, `Lead.actions.changeStatus`. */
+export type AnyActionHandle = AnyAction & ActionHandle;
+/** The record type of an action handle's entity. */
+type HandleRecord<A> = A extends ActionHandle<string, string, infer T> ? T : unknown;
+/**
+ * Declares an action trigger; list it in `workflow(name, { triggers })`. The target is an action
+ * handle, `Lead.actions.changeStatus`, or an entity handle, `Lead`, for any of its actions, authored
+ * or generated. A trigger does not fire for an action the workflow's own user ran.
+ */
+export declare function after<const Name extends string, A extends AnyActionHandle, Input = unknown>(name: Name, target: A, options: AfterOptions<ActionEvent<ActionInput<A>, ActionResult<A>>, HandleRecord<A>, Input>): ActionTrigger<Name, Input>;
+export declare function after<const Name extends string, E extends AnyStoredEntity, Input = unknown>(name: Name, target: E, options: AfterOptions<ActionEvent, E["Type"], Input>): ActionTrigger<Name, Input>;
+/** The bounds of {@link changed}: the value before, the value after, or both. */
+export interface ChangedBounds<V> {
+    /** The value before the action; `null` matches a record that had none or did not exist. */
+    readonly from?: V | null;
+    /** The value after the action; `null` matches a record that has none or was deleted. */
+    readonly to?: V | null;
+}
+/**
+ * A `when` predicate: true when the record's `field` differs before and after the action and
+ * matches the bounds given. A missing record or value counts as no value, so a create that sets
+ * `status` changed it, and `{ to: "qualified" }` does not fire when it was already qualified.
+ */
+export declare function changed<T extends object, K extends keyof T & string>(field: K, bounds?: ChangedBounds<NoInfer<T[K]>>): TriggerFunction<unknown, T, boolean>;
+/** Whether a function is declared `async`; action trigger functions must be synchronous. */
+export declare function isAsyncFunction(value: unknown): boolean;
+/** Whether a value was declared with a trigger constructor such as `cron(…)` or `after(…)`. */
+export declare function isWorkflowTrigger(value: unknown): value is WorkflowTrigger;
+/**
+ * Who started a run, as the ontology service passes it to the workflow function as its second
+ * argument and records it in plaintext run attributes: a trigger, a member through
+ * `POST /api/ontology/workflows/:workflow/start`, or the platform on behalf of a person.
+ */
+export interface WorkflowRunContext {
+    readonly startedBy: {
+        readonly kind: "trigger";
+        /** The trigger's kind; runs started before it was recorded omit it. */
+        readonly triggerKind?: "cron" | "action" | "webhook";
+        /** `<workflow>.<trigger>`, in wire names. */
+        readonly trigger: string;
+        /** For an action trigger: the action whose commit started the run. */
+        readonly actionId?: string;
+        /** For an action trigger evaluated per edited record: that record. */
+        readonly recordId?: string;
+    } | {
+        readonly kind: "member";
+        readonly userId: string;
+    } | {
+        readonly kind: "platform";
+        readonly userId: string | null;
+    };
+}
+/** The function a workflow runs: a `"use workflow"` function of the decoded input. */
+export type WorkflowFunction<Input> = (input: Input, context: WorkflowRunContext) => Promise<unknown>;
+type AnyInputSchema = Schema.Codec<any, any>;
+type InputOf<S> = S extends Schema.Codec<infer A, unknown> ? A : Record<string, never>;
+export interface WorkflowOptions<S extends AnyInputSchema | undefined = undefined> {
+    /** Required, like every declaration: what the workflow does and why. */
+    readonly description: string;
+    /**
+     * The declared role, other than `member`, whose permissions the workflow's runs hold together
+     * with member's. Its runs act as the workflow's own service user.
+     */
+    readonly role: string;
+    /** A `Schema.Struct` of the workflow's input. Omitted means `{}`. */
+    readonly input?: S;
+    /** The `"use workflow"` function. It receives the decoded input. */
+    readonly run: WorkflowFunction<InputOf<S>>;
+    /**
+     * What starts the workflow on its own: `cron(…)`, `after(…)` or `webhook(…)`. None means the
+     * app, the CLI or another workflow.
+     */
+    readonly triggers?: ReadonlyArray<WorkflowTrigger>;
+    /** Connections a step calls directly, each listed in `defineOntology({ connections })`. */
+    readonly connections?: ReadonlyArray<AnyConnectionHandle>;
+}
+/**
+ * A workflow: a durable process written with the Vercel Workflow SDK, run by the ontology service
+ * as its own keyless service user holding `role`. The declaration only records; `check` and the
+ * sandbox evaluation of `index.ts` never call `run`.
+ */
+export interface Workflow<Name extends string = string, Input = unknown> {
+    readonly [WorkflowTypeId]: typeof WorkflowTypeId;
+    /** A camelCase name, unique among the ontology's workflows. It names the workflow user. */
+    readonly name: Name;
+    readonly description: string;
+    readonly role: string;
+    /** The input schema, `undefined` when the workflow takes `{}`. */
+    readonly input: Schema.Top | undefined;
+    readonly run: WorkflowFunction<Input>;
+    readonly triggers: ReadonlyArray<WorkflowTrigger>;
+    readonly connections: ReadonlyArray<AnyConnectionHandle>;
+}
+/** Any workflow, whatever its input. */
+export type AnyWorkflow = Workflow<string, any>;
+/** Declares a workflow; list it in `defineOntology({ workflows })`. */
+export declare function workflow<const Name extends string, S extends AnyInputSchema | undefined = undefined>(name: Name, options: WorkflowOptions<S>): Workflow<Name, InputOf<S>>;
+/** Whether a value was declared with `workflow(…)`. */
+export declare function isWorkflow(value: unknown): value is AnyWorkflow;
+/** Which field of a cron expression does not parse. */
+export type CronProblem = "fields" | "minute" | "hour" | "day_of_month" | "month" | "day_of_week" | "both_days";
+/**
+ * The first minute after `after` at which the expression fires, in UTC, within the next 366 days;
+ * `undefined` for an invalid expression or one that does not fire in that time.
+ */
+export declare function nextCronTime(expression: string, after: Date): Date | undefined;
+/**
+ * Whether a valid expression names no day that exists: a day of the month no listed month has,
+ * such as `0 0 31 4 *` or `0 0 30 2 *`. The 29th of February counts: it exists in leap years.
+ */
+export declare function cronNeverFires(expression: string): boolean;
+/**
+ * Checks a cron expression by the syntax Vercel crons accept: five fields, read in UTC, each `*`,
+ * numbers, ranges, steps and lists, without month or day names, and with at most one of the day
+ * fields restricted. It validates syntax only. `undefined` when it parses.
+ */
+export declare function cronProblem(expression: string): CronProblem | undefined;
+export {};