zitejs 0.10.0-start.1 → 0.10.0-start.3

package/dist/esm/start/problems.js

@@ -0,0 +1,8 @@
+/** Every problem in a description, one line each, named by its rule. Any of them fails the build. */
+export function descriptionProblems(description) {
+    return [
+        ...description.functions.flatMap((f) => f.problems.map((p) => `function ${f.id}${f.file ? ` (${f.file})` : ""}: ${p}`)),
+        ...description.routes.flatMap((r) => r.problems.map((p) => `route ${r.path}: ${p}`)),
+        ...(description.workflows ?? []).flatMap((w) => w.problems.map((p) => `workflow ${w.id} (${w.file}): ${p}`)),
+    ];
+}

package/dist/esm/start/router.js

@@ -30,5 +30,8 @@ export function createZiteRouter(options) {
             context.user = dehydrated.user;
         },
     });
+    const host = currentHost();
+    if (host)
+        host.router = router;
     return router;
 }

package/dist/esm/start/runLog.d.ts

@@ -0,0 +1,5 @@
+export declare const preview: (value: unknown) => string | undefined;
+export declare const errorOf: (error: unknown) => {
+    code: string;
+    message: string;
+};

package/dist/esm/start/runLog.js

@@ -0,0 +1,18 @@
+import { ZiteError } from "./index.js";
+const PREVIEW_LIMIT = 8_000;
+export const preview = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "object" && value !== null && Symbol.asyncIterator in value)
+        return "[stream]";
+    try {
+        const json = JSON.stringify(value);
+        return json && json.length > PREVIEW_LIMIT ? `${json.slice(0, PREVIEW_LIMIT)}…` : json;
+    }
+    catch {
+        return "[unserializable]";
+    }
+};
+export const errorOf = (error) => error instanceof ZiteError
+    ? { code: error.code, message: error.message }
+    : { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : String(error) };

package/dist/esm/start/scope.d.ts

