@ref0/sdk 0.0.0-stage → 0.5.0

package/dist/index.mjs

@@ -0,0 +1,1552 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
+//#region src/ref0-steps.ts
+/**
+* What ref0's own steps in a run share, whichever handle or leaf takes them: how each retries,
+* and the digest a step's name carries as its identity.
+*/
+/**
+* How ref0's own steps retry: what fails in one is ref0 unavailable, so five tries a second
+* apart and doubling, about half a minute, then the run ends `unavailable`, never as a failure.
+* ref0 gives up on an attempt after 40 seconds, inside its minute, so a stall fails as ref0's
+* outage and never as Workflows' own timeout.
+*/
+const ref0Steps = {
+	retries: {
+		limit: 5,
+		delay: "1 second",
+		backoff: "exponential"
+	},
+	timeout: "1 minute"
+};
+/** The first 12 hex of the SHA-256 of some text: a step's identity in its name. */
+const digestOf = async (text) => {
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))).slice(0, 6)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+//#endregion
+//#region src/rpc.ts
+/**
+* What the SDK does with what reaches a run's code over RPC: Cloudflare's `step`, and ref0's own
+* calls. Each result is copied and released, so nothing holds the call open and the invocation
+* can end.
+*/
+/** A result that came over RPC, copied and released. */
+const settle = async (call) => {
+	const result = await call;
+	try {
+		return structuredClone(result);
+	} finally {
+		result?.[Symbol.dispose]?.();
+	}
+};
+/**
+* Cloudflare's `step`, with every result settled, and each `do` callback given to `scoped`
+* first, so a run can know which step its code is in.
+*/
+const settledStep = (step, scoped = (callback) => callback) => ({
+	do: (name, ...args) => settle(args.length === 1 ? step.do(name, scoped(args[0])) : step.do(name, args[0], scoped(args[1]))),
+	sleep: (name, duration) => settle(step.sleep(name, duration)),
+	sleepUntil: (name, timestamp) => settle(step.sleepUntil(name, timestamp)),
+	waitForEvent: (name, options) => settle(step.waitForEvent(name, options))
+});
+//#endregion
+//#region src/run-scope.ts
+const inStep = new AsyncLocalStorage();
+const inRun = new AsyncLocalStorage();
+/**
+* Where a sandbox opened now goes, for `sandbox.run`: the run's sink, its place counted among the
+* step's actions, and the step's attempt. Undefined outside a workflow's step.
+*/
+const sandboxPlace = () => {
+	const at = inStep.getStore();
+	if (at === void 0) return void 0;
+	const place = {
+		step: at.step,
+		count: at.count,
+		call: at.calls
+	};
+	at.calls += 1;
+	return {
+		sink: at.sink,
+		place,
+		attempt: at.attempt
+	};
+};
+//#endregion
+//#region src/ask.ts
+/**
+* ref0 refused an ask, as it refuses an action, and never opened it; `duplicate` when the same
+* words went to the same decider within the hour; or `withdrawn`, opened, then closed with no
+* answer when its thread closed. A refusal is kept as its step's result, so a replay throws it
+* again and asks nothing.
+*/
+var AskRefused = class extends Error {
+	why;
+	constructor(key, why) {
+		super(why === "withdrawn" ? `ref0 withdrew the ask ${key}: its thread closed before anyone answered` : `ref0 refused the ask ${key}: ${why}`);
+		this.name = "AskRefused";
+		this.why = why;
+	}
+};
+/** What an ask's key may be, as `AnswerKey` in `@ref0/contracts` says. */
+const askKey = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+* How long the run waits for an ask's close: its deadline is a day at most, and ref0 sends its
+* lean at the deadline, so past a day and an hour ref0 has failed to.
+*/
+const answerTimeout = "25 hours";
+/**
+* The run's sink: refused, in words, inside a step's callback, since one step can't hold another,
+* and outside a workflow run.
+*/
+const sinkFor$1 = () => {
+	if (inStep.getStore() !== void 0) throw new Error("ask.run is a step of its own: call it outside step.do's callback");
+	const run = inRun.getStore();
+	if (run === void 0) throw new Error("ask.run asks from a workflow's run only");
+	return run.sink;
+};
+/**
+* Asks once, in a step of its own, then waits in the run for the ask's close, `ask-<key>`. The
+* ask's step name carries its key and a digest of what it asks, since Workflows tells steps of
+* one name apart only by the order they're reached in: a replay finds the same ask, and two asks
+* with one key never take each other's answers, as ref0 opens only the first.
+*/
+const run$1 = async (step, options) => {
+	const sink = sinkFor$1();
+	const key = options.key;
+	if (!askKey.test(key)) throw new AskRefused(JSON.stringify(key).slice(0, 80), "invalid");
+	const request = {
+		verb: "ask",
+		to: options.to,
+		key,
+		question: options.question,
+		answers: options.answers.map((answer) => ({
+			key: answer.key,
+			title: answer.title,
+			detail: answer.detail
+		})),
+		lean: options.lean,
+		deadline: options.deadline
+	};
+	const asked = await step.do(`ref0: ask ${key} ${await digestOf(JSON.stringify(request))}`, ref0Steps, async (context) => await settle(sink.act({
+		place: {
+			step: context.step.name,
+			count: context.step.count,
+			call: 0
+		},
+		request
+	})));
+	if (asked.kind === "duplicate") throw new AskRefused(key, "duplicate");
+	if (asked.kind === "refused") throw new AskRefused(key, asked.why);
+	const got = (await step.waitForEvent(`ref0: answer ${key}`, {
+		type: `ask-${key}`,
+		timeout: answerTimeout
+	}).catch(() => {
+		throw new Error(`ref0 sent no answer to the ask ${key} within a day and an hour`);
+	})).payload;
+	if (got.kind === "withdrawn") throw new AskRefused(key, "withdrawn");
+	const answered = got.key;
+	return got.via === "decider" ? {
+		key: answered,
+		by: got.by,
+		via: got.via,
+		at: got.at
+	} : {
+		key: answered,
+		via: got.via,
+		at: got.at
+	};
+};
+/**
+* ref0's ask: `ask.run(step, { to, key, question, answers, lean, deadline })` asks, then waits
+* in the run for `{ key, by, via, at }`, the answer, or the lean at the deadline.
+*/
+const ask = { run: run$1 };
+//#endregion
+//#region src/check-params.ts
+/**
+* How deep an object may sit in params: an expansion's answer holds them two deeper, and the run's
+* main module takes an answer whose objects sit at most 64 deep.
+*/
+const maxDepth$1 = 62;
+/** JSON with each object's keys in order, so one value always reads as the same text. */
+const sortedJson = (value) => JSON.stringify(value, (_key, each) => each instanceof Object && !Array.isArray(each) ? Object.fromEntries(Object.entries(each).toSorted(([a], [b]) => a < b ? -1 : 1)) : each);
+/**
+* Params as `CheckRunParams` holds them, in a copy of their own, or the path to the first value
+* in them that JSON can't hold as it is, `''` for the params themselves: a function, a number
+* that isn't finite, `undefined` in a list, or an object that isn't plain, such as a `Date` or a
+* `Map`. An object's `undefined` field is left out, and `-0` is `0`, as JSON writes them, so
+* what's sent is what's digested.
+*/
+const paramsOf = (value) => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return { notJson: "" };
+	const copy = objectOf(value, "", 0);
+	return "notJson" in copy ? copy : { params: copy.json };
+};
+/** A value as JSON holds it, at `at`, `depth` deep: see `paramsOf`. */
+const copyOf = (value, at, depth) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return { json: value };
+	if (typeof value === "number") return Number.isFinite(value) ? { json: value === 0 ? 0 : value } : { notJson: at };
+	if (typeof value !== "object" || depth > maxDepth$1) return { notJson: at };
+	return Array.isArray(value) ? listOf(value, at, depth) : objectOf(value, at, depth);
+};
+/** A list as JSON holds it, each item read by its index, as JSON reads one. */
+const listOf = (value, at, depth) => {
+	const items = [];
+	for (let index = 0; index < value.length; index += 1) {
+		const copy = copyOf(value[index], `${at}[${index}]`, depth + 1);
+		if ("notJson" in copy) return copy;
+		items.push(copy.json);
+	}
+	return { json: items };
+};
+/**
+* A called workflow's output as JSON holds it, in a copy of its own, or the path to the first value
+* in it that JSON can't hold as it is, `''` for the output itself, as `paramsOf` reads params.
+*/
+const outputOf = (value) => copyOf(value, "", 0);
+/** A plain object as JSON holds it, each `undefined` field left out. */
+const objectOf = (value, at, depth) => {
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return { notJson: at };
+	const fields = [];
+	for (const [key, field] of Object.entries(value)) {
+		if (field === void 0) continue;
+		const copy = copyOf(field, at === "" ? key : `${at}.${key}`, depth + 1);
+		if ("notJson" in copy) return copy;
+		fields.push([key, copy.json]);
+	}
+	return { json: Object.fromEntries(fields) };
+};
+/** The most a refusal's why may say, as `CheckExpansion` and `CalledWorkflowAnswer` keep it. */
+const whyLength$1 = 1e3;
+/**
+* The first of a zod error's issues, as one line, at its path, for a check's params or a called
+* workflow's input: `none` when it has no issue to say.
+*/
+const issueOf = (error, none) => {
+	const [issue] = error.issues;
+	if (issue === void 0) return none;
+	const at = issue.path.map(String).join(".");
+	return (at === "" ? issue.message : `${at}: ${issue.message}`).slice(0, whyLength$1);
+};
+//#endregion
+//#region src/called.ts
+/**
+* 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.
+*/
+var CalledRunFailed = class extends Error {
+	workflow;
+	why;
+	/** The child run, once there is one. */
+	run;
+	constructor(workflow, failed, run) {
+		super(failed.kind === "refused" ? `ref0 refused to call ${workflow}: ${failed.nextStep}` : `${workflow} failed: ${failed.why}`);
+		this.name = "CalledRunFailed";
+		this.workflow = workflow;
+		this.why = failed.kind === "refused" ? failed.why : "failed";
+		this.run = run;
+	}
+};
+/** The most a call's input may be, as JSON in UTF-8, as `@ref0/contracts` says. */
+const maxInputBytes = 16384;
+/** How long one wait for a child's end lasts before ref0's record is read again. */
+const waitTimeout$1 = "1 hour";
+const encoder = new TextEncoder();
+/**
+* A call's input as JSON holds it, as a check's params are, an `undefined` field left out, so
+* what's sent is what's digested: refused, before anything is sent, when JSON can't hold it as it
+* is, or past its bound.
+*/
+const inputOf = (workflow, given) => {
+	const copy = paramsOf(given);
+	if ("notJson" in copy) throw new CalledRunFailed(workflow, {
+		kind: "refused",
+		why: "invalid input",
+		nextStep: copy.notJson === "" ? "Give a called workflow's input as a plain object of JSON values" : `Give ${copy.notJson} as JSON: a string, a finite number, true, false, null, or a list or plain object of them`
+	});
+	if (encoder.encode(JSON.stringify(copy.params)).byteLength > maxInputBytes) throw new CalledRunFailed(workflow, {
+		kind: "refused",
+		why: "invalid input",
+		nextStep: `Give it at most ${maxInputBytes} bytes of input, as JSON: pass a name or a key, not the data`
+	});
+	return copy.params;
+};
+/**
+* The run's sink: refused, in words, inside a step's callback, since one step can't hold another,
+* and outside a workflow run.
+*/
+const sinkFor = (workflow) => {
+	if (inStep.getStore() !== void 0) throw new Error(`${workflow}.run is a step of its own: call it outside step.do's callback`);
+	const run = inRun.getStore();
+	if (run === void 0) throw new Error(`ref0 runs a called workflow from a workflow's run only: ${workflow}`);
+	return run.sink;
+};
+/**
+* Calls a called workflow in a step of its own, `ref0: call <name> <digest>`. Its name carries a
+* digest of the input, since Workflows tells steps of one name apart only by the order they're
+* reached in, and concurrent calls reach theirs in another order on a replay. ref0 keys the child
+* by this run, the step's name and count, and the workflow, so a replay finds the same child, a
+* replay with other input calls another, and two calls with the same input are a child each.
+* Calls alike in input may swap their children on a replay, as check starts alike do. Then each
+* round reads how the child is going, in a step, and waits for its end, an hour at a time: ref0
+* sends the end, and a wait that times out reads again, for as long as the child is going.
+*/
+const callOf = async (step, workflow, given) => {
+	const sink = sinkFor(workflow);
+	const input = inputOf(workflow, given);
+	const answer = await step.do(`ref0: call ${workflow} ${await digestOf(JSON.stringify(input))}`, ref0Steps, async (context) => await settle(sink.callWorkflow({
+		place: {
+			step: context.step.name,
+			count: context.step.count
+		},
+		workflow,
+		input
+	})));
+	if (answer.kind === "refused") throw new CalledRunFailed(workflow, answer);
+	const { run } = answer;
+	for (let round = 1;; round += 1) {
+		const state = await step.do(`ref0: called ${run} ${round}`, ref0Steps, async () => await settle(sink.calledState({ run })));
+		if (state.kind === "refused") throw new CalledRunFailed(workflow, state, run);
+		if (state.kind === "failed") throw new CalledRunFailed(workflow, state, run);
+		if (state.kind === "done") return state.output;
+		await step.waitForEvent(`ref0: wait ${run} ${round}`, {
+			type: `workflow-${run}`,
+			timeout: waitTimeout$1
+		}).catch(() => void 0);
+	}
+};
+/**
+* What an import of `.ref0/workflows/<name>.ts` is, as ref0's bundler writes it: a called
+* workflow's handle. Its bare call takes input JSON holds, as a call does.
+*/
+const workflowHandle = (workflow) => Object.assign((input) => ({
+	kind: "workflow",
+	workflow,
+	input: inputOf(workflow, input)
+}), { run: async (step, input) => await callOf(step, workflow, input) });
+//#endregion
+//#region src/attempts.ts
+const inAttempt = new AsyncLocalStorage();
+/** A check's step callback, run with its attempt's opener in scope, and given the context alone. */
+const attemptScoped = (callback) => (context, opener) => opener === void 0 ? callback(context) : inAttempt.run(opener, () => callback(context));
+/** The opener of the attempt this code runs in, or `undefined` outside a step's callback. */
+const attemptOpener = () => inAttempt.getStore();
+//#endregion
+//#region src/needs.ts
+const made = /* @__PURE__ */ new WeakMap();
+/** The most of a need's stack kept, as `maxNeedStackLength` in `@ref0/contracts` says. */
+const maxStack = 320;
+/** The frames kept: the SDK's own few, then the line of `gate.ts` that made the need. */
+const maxFrames = 6;
+/**
+* A need, made where it's called from, or on `stack` when a helper of the SDK's took its caller's
+* stack itself, so the line of `gate.ts` stays in the frames kept.
+*/
+const needFrom = (need, stack = (/* @__PURE__ */ new Error("a need")).stack ?? "") => {
+	const value = Object.freeze({});
+	made.set(value, {
+		need,
+		stack: stack.split("\n").slice(0, maxFrames).join("\n").slice(0, maxStack)
+	});
+	return value;
+};
+/**
+* What the SDK made a need as, or `undefined` for anything else the gate returned in its place:
+* what isn't an object is never a key of `made`.
+*/
+const madeOf = (value) => made.get(value);
+/**
+* Whether what the gate or a check's run returned in place of a list of needs is one: a list the
+* value's own type says holds needs keeps that type, where `Array.isArray` would make it `any[]`.
+*/
+const isList = (value) => Array.isArray(value);
+//#endregion
+//#region src/start-answers.ts
+/**
+* A start rule's answer, as `check()` keeps it for ref0 to call in the check's isolate: the rule
+* run for each new run a start would make, and what its lists say, checked, since a rule may
+* return anything.
+*/
+/** The most refusals an answer keeps, and called runs it waits on, as `@ref0/contracts` says. */
+const maxRefusals = 16;
+const maxWaits = 4;
+/** The starter, as a run their start would make shows them: their actor, without its chain. */
+const actorOf = (actor) => {
+	switch (actor.kind) {
+		case "person": return {
+			kind: "person",
+			id: actor.id
+		};
+		case "agent": return {
+			kind: "agent",
+			id: actor.id,
+			owner: actor.owner
+		};
+		case "ref0": return {
+			kind: "ref0",
+			id: actor.id
+		};
+	}
+};
+const isStrings = (value) => isList(value) && value.every((item) => typeof item === "string");
+const isAllow = (item) => typeof item === "object" && item !== null && "kind" in item && item.kind === "allow";
+/** Whether a value is `text`'s, a start rule's refusal's words or a called workflow's title. */
+const isText = (value) => typeof value === "object" && value !== null && "strings" in value && "values" in value && isStrings(value.strings) && isStrings(value.values);
+const isRefusal = (item) => typeof item === "object" && item !== null && "kind" in item && item.kind === "refuse" && "text" in item && isText(item.text);
+const isCalledRun = (item) => typeof item === "object" && item !== null && "kind" in item && item.kind === "workflow" && "workflow" in item && typeof item.workflow === "string" && "input" in item && typeof item.input === "object" && item.input !== null && !isList(item.input);
+/**
+* A start rule's answer for each new run a start would make, each judged with its own params, the
+* check's runs with the start's new runs before it, newest first, as just started, so a grid
+* can't pass a limit its rule counts, and when it's judged: refused if any list refuses, with
+* each refusal once; otherwise waiting on each called workflow's run the lists name, each
+* workflow and input once, at most `maxWaits`; otherwise allowed. Invalid, with why, when the
+* rule returns anything else, or names more runs.
+*/
+const startAnswerOf = async (rule, context) => {
+	if (rule === void 0) return { kind: "allowed" };
+	const refusals = /* @__PURE__ */ new Map();
+	const waits = /* @__PURE__ */ new Map();
+	const starting = [];
+	for (const cell of context.cells) {
+		const listed = await rule({
+			actor: context.actor,
+			params: cell,
+			where: context.where,
+			runs: [...starting, ...context.runs],
+			now: context.now
+		});
+		if (!isList(listed)) return {
+			kind: "invalid",
+			why: "It didn't return a list"
+		};
+		for (const item of listed) {
+			if (!item) continue;
+			if (isRefusal(item)) {
+				const text = {
+					strings: [...item.text.strings],
+					values: [...item.text.values]
+				};
+				refusals.set(JSON.stringify(text), text);
+			} else if (isCalledRun(item)) {
+				const run = {
+					workflow: item.workflow,
+					input: item.input
+				};
+				waits.set(sortedJson(run), run);
+			} else if (!isAllow(item)) return {
+				kind: "invalid",
+				why: "Its list holds something that isn't allow(), refuse(text), a called workflow's run or a falsy value"
+			};
+		}
+		starting.unshift({
+			startedAt: context.now,
+			actor: actorOf(context.actor),
+			where: context.where,
+			params: cell
+		});
+	}
+	if (refusals.size > 0) return {
+		kind: "refused",
+		refusals: [...refusals.values()].slice(0, maxRefusals)
+	};
+	if (waits.size > maxWaits) return {
+		kind: "invalid",
+		why: `It waits on more than ${maxWaits} called workflows' runs: name at most ${maxWaits}, each workflow and input once`
+	};
+	return waits.size === 0 ? { kind: "allowed" } : {
+		kind: "waits",
+		runs: [...waits.values()]
+	};
+};
+//#endregion
+//#region src/tree.ts
+const decoder = new TextDecoder();
+/** A tree's reads, each one of ref0's over RPC through `host`. */
+const treeOf = (host) => {
+	const bytesAt = ({ path }) => settle(host.readFile(path));
+	const textAt = async (read) => {
+		const bytes = await bytesAt(read);
+		return bytes === null ? null : decoder.decode(bytes);
+	};
+	return {
+		readFile: async (read) => {
+			const bytes = await bytesAt(read);
+			return bytes === null ? null : new Blob([bytes]);
+		},
+		readText: textAt,
+		readJSON: async (read) => {
+			const text = await textAt(read);
+			return text === null ? null : JSON.parse(text);
+		},
+		readTree: async ({ path }) => await settle(host.readTree(path))
+	};
+};
+//#endregion
+//#region src/check.ts
+/**
+* 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.
+*/
+var CheckRunRefused = class extends Error {
+	why;
+	nextStep;
+	/** When a `busy` start may go, in milliseconds since the epoch. */
+	retryAt;
+	constructor(check, refused) {
+		super(`ref0 refused ${check}: ${refused.nextStep}`);
+		this.name = "CheckRunRefused";
+		this.why = refused.why;
+		this.nextStep = refused.nextStep;
+		this.retryAt = refused.retryAt;
+	}
+};
+/** How long one wait for a run's end lasts before ref0's record is read again. */
+const waitTimeout = "1 hour";
+/**
+* The run whose code calls a handle, to start and read its runs through: refused, in words,
+* inside a step's callback, since one step can't hold another, and outside a workflow run.
+*/
+const runFor = (name) => {
+	if (inStep.getStore() !== void 0) throw new Error(`${name}.run, start and wait are steps of their own: call them outside step.do's callback`);
+	const run = inRun.getStore();
+	if (run === void 0) throw new Error(`ref0 runs a check from a workflow's code only, not yet from a check: ${name}`);
+	return run;
+};
+/** A reference to a run a start got, as a step keeps it. */
+const referenceOf = (check, run) => ({
+	check,
+	run
+});
+/** How a run ended, as a result, from what ref0's record says of it. */
+const resultOf = (reference, read) => {
+	const { params } = read;
+	if (read.state !== "ended") throw new Error(`ref0 read ${reference.run} as ${read.state} once it had ended`);
+	if (read.error !== void 0) return read.why === void 0 ? {
+		run: reference,
+		params,
+		error: read.error
+	} : {
+		run: reference,
+		params,
+		error: read.error,
+		why: read.why
+	};
+	const output = read.output;
+	return output === void 0 ? {
+		run: reference,
+		params,
+		conclusion: read.conclusion
+	} : {
+		run: reference,
+		params,
+		conclusion: read.conclusion,
+		output
+	};
+};
+/** What a start asks at its step's place, with `where` and `params` only when given. */
+const startAt = (place, check, where, params) => {
+	if (where === void 0) return params === void 0 ? {
+		place,
+		check
+	} : {
+		place,
+		check,
+		params
+	};
+	return params === void 0 ? {
+		place,
+		check,
+		where
+	} : {
+		place,
+		check,
+		where,
+		params
+	};
+};
+/** What a start's key may be: see `CheckRunOptions['key']`. */
+const startKey = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+/** What to give in place of params JSON can't hold, by the path `paramsOf` answers. */
+const jsonStep = (at) => (at === "" ? "Give a check's params as a plain object of JSON values" : `Give ${at} as JSON: a string, a finite number, true, false, null, or a list or plain object of them`).slice(0, whyLength);
+/**
+* A start's or a need's params as JSON holds them, an `undefined` field left out, so what's sent
+* is what's digested, and a field left out runs each of its `oneOf` values. Params JSON can't hold
+* as they are are refused before anything is digested or started.
+*/
+const jsonOf = (name, params) => {
+	if (params === void 0) return void 0;
+	const copy = paramsOf(params);
+	if ("notJson" in copy) throw new CheckRunRefused(name, {
+		kind: "refused",
+		why: "refused",
+		nextStep: jsonStep(copy.notJson)
+	});
+	return copy.params;
+};
+/**
+* Waits for a start that waits on called workflows to go on or be refused: each round reads how
+* it stands, in a step, then waits for its end, an hour at a time. ref0 sends its end, and a wait
+* that times out reads again, for as long as ref0's record says it waits. Each read's name carries
+* the waiting start's ID and its round, so a replay reads the same. Its runs, or its refusal,
+* thrown.
+*/
+const waitedOf = async (step, name, start) => {
+	const { sink } = runFor(name);
+	for (let round = 1;; round += 1) {
+		const state = await step.do(`ref0: waited ${name} ${start} ${round}`, ref0Steps, async () => await settle(sink.startState({
+			check: name,
+			start
+		})));
+		if (state.kind === "refused") throw new CheckRunRefused(name, state);
+		if (state.kind === "started") return state.runs;
+		await step.waitForEvent(`ref0: wait ${start} ${round}`, {
+			type: `start-${start}`,
+			timeout: waitTimeout
+		}).catch(() => void 0);
+	}
+};
+/**
+* Starts a check's runs in one step of its own. Its name carries the start's identity: its key,
+* if any, and a digest of its `where`, params and key, since Workflows tells steps of one name
+* apart only by the order they're reached in, and concurrent starts reach theirs in another order
+* on a replay. Starts that ask the same without a key are alike to Workflows, so on a replay each
+* may get the other's runs, which differ if the head moved between them: see
+* `CheckRunOptions['key']`. A start whose check's start rule makes it wait waits here, in the
+* run, until it goes on or is refused.
+*/
+const startOf = async (step, name, options = {}) => {
+	const { sink } = runFor(name);
+	const { key } = options;
+	if (key !== void 0 && !startKey.test(key)) throw new CheckRunRefused(name, {
+		kind: "refused",
+		why: "refused",
+		nextStep: `A start's key is up to 64 letters, digits, ., _, : or -, from a letter or digit, not ${JSON.stringify(key).slice(0, 80)}.`
+	});
+	const params = jsonOf(name, options.params);
+	const asked = await digestOf(sortedJson({
+		where: options.where ?? null,
+		params: params ?? {},
+		key: key ?? null
+	}));
+	const answer = await step.do(key === void 0 ? `ref0: start ${name} ${asked}` : `ref0: start ${name} ${key} ${asked}`, ref0Steps, async (context) => await settle(sink.startChecks(startAt({
+		step: context.step.name,
+		count: context.step.count
+	}, name, options.where, params))));
+	if (answer.kind === "refused") throw new CheckRunRefused(name, answer);
+	return (answer.kind === "waiting" ? await waitedOf(step, name, answer.start) : answer.runs).map((run) => referenceOf(name, run));
+};
+/** A wait's identity: the digest of its runs, sorted, one to a line. */
+const waitIdOf = async (runs) => await digestOf(runs.toSorted().join("\n"));
+/**
+* Waits until a run's end wakes this invocation, or an hour passes. Every wait on the run shares
+* one `step.waitForEvent`, since ref0 sends the end once and it wakes one waiter: one that's
+* going is joined, and one that woke stays woken. Only one that ran out its hour makes the next,
+* its count one more, so each one's name is the same on a replay, whichever wait makes it.
+*/
+const wokenBy = (step, waiters, run) => {
+	const held = waiters.get(run);
+	if (held !== void 0 && !held.timedOut) return held.woken;
+	const waiter = {
+		count: (held?.count ?? 0) + 1,
+		woken: Promise.resolve(),
+		timedOut: false
+	};
+	waiter.woken = step.waitForEvent(`ref0: wait ${run} ${waiter.count}`, {
+		type: `check-${run}`,
+		timeout: waitTimeout
+	}).then(() => void 0, () => {
+		waiter.timedOut = true;
+	});
+	waiters.set(run, waiter);
+	return waiter.woken;
+};
+/**
+* Waits for runs to end, then reads how each ended. Each round reads whether they've ended, in a
+* step, then waits for each still going, an hour at a time, as `wokenBy` says; an end ref0 sends
+* wakes the wait, and a wait that times out reads again, for as long as ref0's record says a run
+* is going. Then the results are read a page at a time, each page a step well inside Workflows'
+* 1 MiB. Each read's name carries the wait's own identity, a digest of its runs, and its round or
+* page, since Workflows tells steps of one name apart only by the order they're reached in, and
+* concurrent waits reach theirs in another order on a replay.
+*/
+const waitOf = async (step, name, pending) => {
+	const { sink, waiters } = runFor(name);
+	const foreign = pending.find((reference) => reference.check !== name);
+	if (foreign !== void 0) throw new Error(`${foreign.run} is a run of ${foreign.check}, not ${name}`);
+	const runs = [...new Set(pending.map((reference) => reference.run))].toSorted();
+	if (runs.length === 0) return [];
+	const wait = await waitIdOf(runs);
+	const missing = (found) => {
+		const unknown = runs.find((run) => !found.some((each) => each.run === run));
+		if (unknown !== void 0) throw new Error(`${unknown} isn't a run of ${name} that this workflow run started`);
+	};
+	for (let round = 1;; round += 1) {
+		const states = await step.do(`ref0: states ${name} ${wait} ${round}`, ref0Steps, async () => await settle(sink.checkStates({
+			check: name,
+			runs
+		})));
+		if (states.kind === "refused") throw new CheckRunRefused(name, states);
+		missing(states.runs);
+		const going = states.runs.filter((run) => !run.ended);
+		if (going.length === 0) break;
+		await Promise.all(going.map(async ({ run }) => await wokenBy(step, waiters, run)));
+	}
+	const read = [];
+	for (let from = 0, page = 1; from !== void 0; page += 1) {
+		const at = from;
+		const got = await step.do(`ref0: results ${name} ${wait} ${page}`, ref0Steps, async () => await settle(sink.checkResults({
+			check: name,
+			runs,
+			from: at
+		})));
+		if (got.kind === "refused") throw new CheckRunRefused(name, got);
+		read.push(...got.runs);
+		from = got.next;
+	}
+	missing(read);
+	return pending.map((reference) => {
+		const found = read.find((run) => run.run === reference.run);
+		if (found === void 0) throw new Error(`${reference.run} wasn't read`);
+		return resultOf(reference, found);
+	});
+};
+/**
+* What an import of `.ref0/checks/<name>.ts` is, as ref0's bundler writes it; with `project`,
+* an import of `ref0:project/checks/<name>`, one of the project repo's checks, which a gate needs
+* and nothing runs from here yet.
+*/
+const checkHandle = (name, source) => {
+	const notYet = () => {
+		throw new Error(`ref0 can't run the project's check ${name} from here yet`);
+	};
+	const runs = source === "project" ? {
+		run: notYet,
+		start: notYet,
+		wait: notYet
+	} : {
+		run: async (step, options) => await waitOf(step, name, await startOf(step, name, options)),
+		start: async (step, options) => ({ pending: await startOf(step, name, options) }),
+		wait: async (step, pending) => await waitOf(step, name, pending)
+	};
+	const from = source === "project" ? { source } : {};
+	return Object.assign((given) => {
+		const params = jsonOf(name, given);
+		return needFrom(params === void 0 ? {
+			kind: "check",
+			name,
+			...from
+		} : {
+			kind: "check",
+			name,
+			params,
+			...from
+		});
+	}, runs);
+};
+/** Each `oneOf` field's values, by its schema: the SDK's own, so no zod registry is needed. */
+const marks = /* @__PURE__ */ new WeakMap();
+/**
+* A field's `oneOf` mark: its own, or that of the schema it was cloned from, as `.min()` clones
+* one, or of the schema it wraps, as `.optional()` and `.transform()` wrap one. It reads zod's
+* own links, so a check reaches no zod it doesn't import.
+*/
+const markOf = (field) => {
+	const mark = marks.get(field);
+	if (mark !== void 0) return mark;
+	const { def, parent } = field._zod;
+	const inner = "innerType" in def ? def.innerType : "in" in def ? def.in : parent;
+	return inner === void 0 ? void 0 : markOf(inner);
+};
+/** The most runs one start may ask for, as `maxCheckRunsPerStart` in `@ref0/contracts` says. */
+const maxRuns = 256;
+/** What a refusal may say, as `CheckExpansion` in `@ref0/contracts` keeps it. */
+const whyLength = 1e3;
+/** A start's runs, by its params' `oneOf` fields: see `CheckOwn['expand']`. */
+const expansionOf = async (params, asked) => {
+	const fields = params?.shape ?? {};
+	const unknown = Object.keys(asked).filter((key) => !Object.hasOwn(fields, key));
+	if (unknown.length > 0) return { refused: `It has no param ${unknown.join(", ")}`.slice(0, whyLength) };
+	let cells = [asked];
+	for (const [key, field] of Object.entries(fields)) {
+		const mark = Object.hasOwn(asked, key) ? void 0 : markOf(field);
+		if (mark === void 0) continue;
+		if ("computed" in mark) return { refused: `${key}'s values are read from the tree, which ref0 doesn't do yet: give ${key}` };
+		const distinct = [...new Set(mark.listed)];
+		if (distinct.length === 0) return { refused: `${key} has no values` };
+		if (cells.length * distinct.length > maxRuns) return { refused: `It asks for more than ${maxRuns} runs: give ${key}, or another param` };
+		cells = cells.flatMap((cell) => distinct.map((value) => ({
+			...cell,
+			[key]: value
+		})));
+	}
+	if (params === void 0) return { runs: cells };
+	const runs = [];
+	for (const cell of cells) {
+		const parsed = await params.safeParseAsync(cell);
+		if (!parsed.success) return { refused: issueOf(parsed.error, "Its params are invalid") };
+		const copy = paramsOf(parsed.data);
+		if ("notJson" in copy) return { refused: (copy.notJson === "" ? "Its params aren't JSON once parsed" : `Its params aren't JSON once parsed: ${copy.notJson} isn't`).slice(0, whyLength) };
+		runs.push(copy.params);
+	}
+	return { runs };
+};
+/** The most needs one run's result may add, as `maxResultNeeds` in `@ref0/contracts` says. */
+const maxResultNeeds = 16;
+/**
+* A run's result needs as ref0 keeps them, or why they can't be: each one the SDK made, and none a
+* check's, since a result can't ask for runs mid-version.
+*/
+const resultNeedsOf = (needs) => {
+	if (needs === void 0) return { needs: [] };
+	if (!isList(needs)) return { why: "Its needs aren't a list" };
+	if (needs.length > maxResultNeeds) return { why: `Its result adds past ${maxResultNeeds} needs` };
+	const kept = [];
+	for (const need of needs) {
+		const made = madeOf(need)?.need;
+		if (made === void 0) return { why: "Its needs hold something that isn't one: return approval() and review()" };
+		if (made.kind === "check" || made.kind === "checks") return { why: `Its result can't need ${made.kind === "check" ? `the check ${made.name}` : "checks"}: return approval() and review()` };
+		kept.push(made);
+	}
+	return { needs: kept };
+};
+/** One run of a check: see `CheckOwn['run']`. */
+const runOf$1 = (spec) => async (input, step, host) => {
+	const params = input.params;
+	const result = await spec.run({
+		params,
+		step: settledStep(step, attemptScoped),
+		repo: treeOf(host)
+	});
+	const checked = spec.output === void 0 ? {
+		value: result.output,
+		issues: void 0
+	} : await spec.output["~standard"].validate(result.output);
+	if (checked.issues !== void 0) return {
+		error: "invalid output",
+		why: checked.issues.map((issue) => issue.message).join("; ").slice(0, whyLength)
+	};
+	const read = resultNeedsOf(result.needs);
+	if ("why" in read) return {
+		error: "invalid output",
+		why: read.why
+	};
+	const { needs } = read;
+	const judged = needs.length === 0 ? { conclusion: result.conclusion } : {
+		conclusion: result.conclusion,
+		needs
+	};
+	if (checked.value === void 0) return judged;
+	return {
+		...judged,
+		output: checked.value
+	};
+};
+/**
+* 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.
+*/
+const check = (spec) => Object.assign(checkHandle("this check"), { "~ref0": {
+	version: 1,
+	expand: async (asked) => await expansionOf(spec.params, asked),
+	start: async (context) => await startAnswerOf(spec.start, context),
+	run: runOf$1(spec)
+} });
+/**
+* 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.
+*/
+const oneOf = (values) => {
+	const schema = z.string();
+	marks.set(schema, Array.isArray(values) ? { listed: values } : { computed: true });
+	return schema;
+};
+//#endregion
+//#region src/path-patterns.ts
+const segmentOf = (text) => {
+	if (text === "**") return { kind: "any" };
+	if (text.includes("?")) return {
+		kind: "wild",
+		chars: Array.from(text),
+		parts: void 0
+	};
+	return text.includes("*") ? {
+		kind: "wild",
+		chars: Array.from(text),
+		parts: text.split("*")
+	} : {
+		kind: "literal",
+		text
+	};
+};
+/**
+* Whether a segment matches the literals between a pattern's stars: the first at its start, the
+* last at its end, and each between them in order, the earliest place each fits leaving the
+* most room for the rest.
+*/
+const partsMatch = (parts, segment) => {
+	const head = parts[0] ?? "";
+	const tail = parts.at(-1) ?? "";
+	const end = segment.length - tail.length;
+	if (end < head.length || !segment.startsWith(head) || !segment.endsWith(tail)) return false;
+	let at = head.length;
+	for (const part of parts.slice(1, -1)) {
+		const found = segment.indexOf(part, at);
+		if (found === -1 || found + part.length > end) return false;
+		at = found + part.length;
+	}
+	return true;
+};
+/**
+* Whether one segment matches a wildcard segment's characters, `*` and `?` within it: in time
+* linear in each, since a `*` reaches everything from the first place it can start.
+*/
+const wildMatches = (pattern, segment) => {
+	let reach = new Uint8Array(segment.length + 1);
+	let next = new Uint8Array(segment.length + 1);
+	reach[0] = 1;
+	for (const character of pattern) {
+		next.fill(0);
+		if (character === "*") {
+			const first = reach.indexOf(1);
+			if (first !== -1) next.fill(1, first);
+		} else for (let j = 0; j < segment.length; j++) if (reach[j] === 1 && (character === "?" || character === segment[j])) next[j + 1] = 1;
+		[reach, next] = [next, reach];
+		if (reach.indexOf(1) === -1) return false;
+	}
+	return reach[segment.length] === 1;
+};
+/** Whether one segment matches a wildcard segment. */
+const wildSegmentMatches = (wild, segment) => wild.parts === void 0 ? wildMatches(wild.chars, Array.from(segment)) : partsMatch(wild.parts, segment);
+/** Whether a path's segments match a compiled pattern's. */
+const segmentsMatch = (pattern, path) => {
+	const width = path.length + 1;
+	const tried = new Uint8Array((pattern.length + 1) * width);
+	const from = (p, s) => {
+		const kept = tried[p * width + s];
+		if (kept !== 0) return kept === 1;
+		const segment = pattern[p];
+		const here = path[s];
+		let matched;
+		if (segment === void 0) matched = s === path.length;
+		else if (segment.kind === "any") matched = from(p + 1, s) || s < path.length && from(p, s + 1);
+		else if (here === void 0) matched = false;
+		else if (segment.kind === "literal") matched = segment.text === here && from(p + 1, s + 1);
+		else matched = wildSegmentMatches(segment, here) && from(p + 1, s + 1);
+		tried[p * width + s] = matched ? 1 : 2;
+		return matched;
+	};
+	return from(0, 0);
+};
+/**
+* Whether a path matches any of the patterns, each compiled once. The shapes gates use most for
+* a stack's files are read straight from the path's segments, as the general match would read
+* them: `**\/name` is its last segment, `**\/name/**` any segment, and `**\/name/**\/*` any
+* folder it's in.
+*/
+const pathMatcher = (patterns) => {
+	const names = /* @__PURE__ */ new Set();
+	const segments = /* @__PURE__ */ new Set();
+	const folders = /* @__PURE__ */ new Set();
+	const lastWild = [];
+	const general = [];
+	for (const pattern of patterns) {
+		const compiled = pattern.split("/").map(segmentOf);
+		const [first, second, third, fourth] = compiled;
+		const anyFirst = first?.kind === "any";
+		if (anyFirst && compiled.length === 2 && second?.kind === "literal") names.add(second.text);
+		else if (anyFirst && compiled.length === 2 && second?.kind === "wild") lastWild.push(second);
+		else if (anyFirst && compiled.length === 3 && second?.kind === "literal" && third?.kind === "any") segments.add(second.text);
+		else if (anyFirst && compiled.length === 4 && second?.kind === "literal" && third?.kind === "any" && fourth?.kind === "wild" && fourth.chars.length === 1 && fourth.chars[0] === "*") folders.add(second.text);
+		else general.push(compiled);
+	}
+	return (path) => {
+		const parts = path.split("/");
+		const last = parts.length - 1;
+		const name = parts[last] ?? "";
+		return names.has(name) || parts.some((part, index) => segments.has(part) || index < last && folders.has(part)) || lastWild.some((wild) => wildSegmentMatches(wild, name)) || general.some((pattern) => segmentsMatch(pattern, parts));
+	};
+};
+//#endregion
+//#region src/gate.ts
+/** What the gate is given, from the version's summary and the hosts of the change's trees. */
+const contextOf = (summary, trees) => {
+	const paths = summary.files.flatMap((file) => file.from === null ? [file.path] : [file.path, file.from]);
+	return {
+		change: {
+			files: summary.files,
+			complete: summary.complete,
+			permissions: [...new Set(summary.files.flatMap((file) => file.permissions))].sort(),
+			lines: {
+				added: summary.size.added,
+				removed: summary.size.deleted
+			},
+			touches: (...patterns) => paths.some(pathMatcher(patterns)),
+			only: (...patterns) => paths.length > 0 && paths.every(pathMatcher(patterns)),
+			author: summary.author,
+			before: treeOf(trees.before),
+			after: treeOf(trees.after)
+		},
+		plan: summary.plan
+	};
+};
+/** The most needs the gate may return, as `maxGateNeeds` in `@ref0/contracts` says. */
+const maxNeeds = 128;
+/** How deep the gate's lists may nest. */
+const maxDepth = 16;
+/** What the gate returned, flattened: each need the SDK made, or a throw for anything else. */
+const flatten = (returned) => {
+	const needs = [];
+	const walk = (list, depth) => {
+		if (!isList(list)) throw new TypeError("The gate returns a list of needs");
+		if (depth > maxDepth) throw new TypeError(`The gate's lists nest past ${maxDepth} deep`);
+		for (const item of list) {
+			if (item === false || item === null || item === void 0) continue;
+			if (isList(item)) {
+				walk(item, depth + 1);
+				continue;
+			}
+			const made = madeOf(item);
+			if (made === void 0) throw new TypeError("The gate returned something that isn't a need: return checks, approval() and review()");
+			if (needs.length >= maxNeeds) throw new TypeError(`The gate returned past ${maxNeeds} needs`);
+			needs.push({
+				need: made.need,
+				stack: made.stack
+			});
+		}
+	};
+	walk(returned, 0);
+	return needs;
+};
+/** The gate: given a change, what it needs. Export it as `.ref0/gate.ts`'s default. */
+const gate = (decide) => ({
+	decide,
+	"~ref0": {
+		version: 1,
+		needs: async (input, trees) => ({ needs: flatten(await decide(contextOf(input.summary, trees))) })
+	}
+});
+/**
+* An approval from someone holding that repo permission: `approval('billing')`. Admins hold every
+* permission.
+*/
+const approval = (permission) => needFrom({
+	kind: "permission",
+	name: permission
+});
+/** A whole review covering the change, with no blocking finding open. ref0's floor has one. */
+const review = () => needFrom({ kind: "review" });
+/**
+* A check's need that a local run meets too: `local(unit())`. A run of the same check-run
+* identity, the check's code, its params and the version's expected tree, run with `ref0 run
+* --local` on an attached machine of the thread's and reported, meets each of its parts, and ref0
+* runs none of them on the change, unless another need for the part doesn't take local. ref0's
+* failure of a part still stands, the merge queue's tip still runs the check as ref0's own, and
+* when ref0's runs of a local success's identity fail twice, its machine stops answering the
+* check until an admin restores it. It takes a check's need, never a check or another need.
+*/
+const local = (need) => {
+	const made = madeOf(need)?.need;
+	if (made?.kind !== "check") throw new TypeError("local() wraps a check's need, as local(unit()) does: never approval(), review() or a check");
+	return needFrom({
+		...made,
+		local: true
+	});
+};
+//#endregion
+//#region src/passkey.ts
+/**
+* ref0 asked nobody, and why, as `PasskeyRefusal` in `@ref0/contracts` says. A refusal is
+* kept as its step's result, so a replay throws it again and asks nobody; `agent` is refused
+* before any step.
+*/
+var PasskeyRequestRefused = class extends Error {
+	why;
+	constructor(why) {
+		super(`ref0 asked nobody for a passkey: ${why}`);
+		this.name = "PasskeyRequestRefused";
+		this.why = why;
+	}
+};
+/** The longest one wait for a request's end lasts before ref0's record is read again. */
+const longestWait = 36e5;
+/** What a step's code asks, as a digest: who, the statement and the deadline. */
+const askedDigest = async (options) => await digestOf(JSON.stringify([
+	options.from,
+	options.statement.strings,
+	options.statement.values,
+	options.deadline
+]));
+/**
+* The run whose code asks, refused in words inside a step's callback, since one step can't hold
+* another, and outside a workflow run.
+*/
+const runOf = () => {
+	if (inStep.getStore() !== void 0) throw new Error("passkey.run is a step of its own: call it outside step.do's callback");
+	const run = inRun.getStore();
+	if (run === void 0) throw new Error("ref0 asks for a passkey from a workflow's code only");
+	return run;
+};
+/** What `passkey.run` answers, from ref0's read of a request that ended. */
+const answerOf$1 = (answered) => {
+	const answer = {
+		approved: answered.approved,
+		at: answered.at
+	};
+	if (answered.by !== void 0) answer.by = answered.by;
+	return answer;
+};
+/**
+* Asks for a passkey's yes to `statement`, then waits for the answer. The request is one step,
+* named `ref0: passkey` and told from the run's others by its count, so it's reached in the order
+* the code asks: a replay waits on the same request, and one that asks something else there
+* throws `changed`. Then each round reads the request in a step and waits for its end, until its
+* deadline or an hour, whichever is first, and a wait that times out reads again.
+*/
+const run = async (step, options) => {
+	const { sink } = runOf();
+	const { from } = options;
+	if (from !== "accountable" && "agent" in from) throw new PasskeyRequestRefused("agent");
+	const asking = step.do("ref0: passkey", ref0Steps, async (context) => ({
+		...await settle(sink.askPasskey({
+			place: {
+				step: context.step.name,
+				count: context.step.count
+			},
+			from,
+			statement: options.statement,
+			deadline: options.deadline
+		})),
+		asked: await askedDigest(options)
+	}));
+	const [answer, asked] = await Promise.all([asking, askedDigest(options)]);
+	if (answer.asked !== asked) throw new PasskeyRequestRefused("changed");
+	if (answer.kind === "refused") throw new PasskeyRequestRefused(answer.why);
+	for (let round = 1;; round += 1) {
+		const state = await step.do(`ref0: passkey ${answer.request} ${round}`, ref0Steps, async () => await settle(sink.passkeyState({ request: answer.request })));
+		if (state.state === "refused") throw new Error(`ref0 read ${answer.request} as ${state.why}`);
+		if (state.state === "answered") return answerOf$1(state);
+		const timeout = Math.min(Math.max(state.expiresAt - state.readAt + 1e3, 1e3), longestWait);
+		await step.waitForEvent(`ref0: passkey wait ${answer.request} ${round}`, {
+			type: `passkey-${answer.request}`,
+			timeout
+		}).catch(() => {});
+	}
+};
+/**
+* A check's need whose result counts only once a person said yes to it with their passkey:
+* `passkey.check(local(e2e()))`, or `passkey.check(e2e(), { from: { permission: 'qa' } })` to ask
+* someone else. For each part, ref0 asks for a yes to a statement that names the run that meets it,
+* its check-run identity, its conclusion and its outputs' hash, and the part waits for that yes. A
+* newer run that counts asks again. A no or the request's day ending waits for a newer local run;
+* on a run of ref0's, or from a person who can't be asked, the check needs an admin's override.
+* When ref0's runs of an identity someone said yes over fail twice, their yes stops answering the
+* check until an admin restores them. It takes a check's need, never a check or another need, and wraps it
+* once, before or after `local`.
+*/
+const check$1 = (need, options = {}) => {
+	const made = madeOf(need)?.need;
+	if (made?.kind !== "check") throw new TypeError("passkey.check() wraps a check's need, as passkey.check(unit()) does: never approval(), review() or a check");
+	if (made.passkey !== void 0) throw new TypeError("passkey.check() wraps a need once: return another need to ask someone else too");
+	return needFrom({
+		...made,
+		passkey: { from: options.from ?? "accountable" }
+	});
+};
+const passkey = {
+	run,
+	check: check$1
+};
+//#endregion
+//#region src/browse.ts
+/**
+* Where ref0 loads its browser module, beside the prelude, for a check that imports it: the path
+* contracts names, written here since the SDK's root takes only types from contracts.
+*/
+const browserModule = "/ref0-browser.js";
+const loaded = async () => {
+	try {
+		return await import(
+			/* @vite-ignore */
+			browserModule
+);
+	} catch {
+		throw new Error("This check doesn't import @ref0/sdk/browser: import `expect` from @ref0/sdk/browser");
+	}
+};
+/** The most the reports' flush and the disconnect may each take, which only help the close. */
+const browseCleanupMs = 5e3;
+/**
+* Runs a cleanup step, ignoring its failure, and, given `ms`, giving up on it after that long, so
+* a stalled step holds up none after it.
+*/
+const quietly = async (step, ms) => {
+	let timer;
+	try {
+		const stalled = ms === void 0 ? [] : [new Promise((given) => {
+			timer = setTimeout(given, ms);
+		})];
+		await Promise.race([step(), ...stalled]);
+	} catch {} finally {
+		clearTimeout(timer);
+	}
+};
+/**
+* Lends `fn` a browser for `session`, and closes it however `fn` ends: the reports flushed and the
+* browser disconnected, each within `cleanupMs`, then the lease's close, durable in ref0, always
+* asked, and the lease disposed after it whatever happens.
+*/
+const browseWith = async (opener, session, fn, load = loaded, cleanupMs = browseCleanupMs) => {
+	const browser = await load();
+	const lease = await opener.browse(session);
+	try {
+		const opened = await browser.__ref0Open(lease);
+		try {
+			return await fn(opened.browser);
+		} finally {
+			await quietly(opened.flush, cleanupMs);
+			await quietly(opened.disconnect, cleanupMs);
+		}
+	} finally {
+		try {
+			await quietly(async () => await lease.close());
+		} finally {
+			lease[Symbol.dispose]?.();
+		}
+	}
+};
+//#endregion
+//#region src/sandbox.ts
+/** A sandbox step's timeout and retries unless its options say. */
+const defaultTimeout = "10 minutes";
+const defaultRetries = 2;
+const durationUnits = /* @__PURE__ */ new Map([
+	["second", 1e3],
+	["minute", 6e4],
+	["hour", 36e5]
+]);
+/** A duration's milliseconds: `'10 minutes'` is 600,000. */
+const millisOf = (text) => {
+	const match = /^(\d+(?:\.\d+)?) (second|minute|hour)s?$/.exec(text);
+	const unit = match?.[2] === void 0 ? void 0 : durationUnits.get(match[2]);
+	if (match === null || unit === void 0) throw new Error(`Not a duration: ${text}`);
+	return Math.ceil(Number(match[1]) * unit);
+};
+/**
+* A command's answer in the sandbox, or the failure of one that gave none, and its push. It
+* serves nothing.
+*/
+const execIn = (at, sandbox) => ({
+	push: async ({ message }) => {
+		const place = sandboxPlace()?.place;
+		if (place === void 0) throw new Error("A sandbox pushes only inside its step");
+		return await settle(at.sink.pushSandbox({
+			place,
+			attempt: at.attempt,
+			sandbox,
+			message
+		}));
+	},
+	exec: async (command, options = {}) => {
+		const answer = await settle(at.sink.execSandbox({
+			sandbox,
+			command,
+			...options.cwd !== void 0 && { cwd: options.cwd },
+			...options.env !== void 0 && { env: { ...options.env } },
+			...options.timeout !== void 0 && { timeoutMs: millisOf(options.timeout) }
+		}));
+		if (answer.kind === "failed") throw new Error(`The command gave no answer, ${answer.why}: ${answer.message}`);
+		return {
+			exitCode: answer.exitCode,
+			stdout: answer.stdout,
+			stderr: answer.stderr,
+			startedAt: answer.startedAt,
+			durationMs: answer.durationMs
+		};
+	},
+	serve: async () => await Promise.reject(/* @__PURE__ */ new Error("A workflow's sandbox serves nothing: `serve` is for checks")),
+	browse: async () => await Promise.reject(/* @__PURE__ */ new Error("A workflow's sandbox browses nothing: `browse` is for checks"))
+});
+/**
+* Opens a workflow's sandbox for this attempt of its step, gives it to `work`, and closes it when
+* `work` ends or throws. A step's retry opens a new one. A refusal throws, since `work` has
+* nothing to run in.
+*/
+const runInWorkflow = async (at, sandbox, options, work) => {
+	if (options.paths !== void 0) throw new Error("A workflow's sandbox holds the whole tree: `paths` is for checks");
+	if (options.tree === void 0) throw new Error("A workflow's sandbox needs a tree: `'main'` or a fork's answer");
+	const opened = await settle(at.sink.openSandbox({
+		place: at.place,
+		attempt: at.attempt,
+		sandbox,
+		tree: options.tree,
+		...options.size !== void 0 && { size: options.size },
+		timeoutMs: millisOf(options.timeout ?? defaultTimeout)
+	}));
+	if (opened.kind === "refused") throw new Error(`ref0 refused the sandbox ${sandbox}: ${opened.why}`);
+	try {
+		return await work(execIn(at, opened.sandbox));
+	} finally {
+		await settle(at.sink.closeSandbox(opened.sandbox));
+	}
+};
+/**
+* What an import of `.ref0/sandboxes/<name>.ts` is, as ref0's bundler writes it. Its `run` is
+* `step.do(name, { timeout, retries })` around opening the sandbox once for each attempt, `work`,
+* and closing it in `finally`: a replay returns the step's kept output and opens nothing. In a
+* workflow's step, ref0's Worker opens it, through the run's sink.
+*/
+const sandboxHandle = (name) => {
+	const run = async (step, stepName, options, work) => await step.do(stepName, {
+		timeout: options.timeout ?? defaultTimeout,
+		retries: {
+			limit: options.retries ?? defaultRetries,
+			delay: "10 seconds",
+			backoff: "exponential"
+		}
+	}, async () => {
+		const at = sandboxPlace();
+		if (at !== void 0) return await runInWorkflow(at, name, options, work);
+		const opener = attemptOpener();
+		if (opener === void 0) throw new Error(`${name} opens only in a step of a check run`);
+		if (options.tree !== void 0) throw new Error(`${name} opens in its check run's own tree: \`tree\` is for workflows`);
+		const asked = { sandbox: name };
+		if (options.paths !== void 0) asked.paths = [...options.paths];
+		if (options.size !== void 0) asked.size = options.size;
+		const { session } = await settle(opener.open(asked));
+		try {
+			return await work({
+				exec: async (command, given = {}) => await settle(opener.exec(session, command, given)),
+				push: async () => {
+					throw new Error("A check's sandbox pushes nothing: `push` is a workflow's");
+				},
+				serve: async (command, given) => await settle(opener.serve(session, command, given)),
+				browse: async (fn) => await browseWith(opener, session, fn)
+			});
+		} finally {
+			await settle(opener.close(session)).catch(() => void 0);
+		}
+	});
+	return { run };
+};
+/**
+* A sandbox: its image, size, cached setup, and the hosts setup may reach. Export it as its
+* file's default, `.ref0/sandboxes/<name>.ts`, named by its file.
+*/
+const sandbox = (_spec) => sandboxHandle("this sandbox");
+//#endregion
+//#region src/start-rules.ts
+/** Lets a start make its run, unless another item of the rule's list refuses it. */
+const allow = () => ({ kind: "allow" });
+/** Refuses a start, in words: `` refuse(text`Ten e2e runs a day each. Reuse a result instead`) ``. */
+const refuse = (text) => ({
+	kind: "refuse",
+	text
+});
+//#endregion
+//#region src/workflow.ts
+/**
+* Cloudflare's `step`, with each `do` callback run in a scope that knows its step and attempt,
+* so an action inside it gets its place.
+*/
+const durableStep = (step, sink) => settledStep(step, (callback) => (context) => inStep.run({
+	step: context.step.name,
+	count: context.step.count,
+	attempt: context.attempt,
+	sink,
+	calls: 0,
+	connectionCalls: 0
+}, () => callback(context)));
+/**
+* ref0's actions, each sent with its place, or refused at once outside a step. A fork's place is
+* counted among the step's actions, in the order they're asked.
+*/
+const actionsOf = (sink) => {
+	const placeOf = () => {
+		const at = inStep.getStore();
+		if (at === void 0) throw new Error("ref0's actions run inside a step, in step.do's callback, since a run's code outside one runs again on each replay");
+		const place = {
+			step: at.step,
+			count: at.count,
+			call: at.calls
+		};
+		at.calls += 1;
+		return place;
+	};
+	const send = (request) => settle(sink.act({
+		place: placeOf(),
+		request
+	}));
+	return {
+		comments: { create: (comment) => send({
+			verb: "comment",
+			...comment
+		}) },
+		threads: { start: (start) => send({
+			verb: "thread.start",
+			...start
+		}) },
+		forks: { create: (options = {}) => settle(sink.createFork({
+			place: placeOf(),
+			...options
+		})) },
+		pr: {
+			needs: { add: (pullRequest, need, options = {}) => {
+				const made = madeOf(need);
+				if (made === void 0) throw new TypeError("pr.needs.add takes a need: a check's handle called, approval() or review()");
+				return send({
+					verb: "pr.needs.add",
+					pullRequest,
+					need: made.need,
+					...options
+				});
+			} },
+			open: (options) => {
+				const attempt = inStep.getStore()?.attempt ?? 1;
+				return settle(sink.openPullRequest({
+					place: placeOf(),
+					attempt,
+					...options
+				}));
+			}
+		}
+	};
+};
+/** What a call came to, in a few words, for the run's trace. */
+const callWords = (answer) => answer.kind === "answered" ? "answered" : `refused, ${answer.why}`;
+/**
+* The connections the workflow declared, each operation sent with its place, inside a step, and
+* written to the run's trace once answered: which connection and operation, and what it came
+* to. Never what it answered.
+*/
+const connectionsOf = (sink, declared) => {
+	const send = async (connection, input) => {
+		const at = inStep.getStore();
+		if (at === void 0) throw new Error("ref0's calls run inside a step, in step.do's callback, since a run's code outside one runs again on each replay");
+		const place = {
+			step: at.step,
+			count: at.count,
+			call: at.connectionCalls
+		};
+		at.connectionCalls += 1;
+		const answer = await settle(sink.callConnection({
+			place,
+			connection,
+			method: "getIssue",
+			input
+		}));
+		console.log(`ref0: ${connection}.getIssue ${callWords(answer)}`);
+		return answer;
+	};
+	const entries = Object.entries(declared ?? {}).map(([connection, methods]) => [connection, methods.includes("getIssue") ? { getIssue: async (input) => await send(connection, input) } : {}]);
+	return Object.fromEntries(entries);
+};
+/**
+* A call's input, as a called workflow's `input` parses it, and its title from that: see
+* `WorkflowOwn['called']`.
+*/
+const calledOf = async (spec, given) => {
+	const parsed = await spec.input.safeParseAsync(given);
+	if (!parsed.success) return {
+		kind: "invalid",
+		why: issueOf(parsed.error, "Its input is invalid")
+	};
+	const copy = paramsOf(parsed.data);
+	if ("notJson" in copy) return {
+		kind: "invalid",
+		why: (copy.notJson === "" ? "Its input isn't JSON once parsed" : `Its input isn't JSON once parsed: ${copy.notJson} isn't`).slice(0, 1e3)
+	};
+	const title = spec.title({ input: parsed.data });
+	if (!isText(title)) return {
+		kind: "invalid",
+		why: "Its title isn't text: give title a function that returns text`…`"
+	};
+	return {
+		kind: "called",
+		input: copy.params,
+		title: {
+			strings: [...title.strings],
+			values: [...title.values]
+		}
+	};
+};
+/** The most a called run's output may be, as JSON in UTF-8, as `@ref0/contracts` says. */
+const maxOutputBytes = 65536;
+/**
+* What a called run's code came to: its output as JSON holds it, or why JSON can't hold it as it
+* is, or past its bound, which fails the run.
+*/
+const answerOf = (output) => {
+	if (output === void 0) return { kind: "returned" };
+	const copy = outputOf(output);
+	if ("notJson" in copy) return {
+		kind: "invalid output",
+		why: copy.notJson === "" ? "Its output isn't JSON" : `Its output isn't JSON: ${copy.notJson} isn't`.slice(0, 1e3)
+	};
+	const bytes = new TextEncoder().encode(JSON.stringify(copy.json)).byteLength;
+	if (bytes > maxOutputBytes) return {
+		kind: "invalid output",
+		why: `Its output is ${bytes} bytes of JSON, past ${maxOutputBytes}: return a name or a key, not the data`
+	};
+	return {
+		kind: "returned",
+		output: copy.json
+	};
+};
+/** The run's scope, for any check or called workflow its code runs through a handle. */
+const inRunOf = (sink, run) => inRun.run({
+	sink,
+	waiters: /* @__PURE__ */ new Map()
+}, run);
+const eventWorkflowOf = (spec) => ({ "~ref0": {
+	version: 1,
+	run: async (input, step, sink) => {
+		if ("input" in input) throw new Error("ref0 ran an event workflow on a call's input");
+		const event = input.event;
+		await inRunOf(sink, () => spec.run({
+			event,
+			sessions: input.sessions,
+			step: durableStep(step, sink),
+			ref0: actionsOf(sink),
+			connections: connectionsOf(sink, spec.permissions.connections)
+		}));
+		return { kind: "returned" };
+	}
+} });
+const calledWorkflowOf = (spec) => Object.assign(workflowHandle("this workflow"), { "~ref0": {
+	version: 1,
+	run: async (input, step, sink) => {
+		if (!("input" in input)) throw new Error("ref0 ran a called workflow on an event");
+		const parsed = input.input;
+		const output = await inRunOf(sink, () => spec.run({
+			input: parsed,
+			step: durableStep(step, sink),
+			ref0: actionsOf(sink),
+			connections: connectionsOf(sink, spec.permissions.connections)
+		}));
+		return answerOf(output);
+	},
+	called: async (input) => await calledOf(spec, input)
+} });
+function workflow(spec) {
+	return spec.input === void 0 ? eventWorkflowOf(spec) : calledWorkflowOf(spec);
+}
+/**
+* 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.
+*/
+const text = (strings, ...values) => ({
+	strings: [...strings],
+	values: values.map(String)
+});
+//#endregion
+export { AskRefused, CalledRunFailed, CheckRunRefused, PasskeyRequestRefused, allow, approval, ask, check, gate, local, oneOf, passkey, refuse, review, sandbox, text, workflow };
+
+//# sourceMappingURL=index.mjs.map