@ref0/sdk 0.0.0-stage → 0.5.0

package/dist/browse-DBqoeS-u.d.mts

@@ -0,0 +1,674 @@
+import { $t as WorkflowCallRefused, An as WorkflowText, B as GetIssueInput, Cn as WorkflowPermissions, E as ConnectionCallAnswer, En as WorkflowPullRequestOpen, I as EventRunInput, It as ThreadStage, Jt as WorkflowCall, L as ForkAnswer$1, Mn as WorkflowTrigger, Mt as StartActor$1, Nt as StartRun$1, On as WorkflowStartEnded, Qt as WorkflowCallRefusal, R as ForkCreate, Sn as WorkflowPasskeyState, St as SandboxPushAnswer, T as ConnectionCall, Tn as WorkflowPullRequestAnswer, Ut as WorkflowAction, Wt as WorkflowActionAnswer, Xt as WorkflowCallEnded, Yt as WorkflowCallAnswer, Zt as WorkflowCallInput, _ as CheckRunError, _n as WorkflowOwn, _t as SandboxExec, an as WorkflowCheckResultsAnswer, bn as WorkflowPasskeyEnded, bt as SandboxOpenAnswer, cn as WorkflowCheckStart, dn as WorkflowCheckStatesAnswer, en as WorkflowCalledState, fn as WorkflowCheckWhere, g as CheckOwn, gn as WorkflowFilters, h as CheckOn, hn as WorkflowEvent, in as WorkflowCheckResults, jn as WorkflowThreadStart, kn as WorkflowStartState, ln as WorkflowCheckStartAnswer, mn as WorkflowConnections, nn as WorkflowCheckRefusal, on as WorkflowCheckRun, pn as WorkflowComment, pt as Ref0Owned, qt as WorkflowAskClosed, rn as WorkflowCheckRefused, sn as WorkflowCheckRunEnded, tn as WorkflowCalledStateAnswer, un as WorkflowCheckStates, v as CheckRunParams, vn as WorkflowPasskeyAsk, vt as SandboxExecAnswer, xn as WorkflowPasskeyRead, xt as SandboxPush, y as CheckTreeEntry, yn as WorkflowPasskeyAsked, yt as SandboxOpen } from "./index-Dns8tCkT.mjs";
+import { z } from "zod";
+//#region src/needs.d.ts
+/**
+ * The needs the gate returns, as the SDK makes them: each an empty object, with what it needs
+ * and the stack it was made on kept beside it, out of the gate's reach. So the gate returns only
+ * needs the SDK made, and ref0 reads where each came from, the line of `gate.ts` on that stack.
+ */
+declare const needMade: unique symbol;
+declare const checkNeedMade: unique symbol;
+/** Something a change needs before it merges, as ref0 makes one for the gate to return. */
+interface Need {
+  readonly [needMade]: true;
+}
+/**
+ * A need for a check's runs, as calling its handle makes one, `e2e({ spec })`: the one need a
+ * wrapper such as `local` takes, since it holds the check's params.
+ */
+interface CheckNeed extends Need {
+  readonly [checkNeedMade]: true;
+}
+//#endregion
+//#region src/start-rules.d.ts
+/**
+ * A check's start rule, its `start`, and what it returns: `allow()`, `refuse(text)`, a called
+ * workflow's run, or a falsy value, as `&&` gives one. ref0 calls the rule in the check's own
+ * isolate before any start that isn't ref0's own makes a new run, once for each new run, with
+ * that run's params. A start that joins a run going, or is answered by one that ended, never
+ * reaches it. Any `refuse` refuses the start, with each refusal's words, and an `allow` overrides
+ * none. Otherwise a called workflow's run makes the start wait on it, and every such run must
+ * allow. A list with none of them allows.
+ */
+/**
+ * Who's starting a check: a person, an agent with its owner, or ref0's own part, such as
+ * `ref0:workflows` for a workflow's start. Its `chain` runs up to the person accountable for it:
+ * an agent's session, the attachment its credential was made under and its person; or a
+ * workflow's run and its accountable person. A person starting their own has none.
+ */
+type StartActor = (typeof StartActor$1)['Encoded'];
+/**
+ * One run of the check started in the last day, newest first, the start's own new runs judged
+ * before this one first, so a grid can't pass a limit its rule counts. Each says when it started,
+ * and its actor, `{ kind: 'hidden', id: null }` unless the starter may read where it ran or it's
+ * their own, so a limit for each actor or for the repo counts every run. A run of ref0's part is
+ * no starter's own: one workflow's run is hidden from another's start like anyone's. Where it
+ * ran, its params and how it ended are there only from a scope the starter may read, and for a
+ * thread's own rule, one `main` doesn't have, only from that thread.
+ */
+type StartRun = (typeof StartRun$1)['Encoded'];
+/** What a start rule is given, for one new run a start would make. */
+interface StartContext<Params> {
+  readonly actor: StartActor;
+  /** That run's params, as the check's `params` parsed them. */
+  readonly params: Params;
+  /** Where it would run: `main`'s tree, or the head of a thread. */
+  readonly where: WorkflowCheckWhere;
+  readonly runs: ReadonlyArray<StartRun>;
+  /**
+   * When the start is judged, in milliseconds since the epoch, as each `startedAt` is: the start's
+   * own new runs judged before this one started then. Count `runs` started past `now - window`
+   * for a limit over a window shorter than the day, since a check's code can't read the clock.
+   */
+  readonly now: number;
+}
+/** A start rule's yes: the start may make its run, unless another item of its list refuses it. */
+interface Allow {
+  readonly kind: 'allow';
+}
+/** A start rule's no, in words its starter sees: one of its code's `text` templates. */
+interface Refusal {
+  readonly kind: 'refuse';
+  readonly text: (typeof WorkflowText)['Encoded'];
+}
+/**
+ * A run of a called workflow on its input, what calling the workflow's handle makes,
+ * `approveE2e({ browser: 'webkit' })`, typed by what the workflow returns. In a start rule's list,
+ * one whose workflow returns `allow()` or `refuse(text)`: the start waits, holding no run, while
+ * ref0 runs it as the starter's person's, and its output decides the start.
+ */
+interface CalledRun<Output = unknown> {
+  readonly kind: 'workflow';
+  readonly workflow: string;
+  readonly input: (typeof WorkflowCallInput)['Encoded'];
+  /** Only its type: what the workflow returns. */
+  readonly '~output'?: Output;
+}
+/** What a called workflow a start waits on returns: `allow()` lets the start go on. */
+type StartOutput = Allow | Refusal;
+/** One item of a start rule's list: falsy ones are dropped. */
+type StartItem = Allow | Refusal | CalledRun<StartOutput> | false | null | undefined | 0 | '';
+/** A check's start rule: the list for one new run, or a promise of it. */
+type StartRule<Params> = (context: StartContext<Params>) => ReadonlyArray<StartItem> | Promise<ReadonlyArray<StartItem>>;
+/** Lets a start make its run, unless another item of the rule's list refuses it. */
+declare const allow: () => Allow;
+/** Refuses a start, in words: `` refuse(text`Ten e2e runs a day each. Reuse a result instead`) ``. */
+declare const refuse: (text: Refusal['text']) => Refusal;
+//#endregion
+//#region src/tree.d.ts
+/**
+ * A tree, as `.ref0/` code reads one: a check run's `repo`, the tree it judges, and the gate's
+ * `change.before` and `change.after`. Each read goes to ref0 over RPC, which reads it from the
+ * repo's stored objects, counts it and keeps it, so a read always answers for that one tree.
+ */
+/** A JSON value, as a check's params, output and `readJSON` hold them. */
+type JsonValue = CheckRunParams[string];
+/** Where a read of a tree looks: a path from the tree's root, with no `..`. `''` is the root, which `readTree` lists. */
+interface TreeRead {
+  readonly path: string;
+}
+/** One entry of a folder, as `readTree` answers it: its name and its kind. */
+type TreeEntry = (typeof CheckTreeEntry)['Encoded'];
+/**
+ * Reads of one tree, and of nothing else, as Cloudflare's `ArtifactsRepo.readFile` reads a repo
+ * without its `ref`, which can only be that tree. A file past the most a read holds throws: 8 MiB
+ * in a check run, 1 MiB in the gate.
+ */
+interface Tree {
+  /** The file at a path, or `null` when the tree has none there. */
+  readonly readFile: (read: TreeRead) => Promise<Blob | null>;
+  /** The file at a path, as UTF-8 text, or `null` when the tree has none there. */
+  readonly readText: (read: TreeRead) => Promise<string | null>;
+  /**
+   * The file at a path, as JSON, or `null` when the tree has none there, as for a file that
+   * holds `null`. A file that isn't JSON throws.
+   */
+  readonly readJSON: (read: TreeRead) => Promise<JsonValue>;
+  /**
+   * The folder at a path, as its entries sorted by name, or `null` when the tree has no folder
+   * there. A file there throws, as does a folder past 10,000 entries.
+   */
+  readonly readTree: (read: TreeRead) => Promise<ReadonlyArray<TreeEntry> | null>;
+}
+//#endregion
+//#region src/run-scope.d.ts
+/**
+ * What a workflow run's code is inside as it runs: the run's sink, for everything it asks of
+ * ref0, and the step whose callback it's in, if any. A check's handle reads them, so an import of
+ * a check runs it in the run that calls it.
+ */
+/**
+ * Where ref0 hears a run's actions, its calls, its forks, its sandboxes and its passkey requests,
+ * one for each at its place, its checks and the called workflows it runs. A sandbox opened in a
+ * step's attempt takes its commands and its close here too.
+ */
+interface ActionSink {
+  readonly act: (action: (typeof WorkflowAction)['Encoded']) => Promise<(typeof WorkflowActionAnswer)['Encoded']>;
+  readonly callConnection: (call: (typeof ConnectionCall)['Encoded']) => Promise<(typeof ConnectionCallAnswer)['Encoded']>;
+  /** A fork of the run's repo, made at its place in the run. */
+  readonly createFork: (fork: (typeof ForkCreate)['Encoded']) => Promise<(typeof ForkAnswer$1)['Encoded']>;
+  /** A pull request from a fork the run got, opened at its place in the run. */
+  readonly openPullRequest: (open: (typeof WorkflowPullRequestOpen)['Encoded']) => Promise<(typeof WorkflowPullRequestAnswer)['Encoded']>;
+  /** A call of a called workflow, in the step that makes it: the child run it started. */
+  readonly callWorkflow: (call: (typeof WorkflowCall)['Encoded']) => Promise<(typeof WorkflowCallAnswer)['Encoded']>;
+  /** How a child run the run called is going: going, done with its output, or failed. */
+  readonly calledState: (read: (typeof WorkflowCalledState)['Encoded']) => Promise<(typeof WorkflowCalledStateAnswer)['Encoded']>;
+  /** A start of a check's runs, in the step that starts them. */
+  readonly startChecks: (start: (typeof WorkflowCheckStart)['Encoded']) => Promise<(typeof WorkflowCheckStartAnswer)['Encoded']>;
+  /**
+   * Where a start of a check's runs that waited on called workflows stands: started, with its
+   * runs; still waiting; or refused.
+   */
+  readonly startState: (read: (typeof WorkflowStartState)['Encoded']) => Promise<(typeof WorkflowCheckStartAnswer)['Encoded']>;
+  /** Whether the check runs the run waits on have ended. */
+  readonly checkStates: (read: (typeof WorkflowCheckStates)['Encoded']) => Promise<(typeof WorkflowCheckStatesAnswer)['Encoded']>;
+  /** A page of the results of check runs the run waited on. */
+  readonly checkResults: (read: (typeof WorkflowCheckResults)['Encoded']) => Promise<(typeof WorkflowCheckResultsAnswer)['Encoded']>;
+  /** A sandbox for one attempt of the step that opens it. */
+  readonly openSandbox: (open: (typeof SandboxOpen)['Encoded']) => Promise<(typeof SandboxOpenAnswer)['Encoded']>;
+  readonly execSandbox: (exec: (typeof SandboxExec)['Encoded']) => Promise<(typeof SandboxExecAnswer)['Encoded']>;
+  readonly closeSandbox: (sandbox: string) => Promise<void>;
+  /** A push from a sandbox the run opened on a fork, at its place in the run. */
+  readonly pushSandbox: (push: (typeof SandboxPush)['Encoded']) => Promise<(typeof SandboxPushAnswer)['Encoded']>;
+  /** A passkey request, made once at its place in the run. */
+  readonly askPasskey: (ask: (typeof WorkflowPasskeyAsk)['Encoded']) => Promise<(typeof WorkflowPasskeyAsked)['Encoded']>;
+  /** Where one of the run's passkey requests stands. */
+  readonly passkeyState: (read: (typeof WorkflowPasskeyRead)['Encoded']) => Promise<(typeof WorkflowPasskeyState)['Encoded']>;
+}
+//#endregion
+//#region src/called.d.ts
+/**
+ * A called workflow's handle, as code that imports its file sees it, as a check's is: ref0's
+ * bundler swaps an import of `.ref0/workflows/<name>.ts` for `workflowHandle('<name>')`, so the
+ * workflow's code loads only in its own runs' isolates. In a start rule, calling it makes a run
+ * to wait on, `approveE2e({ browser: 'webkit' })`; in a workflow's run, `.run(step, input)` runs it
+ * as a child run of its own, waits for it in the run, and answers its output.
+ */
+/**
+ * A called workflow, as code that imports its file sees it: `import approveE2e from
+ * './approve-e2e'`. What its file exports also keeps what ref0 calls on it in its own isolate, as
+ * `WorkflowOwn` in `@ref0/contracts` says; an import of the file is a handle without it.
+ */
+interface CalledWorkflow<Input = unknown, Output = unknown> extends Partial<Ref0Owned<WorkflowOwn<WorkflowStep, ActionSink>>> {
+  /**
+   * A run of this workflow on `input`, for a start rule's list, which its output decides: a
+   * workflow that returns `allow()` or `refuse(text)`.
+   */
+  (input: Input): CalledRun<Output>;
+  /**
+   * Runs it as a child run of this run, in steps of its own, so call it outside `step.do`'s
+   * callback: it waits for the child's end in the run, and answers what the child returned, or
+   * throws `CalledRunFailed`. Each call is one child, found again by a replay; a second call of the
+   * same workflow is a child of its own.
+   */
+  readonly run: (step: WorkflowStep, input: Input) => Promise<Output>;
+}
+/**
+ * Why a call of a called workflow failed in its caller: ref0 refused it, by `why`, with what to do
+ * next, such as a chain of calls past four workflows; or the child run ended without returning,
+ * `failed`, in words that say how, such as its code throwing or its time running out. A refusal
+ * is kept as its step's result, so a replay throws it again and calls nothing.
+ */
+declare class CalledRunFailed extends Error {
+  readonly workflow: string;
+  readonly why: WorkflowCallRefusal | 'failed';
+  /** The child run, once there is one. */
+  readonly run: string | undefined;
+  constructor(workflow: string, failed: (typeof WorkflowCallRefused)['Encoded'] | {
+    readonly kind: 'failed';
+    readonly why: string;
+  }, run?: string);
+}
+//#endregion
+//#region src/workflow.d.ts
+/**
+ * `workflow()` and what a run's code reads and asks, as a repo's `.ref0/workflows/` code imports
+ * them from `@ref0/sdk`. A workflow is one of two kinds: an event workflow, with `on`, runs on
+ * its events; a called workflow, with `input` and `title`, runs only when another workflow's run
+ * calls it, and returns its output. A run is a Workflows instance: its code gets Cloudflare's
+ * `step` and acts through `ref0` inside a step, each action applied once at its place in the run.
+ * ref0 bundles its own build of this file into each workflow, whatever version the repo's
+ * lockfile holds, and checks every action outside the run's isolate, so nothing here is trusted
+ * to check anything.
+ */
+/** A trigger's event, as a run reads it. */
+type EventOf<T extends WorkflowTrigger> = Extract<(typeof WorkflowEvent)['Encoded'], {
+  readonly kind: T;
+}>;
+/**
+ * The `type` of an event ref0 sends a run, which its `step.waitForEvent` names: a thread it
+ * started moving to a stage, `thread-61-settled`; a repeat of that thread's occurrence,
+ * `thread-61-repeated`; its ask's close, `ask-ship`, by the ask's key, which `ask.run` waits for;
+ * the end of a check run it started, `check-<run>`, which a check's `run` and `wait` wait for; or
+ * the end of a child run it called, `workflow-<run>`, which a called workflow's `run` waits for;
+ * or the end of its passkey request, `passkey-<request>`, which `passkey.run` waits for; or the
+ * end of a start of a check it made that waited on called workflows, `start-<start>`, which a
+ * check's `run` and `start` wait for.
+ */
+type WaitType = `thread-${number}-${(typeof ThreadStage)['Encoded'] | 'repeated'}` | `ask-${string}` | `check-${string}` | `workflow-${string}` | `passkey-${string}` | `start-${string}`;
+/** That a check run a run started has ended: its result is read from ref0, as `wait` reads it. */
+type CheckRunEnded = (typeof WorkflowCheckRunEnded)['Encoded'];
+/** That a child run a run called has ended: how it went is read from ref0. */
+type CallEnded = (typeof WorkflowCallEnded)['Encoded'];
+/** The event a `WaitType` brings, as a run reads it. */
+type WaitedEvent<K extends WaitType> = K extends `ask-${string}` ? (typeof WorkflowAskClosed)['Encoded'] : K extends `check-${string}` ? CheckRunEnded : K extends `workflow-${string}` ? CallEnded : K extends `passkey-${string}` ? (typeof WorkflowPasskeyEnded)['Encoded'] : K extends `start-${string}` ? (typeof WorkflowStartEnded)['Encoded'] : K extends `thread-${number}-repeated` ? EventOf<'occurrence.repeated'> : EventOf<'thread.stage.moved'>;
+/** A duration as Workflows reads one: `'10 minutes'`, `'1 day'`, or milliseconds. */
+type Duration = `${number} ${'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'}${'s' | ''}` | number;
+/** How a step is tried again, and how long one attempt may take, as Workflows reads it. */
+interface StepConfig {
+  readonly retries?: {
+    readonly limit: number;
+    readonly delay: Duration;
+    readonly backoff?: 'constant' | 'linear' | 'exponential';
+  };
+  readonly timeout?: Duration;
+}
+/** What a step's callback is given: the step's name and count, and which attempt this is. */
+interface StepContext {
+  readonly step: {
+    readonly name: string;
+    readonly count: number;
+  };
+  readonly attempt: number;
+}
+/**
+ * Cloudflare's `WorkflowStep`, as a run's code gets it: each step's result is kept, so a replay
+ * of the run returns it again rather than running the step. Everything outside a step runs
+ * again on each replay.
+ */
+interface WorkflowStep {
+  do<T>(name: string, callback: (context: StepContext) => Promise<T>): Promise<T>;
+  do<T>(name: string, config: StepConfig, callback: (context: StepContext) => Promise<T>): Promise<T>;
+  sleep(name: string, duration: Duration): Promise<void>;
+  sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+  /**
+   * Waits for the event ref0 sends the run under `type`, or until `timeout`, when it throws. An
+   * event sent before the wait is reached is kept for it. ref0 sends each in order, at least
+   * once: one whose send it couldn't confirm comes again, so a move's `revision` and a repeat's
+   * `count` tell it from the next.
+   */
+  waitForEvent<const K extends WaitType>(name: string, options: {
+    readonly type: K;
+    readonly timeout?: Duration;
+  }): Promise<{
+    readonly payload: WaitedEvent<K>;
+    readonly timestamp: Date;
+    readonly type: K;
+  }>;
+}
+type Comment = Omit<(typeof WorkflowComment)['Encoded'], 'verb'>;
+type ThreadStart = Omit<(typeof WorkflowThreadStart)['Encoded'], 'verb'>;
+type ActionAnswer = (typeof WorkflowActionAnswer)['Encoded'];
+/**
+ * Where `pr.needs.add` adds: an attached workflow names the repo, since its thread may hold more.
+ */
+interface NeedAddOptions {
+  readonly repo?: string;
+}
+/** What `forks.create` takes: a key naming what the fork is for, across runs, if any. */
+type ForkOptions = Omit<(typeof ForkCreate)['Encoded'], 'place'>;
+/** The run's fork, by its number in the run, or why not, never thrown. */
+type ForkAnswer = (typeof ForkAnswer$1)['Encoded'];
+/** What `pr.open` takes: the fork as `forks.create` answered it, and the title, as `text`. */
+type PullRequestOptions = Omit<(typeof WorkflowPullRequestOpen)['Encoded'], 'place' | 'attempt'>;
+/** The pull request's number and its thread's, or why not, never thrown. */
+type PullRequestAnswer = (typeof WorkflowPullRequestAnswer)['Encoded'];
+/**
+ * What a run asks of ref0, each inside a step. ref0 answers every action, refusing one it
+ * doesn't allow, and never throws for a refusal. A step's retry gets the answers its first try
+ * got, matched by the order of its calls, so a step asks in the same order each time: a retry
+ * that asks for something else where it asked before is refused `changed`.
+ */
+interface Ref0Actions {
+  readonly comments: {
+    readonly create: (comment: Comment) => Promise<ActionAnswer>;
+  };
+  readonly threads: {
+    readonly start: (start: ThreadStart) => Promise<ActionAnswer>;
+  };
+  /**
+   * A fork of the repo the workflow lives in, from its `main`, for a workflow that declares
+   * `code: 'write'`. With a key, it's the workflow's fork for that key, which a later run gets
+   * again; without one, it's this run's own. While another running run holds the key's fork, it's
+   * refused `busy`.
+   */
+  readonly forks: {
+    readonly create: (options?: ForkOptions) => Promise<ForkAnswer>;
+  };
+  /** Pull requests in the workflow's repo: a need added to one, or one opened from a fork. */
+  readonly pr: {
+    /**
+     * Adds a need to an open pull request, for a workflow that declares `needs: 'add'`:
+     * `ref0.pr.needs.add(41, approval('dba'))`. A need already there gets this run as another
+     * source. Nothing a workflow does removes one.
+     */
+    readonly needs: {
+      readonly add: (pullRequest: number, need: Need, options?: NeedAddOptions) => Promise<ActionAnswer>;
+    };
+    /**
+     * A pull request from a fork the run got to `main`, for a workflow that declares
+     * `code: 'write'`: opened in a new thread the run starts, titled like it, which counts
+     * against the run's `threads`. A fork whose pull request is still open answers that one,
+     * which its push has already moved.
+     */
+    readonly open: (options: PullRequestOptions) => Promise<PullRequestAnswer>;
+  };
+}
+/** What a call through a connection answers: its result, or why not, never thrown. */
+type CallAnswer = (typeof ConnectionCallAnswer)['Encoded'];
+/** The connections a workflow declares, by name, with the operations it calls on each. */
+type Declared = Readonly<Record<string, ReadonlyArray<string>>>;
+/** Each operation a connection can have, by its method's name. */
+interface Operations {
+  /** A Sentry issue, by its ID: its status, level, times and counts, and never its text. */
+  readonly getIssue: (input: (typeof GetIssueInput)['Encoded']) => Promise<CallAnswer>;
+}
+/**
+ * The connections a run calls, as its workflow declared them: each by its name, with only the
+ * operations declared for it. Each is called inside a step, and answers a refusal rather than
+ * throwing one.
+ */
+type ConnectionsOf<C extends Declared> = { readonly [K in keyof C]: Pick<Operations, Extract<C[K][number], keyof Operations>>; };
+/**
+ * What an event workflow's run reads and uses: its event, the live sessions an action may name by
+ * index, and its means.
+ */
+interface WorkflowContext<T extends WorkflowTrigger, C extends Declared = {}> {
+  readonly event: EventOf<T>;
+  readonly sessions: (typeof EventRunInput)['Encoded']['sessions'];
+  readonly step: WorkflowStep;
+  readonly ref0: Ref0Actions;
+  readonly connections: ConnectionsOf<C>;
+}
+/**
+ * What a called workflow's run reads and uses: its input, as its `input` schema parsed it, and
+ * its means. It reads nothing of the event its caller answered, and acts for its caller's
+ * accountable person.
+ */
+interface CalledContext<Input, C extends Declared = {}> {
+  readonly input: Input;
+  readonly step: WorkflowStep;
+  readonly ref0: Ref0Actions;
+  readonly connections: ConnectionsOf<C>;
+}
+/**
+ * What a workflow may do, call, reach and spend, with the connections it calls as written, so its
+ * run's `connections` has each one it declared.
+ */
+type PermissionsOf<C extends Declared> = Omit<(typeof WorkflowPermissions)['Encoded'], 'connections'> & {
+  readonly connections?: C & (typeof WorkflowConnections)['Encoded'];
+};
+/** An event workflow, as its file's default export: `export default workflow({ on, … })`. */
+interface EventWorkflowSpec<T extends WorkflowTrigger, C extends Declared = {}> {
+  readonly on: ReadonlyArray<T>;
+  readonly where?: (typeof WorkflowFilters)['Encoded'];
+  readonly permissions: PermissionsOf<C>;
+  readonly description?: string;
+  /** An event workflow takes no input: a workflow with `input` is a called one, with no `on`. */
+  readonly input?: never;
+  readonly title?: never;
+  readonly run: (context: WorkflowContext<T, C>) => Promise<void>;
+}
+/** A called workflow, as its file's default export: `export default workflow({ input, title, … })`. */
+interface CalledWorkflowSpec<Input extends z.ZodObject, Output, C extends Declared = {}> {
+  /** Its input, one `z.object`, which parses each call's input before its run starts. */
+  readonly input: Input;
+  /** Its run's title, from its input, as `text`: what a list of runs and a wait on it show. */
+  readonly title: (context: {
+    readonly input: z.output<Input>;
+  }) => Text;
+  readonly permissions: PermissionsOf<C>;
+  readonly description?: string;
+  /** A called workflow answers no event: only a call runs it. */
+  readonly on?: never;
+  readonly where?: never;
+  /** Its run, which returns its output, its caller's answer, as JSON. */
+  readonly run: (context: CalledContext<z.output<Input>, C>) => Promise<Output>;
+}
+/** What a workflow's file exports keeps for ref0, in its own isolate. */
+type Own = Ref0Owned<WorkflowOwn<WorkflowStep, ActionSink>>;
+/**
+ * An event workflow, as its file exports it: nothing calls it, so it has no call and no `run`, and
+ * ref0's bundler refuses an import of its file.
+ */
+type EventWorkflow = Own;
+/** Words a run sends, as `text` makes them. */
+type Text = (typeof WorkflowText)['Encoded'];
+/**
+ * A workflow, one of two kinds. An event workflow: which events it answers, `on`, and how it
+ * narrows them, `where`. A called workflow: its `input`, its run's `title` from that, and a run
+ * that returns its output; its file's default export is its handle, which other workflows'
+ * runs call with `.run(step, input)` and a start rule calls bare. Both have their permissions,
+ * which say what they may do and call, the hosts their sandboxes may reach and their run's
+ * budgets, and a description. ref0 reads the literals, so they're written out in place, never
+ * computed; `input`, `title` and `run` are code. A workflow with both `on` and `input`, or
+ * neither, isn't one. A run that wants to stop returns.
+ */
+declare function workflow<const T extends WorkflowTrigger, const C extends Declared = {}>(spec: EventWorkflowSpec<T, C>): EventWorkflow;
+declare function workflow<const Input extends z.ZodObject, Output = void, const C extends Declared = {}>(spec: CalledWorkflowSpec<Input, Output, C>): CalledWorkflow<z.input<Input>, Output>;
+/**
+ * Words to send, as a tagged template: `` text`Started a docs thread for ${event.pullRequest}` ``.
+ * The template's own words are kept as written, and ref0 passes only templates written in the
+ * workflow's code; each value is quoted when it's shown, so nothing from an event reads as an
+ * instruction.
+ */
+declare const text: (strings: TemplateStringsArray, ...values: ReadonlyArray<string | number | boolean>) => (typeof WorkflowText)['Encoded'];
+//#endregion
+//#region src/check.d.ts
+/**
+ * `check()` and `oneOf()`, as a repo's `.ref0/checks/` code imports them from `@ref0/sdk`, and
+ * what an import of a check is. ref0 reads a check's `description`, `timeout`, `on` and `reuse`
+ * from their literals, and whether it has a start rule, and loads its code only in an isolate of its own,
+ * where it calls what `check()` keeps under `~ref0`. Anywhere else, ref0's bundler swaps an
+ * import of its file for a handle by its name, `checkHandle('unit')`, through which a workflow
+ * run's code starts the check's runs and waits for them, each start one step. In the gate, calling a
+ * handle makes a need for it: `unit()` for every part, or `e2e({ spec })` for the parts those
+ * params give.
+ */
+/** A durable step of a run, Workflows' own, which ref0 gives code as it runs it. */
+type Step = WorkflowStep;
+/**
+ * A check run a workflow run started, by ref0's reference to it, kept as a step's result: its
+ * check and its run. Only the workflow run that started it, and only its own check, waits on it.
+ */
+interface CheckRunReference {
+  readonly check: string;
+  readonly run: (typeof WorkflowCheckRun)['Encoded']['run'];
+}
+/**
+ * A duration as ref0 reads one from a file, a count and its unit from seconds to days:
+ * `'45 minutes'`, `'1 hour'`. A workflow's step takes Workflows' own `Duration`.
+ */
+type DurationText = `${number} ${'second' | 'seconds' | 'minute' | 'minutes' | 'hour' | 'hours' | 'day' | 'days'}`;
+/**
+ * How a check run ended, as its `run` says, with what it found. `neutral` says nothing either
+ * way, as a check with nothing to judge does. `needs` are what its result adds to the change it
+ * judged, `approval()` and `review()` only, at most 16: `needs: [approval('dba')]`. They count
+ * whatever the conclusion, once a version's gate takes the run.
+ */
+interface CheckResult<Output = unknown> {
+  readonly conclusion: 'success' | 'failure' | 'neutral';
+  readonly output?: Output;
+  readonly needs?: ReadonlyArray<Need>;
+}
+/** What a Standard Schema's `validate` answers: the output it took, or what's wrong with it. */
+type OutputResult<Output> = {
+  readonly value: Output;
+  readonly issues?: undefined;
+} | {
+  readonly issues: ReadonlyArray<{
+    readonly message: string;
+  }>;
+};
+/**
+ * Any Standard Schema, as zod, valibot and arktype make one: what a check's `output` takes. Its
+ * `validate` is what checks a run's output before the run is kept.
+ */
+interface OutputSchema<Output = unknown> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: Output) => OutputResult<Output> | Promise<OutputResult<Output>>;
+    readonly types?: {
+      readonly input: unknown;
+      readonly output: Output;
+    } | undefined;
+  };
+}
+/**
+ * What a check's `run` is given: its params, its step, and reads of the tree it judges. The tree's
+ * ID isn't among them: a check learns about its tree only by reading it.
+ */
+interface CheckContext<Params> {
+  readonly params: Params;
+  readonly step: Step;
+  /**
+   * The tree it judges, a file past 8 MiB throwing. ref0 keeps each read and its answer, so a run
+   * whose reads answer the same on another tree can answer for it there.
+   */
+  readonly repo: Tree;
+}
+/**
+ * What `check()` takes: ref0 reads `description`, `timeout`, `on` and `reuse` from their literals.
+ * `params`, `output`, `start` and `run` are code.
+ */
+interface CheckSpec<Params extends z.ZodObject, Output> {
+  /** One line on what the check is, at most 80 characters, shown beside its name. */
+  readonly description?: string;
+  /** Its input, one `z.object`: a field made with `oneOf` is one run for each of its values. */
+  readonly params?: Params;
+  /** What `run` returns as its output, checked before a run is kept. */
+  readonly output?: OutputSchema<Output>;
+  /**
+   * Its start rule, which ref0 calls before a start that isn't ref0's own makes a new run, once
+   * for each new run: by hand, as `ref0 run`, or from a workflow. It returns `allow()`,
+   * `refuse(text)` or falsy values, and any refusal refuses the start, in its words. ref0's own
+   * starts, for the gate and the queue's tip as `on` says, never reach it, nor does a start a run
+   * already going or ended answers. Only people, as ``({ actor }) => [actor.kind !== 'person' &&
+   * refuse(text`People start this one`)]``. Anyone may start it unless it says.
+   */
+  readonly start?: StartRule<z.output<Params>>;
+  /** For the whole check run, 45 minutes unless it says, and 6 hours at most. */
+  readonly timeout?: DurationText;
+  /**
+   * When ref0 starts it itself, each once: `'change'`, on each change before it joins `main`;
+   * `'tip'`, on the merge queue's tip before `main` moves, so it guards `main`; `'deployed'`, on
+   * what deployed. `['change', 'tip']` unless it says, and `[]` for ref0 never to start it, so only
+   * other code and people do, as its start rule lets them.
+   */
+  readonly on?: CheckOn;
+  /**
+   * Whether a result answers a start again: `true` unless it says. Then a start of the same check,
+   * params and tree gets the run that judged them, however long ago it ended, and a pass may answer
+   * a start on another tree whose reads answer the same. Write `reuse: false` for a check whose
+   * result depends on the machine or the moment, such as a benchmark, or a sandbox command that
+   * reads the clock, which is the container's real time: a start then joins a run still going, and
+   * once that has ended starts a new one, within the 64 runs a day each check, params and tree make.
+   */
+  readonly reuse?: boolean;
+  readonly run: (context: CheckContext<z.output<Params>>) => CheckResult<Output> | Promise<CheckResult<Output>>;
+}
+/**
+ * What running a check from a workflow takes: its params, a `oneOf` field left out being one
+ * run for each of its values; and `where`, `main`'s tree or the head of the event's thread, its
+ * open pull request's. Without it, the event's thread when it's on one, and `main` when not.
+ */
+interface CheckRunOptions<Params> {
+  readonly params?: Partial<Params>;
+  readonly where?: WorkflowCheckWhere;
+  /**
+   * This start's own name among concurrent starts that ask the same: up to 64 letters, digits,
+   * `.`, `_`, `:` or `-`, from a letter or digit. Workflows tells a run's steps of one name apart
+   * only by the order they're reached in, so equal asks started at once, each behind steps of
+   * its own, may get each other's runs on a replay, which differ when the head moved between
+   * them. Give each a key, such as its shard, for it to keep its own.
+   */
+  readonly key?: string;
+}
+/**
+ * How one check run a workflow started ended, with the params it ran with: its conclusion and
+ * output, if it judged, or its error, if it couldn't, never a success in its place.
+ */
+type CheckRunResult<Output = unknown> = {
+  readonly run: CheckRunReference;
+  readonly params: CheckRunParams;
+  readonly conclusion: 'success' | 'failure' | 'neutral';
+  readonly output?: Output;
+  readonly error?: undefined;
+} | {
+  readonly run: CheckRunReference;
+  readonly params: CheckRunParams;
+  readonly error: CheckRunError;
+  readonly why?: string;
+  readonly conclusion?: undefined;
+};
+/**
+ * ref0 refused a workflow's start of a check, or its read of one's runs, as `ref0 run` refuses
+ * one: `why`, what to do next, and for `busy`, when it may go. A refusal is kept as its step's
+ * result, so a replay throws it again and starts nothing. The SDK refuses a start's key or
+ * params itself, before any step, and a gate's need's params when the need is made.
+ */
+declare class CheckRunRefused extends Error {
+  readonly why: WorkflowCheckRefusal;
+  readonly nextStep: string;
+  /** When a `busy` start may go, in milliseconds since the epoch. */
+  readonly retryAt: number | undefined;
+  constructor(check: string, refused: (typeof WorkflowCheckRefused)['Encoded']);
+}
+/**
+ * A check, as code that imports its file sees it: `import unit from '../checks/unit'`. What its
+ * file exports also keeps what ref0 calls on it in its own isolate, as `CheckOwn` in
+ * `@ref0/contracts` says; an import of the file is a handle without it.
+ */
+interface Check<Params = unknown, Output = unknown> extends Partial<Ref0Owned<CheckOwn<Step>>> {
+  /**
+   * A need for it, as the gate returns one: every part, or with `params`, only the parts its
+   * expansion of them gives, as `e2e({ spec: 'apps/web/e2e/refund.spec.ts' })` asks. Wrap it in
+   * `local` for a local run to meet it too.
+   */
+  (params?: Partial<Params>): CheckNeed;
+  /**
+   * Starts its runs, one for each cell of its `oneOf` grid, and waits for each to end. A run of
+   * the same check, params and tree that's going is joined, and one that ended answers, unless the
+   * check says `reuse: false`, as `ref0 run` answers.
+   */
+  readonly run: (step: Step, options?: CheckRunOptions<Params>) => Promise<ReadonlyArray<CheckRunResult<Output>>>;
+  /** Starts its runs without waiting: a reference to each, for `wait` in a later step. */
+  readonly start: (step: Step, options?: CheckRunOptions<Params>) => Promise<{
+    readonly pending: ReadonlyArray<CheckRunReference>;
+  }>;
+  /** Waits for runs `start` started, and answers how each ended, in their order. */
+  readonly wait: (step: Step, pending: ReadonlyArray<CheckRunReference>) => Promise<ReadonlyArray<CheckRunResult<Output>>>;
+}
+/** Where a `oneOf` field's values come from: listed, or read from the tree and the params before it. */
+type OneOfValues = ReadonlyArray<string> | ((tree: string, params: Readonly<Record<string, string | undefined>>) => ReadonlyArray<string> | Promise<ReadonlyArray<string>>);
+/**
+ * A check: what it is, its params, when it runs, and the work of one run. Export it as its
+ * file's default, `.ref0/checks/<name>.ts`, named by its file.
+ */
+declare const check: <const Params extends z.ZodObject = z.ZodObject<{}>, Output = unknown>(spec: CheckSpec<Params, Output>) => Check<z.output<Params>, Output>;
+/**
+ * A param that's one check run for each of its values, and a grid with several. It's a zod 4
+ * string schema, so `.ref0/package.json` needs zod 4, the one its `z.object` comes from.
+ */
+declare const oneOf: (values: OneOfValues) => z.ZodString;
+//#endregion
+//#region src/browse.d.ts
+/**
+ * `sb.browse`: ref0's browser module, loaded beside a check that imports `@ref0/sdk/browser`, and
+ * a lease from the attempt's opener, held as its RPC stub and never settled, which settling would
+ * release. Its cleanup flushes the hooks' reports, disconnects, closes the lease and disposes it,
+ * each failure ignored and the first two bounded, so `fn`'s value or throw is what the browse
+ * answers, and a stalled step never keeps the lease from its close.
+ */
+/**
+ * The browser `sb.browse` lends a check, as the SDK's root names it: no more than its version.
+ * `@ref0/sdk/browser`, which a check that browses imports, merges Playwright's members into it,
+ * so the root's published types never name Playwright, whose own reach Workers' types.
+ */
+interface Browser {
+  readonly version: () => string;
+}
+//#endregion
+export { StartActor as $, ForkOptions as A, WorkflowContext as B, Comment as C, EventWorkflow as D, EventOf as E, StepConfig as F, CalledWorkflow as G, text as H, StepContext as I, TreeEntry as J, JsonValue as K, ThreadStart as L, PullRequestAnswer as M, PullRequestOptions as N, EventWorkflowSpec as O, Ref0Actions as P, Refusal as Q, WaitType as R, CheckRunEnded as S, Duration as T, workflow as U, WorkflowStep as V, CalledRunFailed as W, Allow as X, TreeRead as Y, CalledRun as Z, ActionAnswer as _, CheckRunOptions as a, allow as at, CalledContext as b, CheckRunResult as c, Need as ct, OneOfValues as d, StartContext as et, OutputResult as f, oneOf as g, check as h, CheckResult as i, StartRun as it, NeedAddOptions as j, ForkAnswer as k, CheckSpec as l, Step as m, Check as n, StartOutput as nt, CheckRunReference as o, refuse as ot, OutputSchema as p, Tree as q, CheckContext as r, StartRule as rt, CheckRunRefused as s, CheckNeed as st, Browser as t, StartItem as tt, DurationText as u, CallAnswer as v, ConnectionsOf as w, CalledWorkflowSpec as x, CallEnded as y, WaitedEvent as z };
+//# sourceMappingURL=browse-DBqoeS-u.d.mts.map