@@ -1,5 +1,5 @@
-import type { User, ZiteRequestContext } from "./types.js";
-export type AccessKind = "signedIn" | "anyone" | "webhook" | "workflow";
+import type { AccessKind, User, ZiteRequestContext } from "./types.js";
+export type { AccessKind } from "./types.js";
 export type AccessScope = {
     kind: AccessKind;
     user: User | null;

package/dist/esm/start/server.d.ts

@@ -1,42 +1,32 @@
-import { type AccessKind } from "./scope.js";
-import type { RunRecord, ZiteRequestContext } from "./types.js";
+import type { HostProps, PlatformBinding, ZiteRequestContext } from "./types.js";
 export { runWithHost } from "./scope.js";
 export { describeApp } from "./describe.js";
-export type { RunRecord } from "./types.js";
-export type PlatformCallInput = {
-    integrationId: string;
-    className: string;
-    methodName: string;
-    params: unknown;
-    access: AccessKind;
-    userId: string | null;
-    requestId: string;
-};
-/** The `ZITE` service binding the host's Platform entrypoint gives every app script. */
-export type PlatformBinding = {
-    call(call: PlatformCallInput): Promise<unknown>;
-    /** One batch per request, after its response has ended. */
-    runs(batch: {
-        requestId: string;
-        runs: RunRecord[];
-    }): Promise<void>;
-};
+export type { HostProps, PlatformBinding, PlatformCallInput, PlatformCallResult, PlatformSession, RunRecord } from "./types.js";
 /**
- * Routes every zitejs data, integration and email call through `call`, and only
- * inside an access scope. The access kind travels with the call so the platform
- * can record what a page read and, later, narrow anonymous reads.
+ * Routes every zitejs data, integration and email call to this request's
+ * platform, on one session, and only inside an access scope. The access kind
+ * travels with the call so the platform can record what a page read and narrow
+ * anonymous reads.
  */
-export declare function installPlatformTransport(call: (input: PlatformCallInput) => Promise<unknown>): void;
-/** The host's `x-zite-*` headers. Only the host can set them: the front strips them from public traffic. */
-export declare function hostContextFromRequest(request: Request): ZiteRequestContext;
+export declare function installPlatformTransport(): void;
+/** What the host dispatched this request with. Headers are ignored: props are the only thing it alone can set. */
+export declare function hostContextFromProps(request: Request, props: HostProps): ZiteRequestContext;
+/**
+ * A request the host didn't dispatch: `zitejs describe` under `vite preview`,
+ * and tests, which pass their own platform. Deployed builds have no public URL,
+ * so in production every request carries props.
+ */
+export declare function hostContextFromRequest(request: Request, platform?: PlatformBinding): ZiteRequestContext;
 /** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
 export declare const builtFunctionIds: () => string[];
+/** Each server function's `description` option, written in by `zite()` at build. */
+export declare const builtFunctionDescriptions: () => Record<string, string>;
 type Fetch = (request: Request, ...rest: unknown[]) => Promise<Response> | Response;
 /**
- * The fetch handler of a Start app's server entry. Describe calls get the app's
- * description; everything else runs TanStack with the host's identity in
- * server-only storage. Platform calls go to the `ZITE` binding from the Worker's
- * env, or to `platform` when a test or local dev supplies one.
+ * The fetch handler of a Start app's server entry. A request the host
+ * dispatched carries its identity and platform in props; anything else (describe
+ * under `vite preview`, tests) reads `x-zite-*` headers and uses `platform`
+ * if one is given.
  */
 export declare function createZiteFetch(options: {
     handler: {

package/dist/esm/start/server.js

@@ -1,30 +1,52 @@
+import { ZiteError, ZITE_ERROR_STATUS } from "./index.js";
 import { describeApp } from "./describe.js";
+import { preview } from "./runLog.js";
 import { getHost, requireScope, runWithHost } from "./scope.js";
+import { loadWorkflows, loggedInput, runWorkflow } from "./workflowRun.js";
 export { runWithHost } from "./scope.js";
 export { describeApp } from "./describe.js";
 /**
- * Routes every zitejs data, integration and email call through `call`, and only
- * inside an access scope. The access kind travels with the call so the platform
- * can record what a page read and, later, narrow anonymous reads.
+ * Routes every zitejs data, integration and email call to this request's
+ * platform, on one session, and only inside an access scope. The access kind
+ * travels with the call so the platform can record what a page read and narrow
+ * anonymous reads.
  */
-export function installPlatformTransport(call) {
-    const sdkCall = (integrationId, className, methodName, params) => {
+export function installPlatformTransport() {
+    const sdkCall = async (integrationId, className, methodName, params) => {
         const scope = requireScope(`${className}.${methodName}`);
-        return call({
-            integrationId,
-            className,
-            methodName,
-            params,
-            access: scope.kind,
-            userId: scope.user?.id ?? null,
-            requestId: getHost()?.requestId ?? "",
-        });
+        const host = getHost();
+        // Fails closed: no platform means no platform access, never a fallback.
+        if (!host?.platform)
+            throw new Error("The Zite platform binding is missing");
+        host.session ??= Promise.resolve(host.platform.session());
+        const result = await (await host.session).call({ integrationId, className, methodName, params, access: scope.kind });
+        if ("value" in result)
+            return result.value;
+        const { code, message } = result.error;
+        throw new ZiteError(code in ZITE_ERROR_STATUS ? code : "INTERNAL_ERROR", message);
     };
     globalThis.__wrapSdkCall = sdkCall;
 }
 const decodeUser = (value) => JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0))));
-/** The host's `x-zite-*` headers. Only the host can set them: the front strips them from public traffic. */
-export function hostContextFromRequest(request) {
+const INVOKE_KINDS = new Set(["webhook", "describe", "workflow", "warm"]);
+/** What the host dispatched this request with. Headers are ignored: props are the only thing it alone can set. */
+export function hostContextFromProps(request, props) {
+    return {
+        requestId: props.requestId,
+        url: request.url,
+        user: props.user,
+        mode: props.mode,
+        invoke: props.invoke,
+        runs: [],
+        platform: props.platform,
+    };
+}
+/**
+ * A request the host didn't dispatch: `zitejs describe` under `vite preview`,
+ * and tests, which pass their own platform. Deployed builds have no public URL,
+ * so in production every request carries props.
+ */
+export function hostContextFromRequest(request, platform) {
     const { headers } = request;
     const user = headers.get("x-zite-user");
     const [kind, name = ""] = headers.get("x-zite-invoke")?.split(":") ?? [];
@@ -32,12 +54,24 @@ export function hostContextFromRequest(request) {
         requestId: headers.get("x-zite-request-id") ?? crypto.randomUUID(),
         url: request.url,
         user: user ? decodeUser(user) : null,
-        invoke: kind === "webhook" || kind === "describe" || kind === "workflow" ? { kind, name } : null,
+        mode: "live",
+        invoke: INVOKE_KINDS.has(kind) ? { kind: kind, name } : null,
         runs: [],
+        platform,
     };
 }
 /** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
 export const builtFunctionIds = () => "__ZITE_FN_IDS__".split(",").filter((id) => id && !id.startsWith("__ZITE"));
+const parseDescriptions = (json) => {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+};
+/** Each server function's `description` option, written in by `zite()` at build. */
+export const builtFunctionDescriptions = () => parseDescriptions("__ZITE_FN_DESCRIPTIONS__");
 // Server functions also run while a streamed page renders, so the run log is
 // complete only once the body has been read to the end.
 const onBodyEnd = (response, done) => {
@@ -47,35 +81,79 @@ const onBodyEnd = (response, done) => {
     }
     return new Response(response.body.pipeThrough(new TransformStream({ flush: done })), response);
 };
+const INVOKE_PATH = "/_zite/invoke";
+// The host sends `{ input }`; a platform-fired run's input carries the runner's
+// `__cron`, `__poll` or `__webhook` state, exactly as for classic endpoints.
+async function invokeWorkflow(request, host, workflows) {
+    if (request.method !== "POST" || new URL(request.url).pathname !== INVOKE_PATH)
+        return new Response("Not found", { status: 404 });
+    const name = host.invoke?.name;
+    const found = workflows.find((w) => w.id === name);
+    if (!found)
+        return Response.json({ ok: false, error: { code: "NOT_FOUND", message: `No workflow named ${name}` } }, { status: 404 });
+    const input = (await request.json().catch(() => ({})))?.input;
+    const startedAt = Date.now();
+    const result = await runWorkflow(found.workflow, input);
+    host.runs.push({
+        fn: `workflow:${found.id}`,
+        name: found.id,
+        nested: false,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        input: preview(loggedInput(input)),
+        ...(result.ok ? { output: preview(result.output) } : { error: result.error }),
+    });
+    return Response.json(result, { status: result.ok ? 200 : 500 });
+}
+const isZiteError = (error) => error instanceof Error && error.name === "ZiteError" && error.code in ZITE_ERROR_STATUS;
+// TanStack renders any loader error as a 500. A page refused with a ZiteError
+// (a missing role, a record that isn't there) answers with that error's status.
+const pageStatus = (host) => {
+    const matches = host.router?.state?.matches;
+    const failed = matches?.find((match) => match.status === "error")?.error;
+    return isZiteError(failed) ? ZITE_ERROR_STATUS[failed.code] : undefined;
+};
 /**
- * The fetch handler of a Start app's server entry. Describe calls get the app's
- * description; everything else runs TanStack with the host's identity in
- * server-only storage. Platform calls go to the `ZITE` binding from the Worker's
- * env, or to `platform` when a test or local dev supplies one.
+ * The fetch handler of a Start app's server entry. A request the host
+ * dispatched carries its identity and platform in props; anything else (describe
+ * under `vite preview`, tests) reads `x-zite-*` headers and uses `platform`
+ * if one is given.
  */
 export function createZiteFetch(options) {
-    let binding = options.platform;
-    // Fails closed: no binding means no platform access, never a fallback.
-    const platform = () => {
-        if (!binding)
-            throw new Error("The Zite platform binding is missing");
-        return binding;
-    };
-    installPlatformTransport((call) => platform().call(call));
+    installPlatformTransport();
+    // Loaded on first use, so a page request never pays for importing workflow modules.
+    let workflows;
+    const loadedWorkflows = () => (workflows ??= loadWorkflows());
     return async (request, ...rest) => {
-        binding ??= rest[0]?.ZITE;
-        if (request.headers.get("x-zite-invoke") === "describe") {
-            return Response.json(await describeApp({ fnIds: builtFunctionIds(), getRouter: options.getRouter, request }));
+        const ctx = rest[1];
+        const host = ctx?.props?.platform
+            ? hostContextFromProps(request, ctx.props)
+            : hostContextFromRequest(request, options.platform);
+        // Starting this isolate was the point: the platform warms a build before its
+        // first visitors, and no app code runs.
+        if (host.invoke?.kind === "warm")
+            return new Response(null, { status: 204 });
+        if (host.invoke?.kind === "describe") {
+            return Response.json(await describeApp({
+                fnIds: builtFunctionIds(),
+                descriptions: builtFunctionDescriptions(),
+                getRouter: options.getRouter,
+                request,
+                workflows: await loadedWorkflows(),
+            }));
         }
-        const host = hostContextFromRequest(request);
-        const response = await runWithHost(host, () => options.handler.fetch(request));
+        let response = await runWithHost(host, async () => host.invoke?.kind === "workflow" ? invokeWorkflow(request, host, await loadedWorkflows()) : options.handler.fetch(request));
+        const status = response.status === 500 ? pageStatus(host) : undefined;
+        if (status)
+            response = new Response(response.body, { status, headers: response.headers });
         return onBodyEnd(response, () => {
-            if (!host.runs.length || !binding)
+            const { platform } = host;
+            if (!host.runs.length || !platform)
                 return;
-            const flushed = binding.runs({ requestId: host.requestId, runs: host.runs }).catch((error) => {
+            const flushed = platform.runs({ runs: host.runs }).catch((error) => {
                 console.error("[zite] couldn't record runs", error);
             });
-            rest[1]?.waitUntil(flushed);
+            ctx?.waitUntil(flushed);
         });
     };
 }

package/dist/esm/start/types.d.ts

@@ -18,15 +18,64 @@ export type RunRecord = {
         message: string;
     };
 };
+export type AccessKind = "signedIn" | "anyone" | "webhook" | "workflow";
+/** One data, integration or email call. Who is calling is the platform's to know, never the app's to say. */
+export type PlatformCallInput = {
+    integrationId: string;
+    className: string;
+    methodName: string;
+    params: unknown;
+    /** The access decision the call ran under; the platform may narrow on it but never widens. */
+    access: AccessKind;
+};
+/**
+ * A call's answer. Errors come back as values: Workers RPC keeps a thrown
+ * error's message but drops its code.
+ */
+export type PlatformCallResult = {
+    value: unknown;
+} | {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type PlatformSession = {
+    call(call: PlatformCallInput): Promise<PlatformCallResult>;
+};
+/** What the host hands each request: its platform, already scoped to the app, build, request and user. */
+export type PlatformBinding = {
+    /** Every platform call of one request goes through one session. */
+    session(): PlatformSession | Promise<PlatformSession>;
+    /** One batch per request, after its response has ended. */
+    runs(batch: {
+        runs: RunRecord[];
+    }): Promise<void>;
+};
+export type HostMode = "live" | "preview" | "validate";
+export type HostInvoke = {
+    kind: "webhook" | "describe" | "workflow" | "warm";
+    name: string;
+};
+/** The per-request props the host dispatches with. Only the host can set them. */
+export type HostProps = {
+    platform: PlatformBinding;
+    requestId: string;
+    user: User | null;
+    mode: HostMode;
+    invoke: HostInvoke | null;
+};
 /** What the host resolved for this request. Set by the generated server entry, never by the browser. */
 export type ZiteRequestContext = {
     requestId: string;
     url: string;
     user: User | null;
-    invoke: {
-        kind: "webhook" | "describe" | "workflow";
-        name: string;
-    } | null;
+    mode: HostMode;
+    invoke: HostInvoke | null;
     /** Filled by run capture, flushed to the platform once the response ends. */
     runs: RunRecord[];
+    platform?: PlatformBinding;
+    session?: Promise<PlatformSession>;
+    /** This request's router, so a page's status can follow the error it rendered. */
+    router?: unknown;
 };

package/dist/esm/start/vite.js

@@ -2,9 +2,13 @@ import path from "node:path";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
 import viteReact from "@vitejs/plugin-react";
 import { ziteId } from "../vite/index.js";
-import { hasAppStart, renderStartInstance, renderStartServerEntry, START_INSTANCE_ENTRY, START_SERVER_ENTRY, writeIfChanged, } from "./entries.js";
-// Must match the literal in ./server.ts, which the build rewrites.
+import { factoryDescriptions } from "./descriptions.js";
+import { hasAppStart, renderStartInstance, renderStartServerEntry, renderWorkflowModules, START_INSTANCE_ENTRY, START_SERVER_ENTRY, workflowFiles, writeIfChanged, } from "./entries.js";
+// Must match the literals in ./server.ts, which the build rewrites.
 const FN_IDS_TOKEN = "__ZITE_FN_IDS__";
+const FN_DESCRIPTIONS_LITERAL = /(["'`])__ZITE_FN_DESCRIPTIONS__\1/;
+// zitejs's empty registry, which the build replaces with the app's.
+const WORKFLOW_REGISTRY = /[\\/]zitejs[\\/]dist[\\/]esm[\\/]start[\\/]workflowModules\.js$/;
 // Platform-pinned Worker settings. The deploy uses its own fixed template, so
 // these only have to match it; apps don't carry a wrangler config.
 const WORKER_COMPATIBILITY_DATE = "2026-09-25";
@@ -62,18 +66,42 @@ export function zite(options = {}) {
                 },
             };
         },
+        // Each new isolate loads the whole server bundle, so its size is cold-start
+        // time; Vite leaves SSR output unminified.
+        configEnvironment: (name, config) => name === "ssr" && options.cloudflare !== false && config.build?.minify === undefined ? { build: { minify: true } } : undefined,
     };
+    // Each server function's `description` option, by name, for the editor.
+    const descriptions = new Map();
+    const srcDir = `${path.join(appDir, "src")}${path.sep}`;
     const functionIds = {
         name: "zite:function-ids",
         apply: "build",
+        transform(code, id) {
+            if (this.environment?.config.consumer !== "server" || !id.startsWith(srcDir) || !code.includes("description"))
+                return;
+            try {
+                for (const [name, text] of factoryDescriptions(this.parse(code)))
+                    descriptions.set(name, text);
+            }
+            catch {
+                // Display-only: an unreadable module just shows no descriptions.
+            }
+        },
         generateBundle(_, bundle) {
+            const described = Object.fromEntries([...descriptions].filter(([name]) => ids.has(name)));
             for (const chunk of Object.values(bundle)) {
-                if (chunk.type === "chunk" && chunk.code.includes(FN_IDS_TOKEN)) {
+                if (chunk.type !== "chunk")
+                    continue;
+                if (chunk.code.includes(FN_IDS_TOKEN))
                     chunk.code = chunk.code.replace(FN_IDS_TOKEN, [...ids.keys()].join(","));
-                }
+                chunk.code = chunk.code.replace(FN_DESCRIPTIONS_LITERAL, () => JSON.stringify(JSON.stringify(described)));
             }
         },
     };
+    const workflowRegistry = {
+        name: "zite:workflow-registry",
+        load: (id) => (WORKFLOW_REGISTRY.test(id.split("?")[0]) ? renderWorkflowModules(appDir, workflowFiles(appDir)) : undefined),
+    };
     return [
         tanstackStart({
             // TanStack resolves these from `src/`.
@@ -110,5 +138,6 @@ export function zite(options = {}) {
         ziteId(),
         compileZitejs,
         functionIds,
+        workflowRegistry,
     ];
 }

package/dist/esm/start/workflow.d.ts

@@ -0,0 +1,36 @@
+import type { ZiteTrigger, ZiteTriggerContext } from "../backend/index.js";
+import type { ZiteSchedule } from "../schedules/index.js";
+declare const WORKFLOW: unique symbol;
+export type WorkflowConfig = {
+    /** What this workflow does, in a sentence. Shown in the editor. */
+    description?: string;
+} & ({
+    schedule: ZiteSchedule;
+    trigger?: never;
+} | {
+    trigger: ZiteTrigger;
+    schedule?: never;
+});
+/** What a workflow's handler gets. A trigger adds `trigger`, typed by the kind it declares. */
+export type WorkflowArgs<TConfig extends WorkflowConfig> = {
+    input: unknown;
+} & (TConfig extends {
+    trigger: infer T;
+} ? {
+    trigger: ZiteTriggerContext<T>;
+} : unknown);
+export type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
+    readonly [WORKFLOW]: true;
+    readonly config: TConfig;
+    readonly handler: (args: WorkflowArgs<TConfig>) => unknown;
+};
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export declare function createWorkflow<const TConfig extends WorkflowConfig>(config: TConfig): {
+    handler: (fn: (args: WorkflowArgs<TConfig>) => unknown) => Workflow<TConfig>;
+};
+export declare const isWorkflow: (value: unknown) => value is Workflow;
+export {};

package/dist/esm/start/workflow.js

@@ -0,0 +1,13 @@
+// Shared across copies of zitejs in one bundle, like the access scope.
+const WORKFLOW = Symbol.for("zitejs:workflow");
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export function createWorkflow(config) {
+    return {
+        handler: (fn) => ({ [WORKFLOW]: true, config, handler: fn }),
+    };
+}
+export const isWorkflow = (value) => typeof value === "object" && value !== null && value[WORKFLOW] === true;

package/dist/esm/start/workflow.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/start/workflow.test-d.js

@@ -0,0 +1,24 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { createWorkflow } from "./workflow.js";
+describe("createWorkflow handler args", () => {
+    it("gives a schedule no trigger", () => {
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "2026-10-10T03:00:00Z", timezone: "UTC" } }).handler((args) => {
+            expectTypeOf(args).toEqualTypeOf();
+        });
+    });
+    it("types the trigger by the kind it declares", () => {
+        createWorkflow({ trigger: { every: "5m" } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({ trigger: { integration: "slack", events: ["message.channels"] } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({ trigger: { integration: "asana" } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+    });
+    it("takes a schedule or a trigger, not both", () => {
+        // @ts-expect-error a workflow runs on one or the other
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "x", timezone: "UTC" }, trigger: { every: "5m" } });
+    });
+});

package/dist/esm/start/workflowModules.d.ts

@@ -0,0 +1 @@
+export declare const workflowModules: Record<string, () => Promise<Record<string, unknown>>>;

package/dist/esm/start/workflowModules.js

@@ -0,0 +1,3 @@
+// Replaced at build by zite() with a lazy import of every app module that
+// mentions createWorkflow. Empty wherever the plugin didn't build the app.
+export const workflowModules = {};

package/dist/esm/start/workflowRun.d.ts

@@ -0,0 +1,80 @@
+import { type Workflow } from "./workflow.js";
+export type TriggerReport = {
+    handled: string[];
+    cursor?: string;
+};
+export type WorkflowRunResult = {
+    ok: true;
+    output: unknown;
+    trigger?: TriggerReport;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    trigger?: TriggerReport;
+};
+/**
+ * Splits the platform's state out of the input. A poll or a provider delivery
+ * with a cursor gets `seen`, `handled` and `advance`. Handled ids are reported
+ * whether or not the run throws, so an item acted on is never acted on again;
+ * the staged cursor only on success. Only ids the incoming `seen` lacked are
+ * reported: billing reads an empty list as a run that found nothing new.
+ */
+export declare function triggerContext(workflow: Workflow, rawInput: unknown): {
+    input: unknown;
+    trigger?: undefined;
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+    } | {
+        headers?: undefined;
+    } | {
+        headers: {};
+    };
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers?: undefined;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers: {};
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    };
+    report: (succeeded: boolean) => TriggerReport;
+};
+/** Runs the handler in a workflow access scope: no user, and data calls allowed. */
+export declare function runWorkflow(workflow: Workflow, rawInput: unknown): Promise<WorkflowRunResult>;
+export type LoadedWorkflow = {
+    id: string;
+    file: string;
+    workflow: Workflow;
+};
+/** Every exported workflow in the app, by export name. */
+export declare function loadWorkflows(modules?: Record<string, () => Promise<Record<string, unknown>>>): Promise<LoadedWorkflow[]>;
+/** The input as the run log keeps it: a trigger's `seen` list can hold thousands of ids. */
+export declare const loggedInput: (rawInput: unknown) => unknown;