iterate 0.2.7 → 0.3.0

package/dist/next/project-ingress.mjs

@@ -0,0 +1,75 @@
+//#region src/next/project-ingress.ts
+/** A DNS label: lowercase letters and digits, single hyphens inside. */
+const DNS_LABEL = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** An app label: a DNS label that is also an itx identifier (it becomes a step, `itx.apps.<label>`). */
+const APP_LABEL = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** The labels `host` has under `hostname` — `site--p.iterate.app` ⇒ `["site--p"]` — lowercased, a
+*  trailing dot (a fully-qualified Host, `site--p.base.`) dropped; null when `host` is not under
+*  `hostname` at all. */
+function labelsUnder(host, hostname) {
+	const name = host.toLowerCase().replace(/\.$/, "");
+	const suffix = `.${hostname.toLowerCase()}`;
+	return name.endsWith(suffix) ? name.slice(0, -suffix.length).split(".") : null;
+}
+/** The project + app `url` names under `routing`, or null when it names none. Pure. */
+function projectAddressOf(routing, url, platformOrigin) {
+	if (!routing) return null;
+	if (routing.type === "subdomains") {
+		const labels = labelsUnder(url.hostname, routing.hostname);
+		if (!labels || labels.length > 2) return null;
+		const [first, second] = labels;
+		const separator = first.startsWith("xn--") ? -1 : first.indexOf("--");
+		const [app, project] = second !== void 0 ? [first, second] : separator === -1 ? [null, first] : [first.slice(0, separator), first.slice(separator + 2)];
+		if (!DNS_LABEL.test(project) || app !== null && !APP_LABEL.test(app)) return null;
+		return {
+			app,
+			project,
+			basePath: ""
+		};
+	}
+	if (url.origin !== new URL(platformOrigin).origin) return null;
+	const [, prefix, project = "", app] = url.pathname.split("/");
+	if (prefix !== "projects" || !DNS_LABEL.test(project)) return null;
+	if (app === void 0 || app === "") return {
+		app: null,
+		project,
+		basePath: `/projects/${project}`
+	};
+	if (!APP_LABEL.test(app)) return null;
+	return {
+		app,
+		project,
+		basePath: `/projects/${project}/${app}`
+	};
+}
+/** A CUSTOM HOSTNAME — one of a deployment's own that IS a project's apex (os-next
+*  `urls.temporaryCustomHostnames`, `{ "iterate2.com": "iterate" }`): the apex shape, `app: null`, so the
+*  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for a
+*  hostname the map does not name — the map's spelling, case and a trailing dot forgiven, no wildcard
+*  under it. Pure. */
+function customProjectHostOf(hostname, hostnames) {
+	const project = hostnames[hostname.toLowerCase().replace(/\.$/, "")];
+	return project ? {
+		app: null,
+		project
+	} : null;
+}
+/** The URL of `app` (null ⇒ the apex, the config worker) in `project` under `routing`, at `path`
+*  (default "/", must start with "/"). Null when there is no ingress, or when the result would not
+*  parse back to the same address (a bad label; a `path` that climbs out of its app). subdomains:
+*  the protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+*  `http://<app>--<project>.localhost:8788/…`); paths: `<platformOrigin>/projects/<project>[/<app>]<path>`. Pure. */
+function projectUrlOf(routing, platformOrigin, target) {
+	if (!routing) return null;
+	const path = target.path || "/";
+	if (!path.startsWith("/")) throw new Error(`projectUrlOf: path must start with "/": ${path}`);
+	const app = target.app || null;
+	const origin = new URL(platformOrigin);
+	const url = routing.type === "subdomains" ? new URL(path, `${origin.protocol}//${app ? `${app}--` : ""}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : ""}`) : new URL(`/projects/${target.project}${app ? `/${app}` : ""}${path}`, origin.origin);
+	const parsed = projectAddressOf(routing, url, platformOrigin);
+	return parsed && parsed.project === target.project && parsed.app === app ? url : null;
+}
+//#endregion
+export { customProjectHostOf, projectAddressOf, projectUrlOf };
+
+//# sourceMappingURL=project-ingress.mjs.map

package/dist/next/project-ingress.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ingress.mjs","names":[],"sources":["../../src/next/project-ingress.ts"],"sourcesContent":["// next/project-ingress.ts — HOW PROJECTS ARE REACHED OVER HTTP, both directions in ONE pure file. A\n// deployment's `urls.ingressRouting` (os-next app-config.ts) names the mechanism; `projectAddressOf`\n// parses a request's URL into the project and app it names, `projectUrlOf` composes the URL of an\n// app in a project. The platform's edge parses; the platform, the dash and an app compose — one\n// implementation, table-tested to round-trip (project-ingress.test.ts). No imports.\n//\n//   subdomains  `<app>--<project>.<hostname>`, `<app>.<project>.<hostname>`, the apex `<project>.<hostname>`\n//               — every app its own origin, under one wildcard on `hostname`.\n//   paths       `<platformOrigin>/projects/<project>/<app>/…`, the apex `<platformOrigin>/projects/<project>/`\n//               — one origin (workers.dev has no wildcard), every project under `/projects/` so the\n//               platform's own paths (`/api`, `/mcp`, `/login`, …) need no reserved list; the edge\n//               sandboxes what an app serves.\n\n/** How projects are reached over HTTP; null ⇒ no ingress (`/api` and `/mcp` still answer). */\nexport type IngressRouting = { type: \"subdomains\"; hostname: string } | { type: \"paths\" } | null;\n\n/** What a request names: the project (its slug, as written — whether it EXISTS is the directory's\n *  answer), the app (null ⇒ the apex: the project's config worker answers), and the path prefix the\n *  edge strips before the app sees the URL (\"\" under subdomains; \"/projects/<project>\" or\n *  \"/projects/<project>/<app>\" under paths). */\nexport type ProjectAddress = { project: string; app: string | null; basePath: string };\n\n/** A DNS label: lowercase letters and digits, single hyphens inside. */\nconst DNS_LABEL = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;\n/** An app label: a DNS label that is also an itx identifier (it becomes a step, `itx.apps.<label>`). */\nconst APP_LABEL = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\n/** The labels `host` has under `hostname` — `site--p.iterate.app` ⇒ `[\"site--p\"]` — lowercased, a\n *  trailing dot (a fully-qualified Host, `site--p.base.`) dropped; null when `host` is not under\n *  `hostname` at all. */\nfunction labelsUnder(host: string, hostname: string): string[] | null {\n  const name = host.toLowerCase().replace(/\\.$/, \"\");\n  const suffix = `.${hostname.toLowerCase()}`;\n  return name.endsWith(suffix) ? name.slice(0, -suffix.length).split(\".\") : null;\n}\n\n/** The project + app `url` names under `routing`, or null when it names none. Pure. */\nexport function projectAddressOf(\n  routing: IngressRouting,\n  url: URL,\n  platformOrigin: string,\n): ProjectAddress | null {\n  if (!routing) return null;\n  if (routing.type === \"subdomains\") {\n    const labels = labelsUnder(url.hostname, routing.hostname);\n    if (!labels || labels.length > 2) return null; // deeper than `<app>.<project>` is not a project host\n    const [first, second] = labels as [string, string?];\n    const separator = first.startsWith(\"xn--\") ? -1 : first.indexOf(\"--\"); // `xn--…` is an IDN label (punycode), never `<app>--<project>`\n    const [app, project] =\n      // oxlint-disable-next-line iterate/simple-truthiness-check -- a PRESENT-but-empty second label (`<app>..<base>`) is the `<app>.<project>` shape (rejected below by DNS_LABEL), not the single-label `<project>` shape a truthiness check would route it to\n      second !== undefined\n        ? [first, second] // `<app>.<project>`\n        : separator === -1\n          ? [null, first] // the apex, `<project>`\n          : [first.slice(0, separator), first.slice(separator + 2)]; // `<app>--<project>`\n    // oxlint-disable-next-line iterate/simple-truthiness-check -- an empty app label (`--<project>.<base>`) must still be rejected by APP_LABEL; truthiness would skip the check and admit it\n    if (!DNS_LABEL.test(project) || (app !== null && !APP_LABEL.test(app))) return null;\n    return { app, project, basePath: \"\" };\n  }\n  if (url.origin !== new URL(platformOrigin).origin) return null;\n  const [, prefix, project = \"\", app] = url.pathname.split(\"/\");\n  if (prefix !== \"projects\" || !DNS_LABEL.test(project)) return null;\n  // oxlint-disable-next-line iterate/simple-truthiness-check -- `/projects/<project>` and `/projects/<project>/` are both the apex; a present-but-empty next segment is not an app\n  if (app === undefined || app === \"\")\n    return { app: null, project, basePath: `/projects/${project}` };\n  if (!APP_LABEL.test(app)) return null;\n  return { app, project, basePath: `/projects/${project}/${app}` };\n}\n\n/** A CUSTOM HOSTNAME — one of a deployment's own that IS a project's apex (os-next\n *  `urls.temporaryCustomHostnames`, `{ \"iterate2.com\": \"iterate\" }`): the apex shape, `app: null`, so the\n *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for a\n *  hostname the map does not name — the map's spelling, case and a trailing dot forgiven, no wildcard\n *  under it. Pure. */\nexport function customProjectHostOf(\n  hostname: string,\n  hostnames: Record<string, string>,\n): { app: null; project: string } | null {\n  const project = hostnames[hostname.toLowerCase().replace(/\\.$/, \"\")];\n  return project ? { app: null, project } : null;\n}\n\n/** The URL of `app` (null ⇒ the apex, the config worker) in `project` under `routing`, at `path`\n *  (default \"/\", must start with \"/\"). Null when there is no ingress, or when the result would not\n *  parse back to the same address (a bad label; a `path` that climbs out of its app). subdomains:\n *  the protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so\n *  `http://<app>--<project>.localhost:8788/…`); paths: `<platformOrigin>/projects/<project>[/<app>]<path>`. Pure. */\nexport function projectUrlOf(\n  routing: IngressRouting,\n  platformOrigin: string,\n  target: { project: string; app?: string | null; path?: string },\n): URL | null {\n  if (!routing) return null;\n  const path = target.path || \"/\";\n  if (!path.startsWith(\"/\")) throw new Error(`projectUrlOf: path must start with \"/\": ${path}`);\n  const app = target.app || null;\n  const origin = new URL(platformOrigin);\n  const url =\n    routing.type === \"subdomains\"\n      ? new URL(\n          path,\n          `${origin.protocol}//${app ? `${app}--` : \"\"}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : \"\"}`,\n        )\n      : new URL(`/projects/${target.project}${app ? `/${app}` : \"\"}${path}`, origin.origin);\n  const parsed = projectAddressOf(routing, url, platformOrigin);\n  return parsed && parsed.project === target.project && parsed.app === app ? url : null;\n}\n"],"mappings":";;AAuBA,MAAM,YAAY;;AAElB,MAAM,YAAY;;;;AAKlB,SAAS,YAAY,MAAc,UAAmC;CACpE,MAAM,OAAO,KAAK,YAAY,CAAC,CAAC,QAAQ,OAAO,EAAE;CACjD,MAAM,SAAS,IAAI,SAAS,YAAY;CACxC,OAAO,KAAK,SAAS,MAAM,IAAI,KAAK,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,GAAG,IAAI;AAC5E;;AAGA,SAAgB,iBACd,SACA,KACA,gBACuB;CACvB,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,SAAS,cAAc;EACjC,MAAM,SAAS,YAAY,IAAI,UAAU,QAAQ,QAAQ;EACzD,IAAI,CAAC,UAAU,OAAO,SAAS,GAAG,OAAO;EACzC,MAAM,CAAC,OAAO,UAAU;EACxB,MAAM,YAAY,MAAM,WAAW,MAAM,IAAI,KAAK,MAAM,QAAQ,IAAI;EACpE,MAAM,CAAC,KAAK,WAEV,WAAW,KAAA,IACP,CAAC,OAAO,MAAM,IACd,cAAc,KACZ,CAAC,MAAM,KAAK,IACZ,CAAC,MAAM,MAAM,GAAG,SAAS,GAAG,MAAM,MAAM,YAAY,CAAC,CAAC;EAE9D,IAAI,CAAC,UAAU,KAAK,OAAO,KAAM,QAAQ,QAAQ,CAAC,UAAU,KAAK,GAAG,GAAI,OAAO;EAC/E,OAAO;GAAE;GAAK;GAAS,UAAU;EAAG;CACtC;CACA,IAAI,IAAI,WAAW,IAAI,IAAI,cAAc,CAAC,CAAC,QAAQ,OAAO;CAC1D,MAAM,GAAG,QAAQ,UAAU,IAAI,OAAO,IAAI,SAAS,MAAM,GAAG;CAC5D,IAAI,WAAW,cAAc,CAAC,UAAU,KAAK,OAAO,GAAG,OAAO;CAE9D,IAAI,QAAQ,KAAA,KAAa,QAAQ,IAC/B,OAAO;EAAE,KAAK;EAAM;EAAS,UAAU,aAAa;CAAU;CAChE,IAAI,CAAC,UAAU,KAAK,GAAG,GAAG,OAAO;CACjC,OAAO;EAAE;EAAK;EAAS,UAAU,aAAa,QAAQ,GAAG;CAAM;AACjE;;;;;;AAOA,SAAgB,oBACd,UACA,WACuC;CACvC,MAAM,UAAU,UAAU,SAAS,YAAY,CAAC,CAAC,QAAQ,OAAO,EAAE;CAClE,OAAO,UAAU;EAAE,KAAK;EAAM;CAAQ,IAAI;AAC5C;;;;;;AAOA,SAAgB,aACd,SACA,gBACA,QACY;CACZ,IAAI,CAAC,SAAS,OAAO;CACrB,MAAM,OAAO,OAAO,QAAQ;CAC5B,IAAI,CAAC,KAAK,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,2CAA2C,MAAM;CAC5F,MAAM,MAAM,OAAO,OAAO;CAC1B,MAAM,SAAS,IAAI,IAAI,cAAc;CACrC,MAAM,MACJ,QAAQ,SAAS,eACb,IAAI,IACF,MACA,GAAG,OAAO,SAAS,IAAI,MAAM,GAAG,IAAI,MAAM,KAAK,OAAO,QAAQ,GAAG,QAAQ,WAAW,OAAO,OAAO,IAAI,OAAO,SAAS,IACxH,IACA,IAAI,IAAI,aAAa,OAAO,UAAU,MAAM,IAAI,QAAQ,KAAK,QAAQ,OAAO,MAAM;CACxF,MAAM,SAAS,iBAAiB,SAAS,KAAK,cAAc;CAC5D,OAAO,UAAU,OAAO,YAAY,OAAO,WAAW,OAAO,QAAQ,MAAM,MAAM;AACnF"}

package/dist/next/react.mjs

@@ -0,0 +1,285 @@
+import { connectLiveState } from "./client.mjs";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+//#region src/next/client/react.tsx
+/** @jsxImportSource react */
+/** Subscribe to a producer's live state and render its latest value. Pass a ready `itx` (a capnweb
+*  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `door`
+*  thunk that reads `{rev, state}` (`() => itx.invoke("itx.facets.get('slug').liveSnapshot()")`).
+*  Re-subscribes when the session, `key`, or `name` changes; unmount (and every re-subscribe)
+*  disposes the previous server-side subscription. */
+function useLiveState(itx, opts) {
+	const [store, setStore] = useState();
+	const [status, setStatus] = useState("connecting");
+	const [error, setError] = useState();
+	const doorRef = useRef(opts.door);
+	doorRef.current = opts.door;
+	useEffect(() => {
+		setStore(void 0);
+		setStatus("connecting");
+		setError(void 0);
+		if (!itx) return;
+		const door = doorRef.current;
+		let disposed = false;
+		let dispose;
+		const unmounted = new AbortController();
+		connectLiveState(itx, {
+			key: opts.key,
+			name: opts.name,
+			door,
+			signal: unmounted.signal,
+			onResync: (r) => {
+				if (disposed) return;
+				if (r === "healed") {
+					setStatus("live");
+					setError(void 0);
+				} else {
+					setStatus("error");
+					setError(r.message);
+				}
+			}
+		}).then((conn) => {
+			dispose = conn.dispose;
+			if (disposed) {
+				conn.dispose();
+				return;
+			}
+			setStore(conn.store);
+			setStatus("live");
+		}, (e) => {
+			if (disposed) return;
+			setError(e instanceof Error ? e.message : String(e));
+			setStatus("error");
+		});
+		return () => {
+			disposed = true;
+			unmounted.abort();
+			dispose?.();
+		};
+	}, [
+		itx,
+		opts.key,
+		opts.name
+	]);
+	return {
+		value: useSyncExternalStore(useCallback((cb) => store ? store.subscribe(cb) : () => {}, [store]), () => store?.get(), () => void 0),
+		rev: store?.rev() ?? null,
+		status,
+		error
+	};
+}
+/** A wire event (a capnweb proxy value or a plain object) as an `IterateContextEvent`, or null when
+*  it is not a committed row. Structural, not a schema: the transport validated it; this only refuses
+*  a shape the view cannot place (no offset, type or time). */
+function toIterateContextEvent(raw) {
+	const value = JSON.parse(JSON.stringify(raw));
+	if (!value || typeof value.offset !== "number" || typeof value.type !== "string" || typeof value.createdAt !== "string") return null;
+	return value;
+}
+/** A named live state before its first seed lands — and before the effect that opens it has run. */
+const LIVE_STATE_CONNECTING = {
+	value: void 0,
+	rev: null,
+	status: "connecting"
+};
+/** THE ITERATE CONTEXT, live — one hook, one stream subscription. THE LOG: subscribe to every
+*  committed event (or `consumes`) BEFORE the catch-up read, so nothing lands between the two;
+*  pushes and pages both dedupe into one map by offset; `caughtUp` once the read reached the head;
+*  `error` when the connect failed. Off that same log, THE PROCESSORS TABLE, re-read whenever the
+*  log grows a row-changing event (a subscription configured, halted or resumed — the table is core
+*  state, one call away, no push of its own), and WHO IS HERE: the rpc stubs lent right now
+*  (`itx.rpcStubs.list()` — physical, re-read at every new head, since presence changes are
+*  ephemeral facts) and, from the log, every principal that acted, newest first. And named facets'
+*  LIVE STATE, each seeded through `itx.facets.get('<name>').liveSnapshot()` — one entry per name,
+*  always. `liveState` OMITTED opens `core` (the core reduce answers under that name) plus every
+*  hosted facet in the processors table the hook holds, following the table as it loads and changes;
+*  `liveState` GIVEN is exactly the names to open, no implicit `core`. Re-connects when `itx`
+*  changes; unmount disposes every server-side subscription. */
+function useIterateContext(itx, opts = {}) {
+	const [events, setEvents] = useState(() => /* @__PURE__ */ new Map());
+	const [caughtUp, setCaughtUp] = useState(false);
+	const [error, setError] = useState();
+	const consumesKey = JSON.stringify(opts.consumes || ["*"]);
+	useEffect(() => {
+		setEvents(/* @__PURE__ */ new Map());
+		setCaughtUp(false);
+		setError(void 0);
+		if (!itx) return;
+		let disposed = false;
+		const merge = (batch) => setEvents((held) => {
+			const next = new Map(held);
+			for (const raw of batch) {
+				const event = toIterateContextEvent(raw);
+				if (event) next.set(event.offset, event);
+			}
+			return next;
+		});
+		let subscription;
+		(async () => {
+			const handle = await itx.subscribe({
+				consumes: JSON.parse(consumesKey),
+				target: (batch) => !disposed && merge(batch)
+			});
+			if (disposed) {
+				handle[Symbol.dispose]();
+				return;
+			}
+			subscription = handle;
+			for (let after = 0;;) {
+				const page = await itx.readEvents(after, 500);
+				if (disposed) return;
+				merge(page.events);
+				if (page.atHead || page.scannedThroughOffset <= after) break;
+				after = page.scannedThroughOffset;
+			}
+			setCaughtUp(true);
+		})().catch((e) => !disposed && setError(e instanceof Error ? e.message : String(e)));
+		return () => {
+			disposed = true;
+			subscription?.[Symbol.dispose]();
+		};
+	}, [itx, consumesKey]);
+	const sorted = useMemo(() => [...events.values()].sort((a, b) => a.offset - b.offset), [events]);
+	const [table, setTable] = useState();
+	const [failure, setFailure] = useState();
+	useEffect(() => {
+		if (!itx) return;
+		let disposed = false;
+		Promise.resolve(itx.processors.list()).then((list) => {
+			if (disposed) return;
+			setTable({
+				itx,
+				rows: list
+			});
+			setFailure(void 0);
+		}, (e) => !disposed && setFailure({
+			itx,
+			message: e instanceof Error ? e.message : String(e)
+		}));
+		return () => {
+			disposed = true;
+		};
+	}, [itx, sorted.reduce((last, event) => event.type.startsWith("events.iterate.com/stream/subscription-") ? event.offset : last, 0)]);
+	const currentTable = itx && table?.itx === itx ? table : void 0;
+	const [census, setCensus] = useState();
+	useEffect(() => {
+		if (!itx?.rpcStubs) return;
+		let disposed = false;
+		Promise.resolve(itx.rpcStubs.list()).then((list) => !disposed && setCensus({
+			itx,
+			rpcStubs: list
+		}), () => void 0);
+		return () => {
+			disposed = true;
+		};
+	}, [itx, sorted.at(-1)?.offset ?? 0]);
+	const rpcStubs = itx && census?.itx === itx ? census.rpcStubs : [];
+	const actors = useMemo(() => {
+		const byActor = /* @__PURE__ */ new Map();
+		for (const event of sorted) {
+			const principal = event.source?.principal;
+			if (!principal) continue;
+			byActor.set(principal.actor, {
+				actor: principal.actor,
+				email: principal.email,
+				grant: event.source?.grant,
+				lastSeenAt: event.createdAt
+			});
+		}
+		return [...byActor.values()].sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+	}, [sorted]);
+	const liveStateKey = JSON.stringify(opts.liveState || ["core", ...(currentTable?.rows || []).flatMap((row) => row.hostedFacet ? [row.hostedFacet.name] : [])]);
+	const [liveStates, setLiveStates] = useState();
+	useEffect(() => {
+		if (!itx) return;
+		const names = JSON.parse(liveStateKey);
+		if (names.length === 0) return;
+		let disposed = false;
+		const unmounted = new AbortController();
+		const disposers = [];
+		const patch = (name, change) => setLiveStates((held) => held && held.itx === itx && held.key === liveStateKey ? {
+			...held,
+			entries: {
+				...held.entries,
+				[name]: {
+					...held.entries[name],
+					...change
+				}
+			}
+		} : held);
+		setLiveStates({
+			itx,
+			key: liveStateKey,
+			entries: Object.fromEntries(names.map((name) => [name, LIVE_STATE_CONNECTING]))
+		});
+		for (const name of names) connectLiveState(itx, {
+			key: name,
+			door: async () => await itx.invoke(`itx.facets.get('${name}').liveSnapshot()`),
+			signal: unmounted.signal,
+			onResync: (result) => {
+				if (disposed) return;
+				if (result === "healed") patch(name, {
+					status: "live",
+					error: void 0
+				});
+				else patch(name, {
+					status: "error",
+					error: result.message
+				});
+			}
+		}).then((connection) => {
+			if (disposed) {
+				connection.dispose();
+				return;
+			}
+			disposers.push(connection.dispose);
+			disposers.push(connection.store.subscribe(() => patch(name, {
+				value: connection.store.get(),
+				rev: connection.store.rev()
+			})));
+			patch(name, {
+				value: connection.store.get(),
+				rev: connection.store.rev(),
+				status: "live"
+			});
+		}, (e) => {
+			if (disposed) return;
+			patch(name, {
+				status: "error",
+				error: e instanceof Error ? e.message : String(e)
+			});
+		});
+		return () => {
+			disposed = true;
+			unmounted.abort();
+			for (const dispose of disposers) dispose();
+		};
+	}, [itx, liveStateKey]);
+	const liveState = useMemo(() => {
+		const names = JSON.parse(liveStateKey);
+		const held = itx && liveStates?.itx === itx && liveStates.key === liveStateKey ? liveStates.entries : {};
+		return Object.fromEntries(names.map((name) => [name, held[name] || LIVE_STATE_CONNECTING]));
+	}, [
+		itx,
+		liveStateKey,
+		liveStates
+	]);
+	return {
+		events: sorted,
+		caughtUp,
+		error,
+		processors: {
+			rows: currentTable?.rows || [],
+			loaded: Boolean(currentTable),
+			error: itx && failure?.itx === itx ? failure.message : void 0
+		},
+		presence: {
+			actors,
+			rpcStubs
+		},
+		liveState
+	};
+}
+//#endregion
+export { useIterateContext, useLiveState };
+
+//# sourceMappingURL=react.mjs.map

package/dist/next/react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.mjs","names":[],"sources":["../../src/next/client/react.tsx"],"sourcesContent":["/** @jsxImportSource react */\n// client/react.tsx — the REACT binding for clean-room live state, shared by every UI (the hosted\n// /demo and the control-plane console). `useLiveState` subscribes a component to a producer's live\n// state (a processor slug, a mini-app key), seeds through its door, and re-renders on every synced\n// delta via `useSyncExternalStore` over the LiveStateStore. The transport and the store\n// (client/live-state.ts) stay framework-free, so this is the ONE file that imports React.\n//\n// Adapted from apps/os's `useLiveState` (packages/iterate/src/sdk/capnweb/react.tsx), kept to the one\n// shape a UI/test needs — no reconnect/backoff/ping-watchdog (that policy belongs to whoever owns the\n// capnweb session; here the caller passes a ready `itx`).\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  connectLiveState,\n  type LiveStateItx,\n  type LiveStateSeed,\n  type LiveStateStore,\n} from \"./live-state.ts\";\n\nexport type LiveStateStatus = \"connecting\" | \"live\" | \"error\";\n\n/** One live state as a component reads it: the latest value (undefined until the first seed lands),\n *  the revision it is at, whether its subscription is connecting, live or failed, and the failure. */\nexport type LiveStateResult<S = unknown> = {\n  value: S | undefined;\n  rev: number | null;\n  status: LiveStateStatus;\n  error?: string;\n};\n\n/** Subscribe to a producer's live state and render its latest value. Pass a ready `itx` (a capnweb\n *  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `door`\n *  thunk that reads `{rev, state}` (`() => itx.invoke(\"itx.facets.get('slug').liveSnapshot()\")`).\n *  Re-subscribes when the session, `key`, or `name` changes; unmount (and every re-subscribe)\n *  disposes the previous server-side subscription. */\nexport function useLiveState<S>(\n  itx: LiveStateItx | undefined,\n  opts: { key: string; name?: string; door: () => Promise<LiveStateSeed<S>> },\n): LiveStateResult<S> {\n  const [store, setStore] = useState<LiveStateStore<S> | undefined>();\n  const [status, setStatus] = useState<LiveStateStatus>(\"connecting\");\n  const [error, setError] = useState<string | undefined>();\n  // The door thunk is a fresh arrow every render; hold the latest so the effect need not re-run per\n  // render. The effect SNAPSHOTS it at connect time, so an old subscription's gap heal can never\n  // read a NEWER key's door (cross-key contamination after a key/session switch).\n  const doorRef = useRef(opts.door);\n  doorRef.current = opts.door;\n\n  useEffect(() => {\n    setStore(undefined);\n    setStatus(\"connecting\");\n    setError(undefined);\n    if (!itx) return;\n    const door = doorRef.current; // pinned to THIS key/session for the connection's whole life\n    let disposed = false;\n    let dispose: (() => Promise<void>) | undefined;\n    const unmounted = new AbortController(); // an unmount while the first seed is pending recalls the row\n    connectLiveState<S>(itx, {\n      key: opts.key,\n      name: opts.name,\n      door,\n      signal: unmounted.signal,\n      onResync: (r) => {\n        if (disposed) return;\n        if (r === \"healed\") {\n          setStatus(\"live\");\n          setError(undefined);\n        } else {\n          // the store keeps its last value; the next delta retries the heal\n          setStatus(\"error\");\n          setError(r.message);\n        }\n      },\n    }).then(\n      (conn) => {\n        dispose = conn.dispose;\n        if (disposed) {\n          void conn.dispose(); // unmounted while connecting — still tear the mount down\n          return;\n        }\n        setStore(conn.store);\n        setStatus(\"live\");\n      },\n      (e: unknown) => {\n        if (disposed) return;\n        setError(e instanceof Error ? e.message : String(e));\n        setStatus(\"error\");\n      },\n    );\n    return () => {\n      disposed = true;\n      unmounted.abort();\n      void dispose?.();\n    };\n  }, [itx, opts.key, opts.name]);\n\n  const subscribe = useCallback(\n    (cb: () => void) => (store ? store.subscribe(cb) : () => {}),\n    [store],\n  );\n  const value = useSyncExternalStore(\n    subscribe,\n    () => store?.get(),\n    () => undefined,\n  );\n  return { value, rev: store?.rev() ?? null, status, error };\n}\n\n// ── the iterate context ── the data half of a general-purpose context view (packages/ui\n// `components/context-view`, the rendering half): every committed event of a context, live; the rows\n// of its processors table; who is here; named facets' live state. ONE hook here, pure components\n// there, so the UI kit stays free of the SDK and any app — the dash, the agents app — composes the two.\n\n/** One committed event as the hook hands it out: the itx envelope, structurally. */\nexport type IterateContextEvent = {\n  offset: number;\n  type: string;\n  createdAt: string;\n  payload?: unknown;\n  metadata?: Record<string, unknown>;\n  idempotencyKey?: string;\n  source?: {\n    principal?: { actor: string; email?: string };\n    grant?: string;\n    processor?: { slug: string; version: string };\n  };\n};\n\n/** One row of a context's processors table (`itx.processors.list()`), structurally. */\nexport type IterateContextProcessorRow = {\n  name: string;\n  target: string;\n  consumes?: string[];\n  configuredAtOffset: number;\n  hostedFacet?: { name: string; className: string; cacheKey?: string; restarts: number };\n};\n\n/** One presence: who acted on the context and when last, from the log's stamps. */\nexport type IterateContextPresence = {\n  actor: string;\n  email?: string;\n  grant?: string;\n  lastSeenAt: string;\n};\n\n/** The slice of a context handle `useIterateContext` reads — a capnweb `IterateContextApi` stub\n *  satisfies it structurally. `rpcStubs` is optional: a handle typed without the census (a project\n *  context's client type) still gets the log, the table and the actors. `invoke` seeds a named\n *  facet's live state (`itx.facets.get('<name>').liveSnapshot()`, as an expression). */\nexport type IterateContextHandle = LiveStateItx & {\n  readEvents(\n    afterOffset?: number,\n    limit?: number,\n  ): Promise<{ events: unknown[]; atHead: boolean; scannedThroughOffset: number }>;\n  processors: { list(): Promise<IterateContextProcessorRow[]> | IterateContextProcessorRow[] };\n  rpcStubs?: { list(): Promise<string[]> | string[] };\n  invoke(call: string): Promise<unknown>;\n};\n\n/** A wire event (a capnweb proxy value or a plain object) as an `IterateContextEvent`, or null when\n *  it is not a committed row. Structural, not a schema: the transport validated it; this only refuses\n *  a shape the view cannot place (no offset, type or time). */\nfunction toIterateContextEvent(raw: unknown): IterateContextEvent | null {\n  const value = JSON.parse(JSON.stringify(raw)) as Record<string, unknown> | null;\n  if (\n    !value ||\n    typeof value.offset !== \"number\" ||\n    typeof value.type !== \"string\" ||\n    typeof value.createdAt !== \"string\"\n  )\n    return null;\n  return value as unknown as IterateContextEvent; // the three fields checked are all the hook indexes by\n}\n\n/** A named live state before its first seed lands — and before the effect that opens it has run. */\nconst LIVE_STATE_CONNECTING: LiveStateResult = {\n  value: undefined,\n  rev: null,\n  status: \"connecting\",\n};\n\n/** THE ITERATE CONTEXT, live — one hook, one stream subscription. THE LOG: subscribe to every\n *  committed event (or `consumes`) BEFORE the catch-up read, so nothing lands between the two;\n *  pushes and pages both dedupe into one map by offset; `caughtUp` once the read reached the head;\n *  `error` when the connect failed. Off that same log, THE PROCESSORS TABLE, re-read whenever the\n *  log grows a row-changing event (a subscription configured, halted or resumed — the table is core\n *  state, one call away, no push of its own), and WHO IS HERE: the rpc stubs lent right now\n *  (`itx.rpcStubs.list()` — physical, re-read at every new head, since presence changes are\n *  ephemeral facts) and, from the log, every principal that acted, newest first. And named facets'\n *  LIVE STATE, each seeded through `itx.facets.get('<name>').liveSnapshot()` — one entry per name,\n *  always. `liveState` OMITTED opens `core` (the core reduce answers under that name) plus every\n *  hosted facet in the processors table the hook holds, following the table as it loads and changes;\n *  `liveState` GIVEN is exactly the names to open, no implicit `core`. Re-connects when `itx`\n *  changes; unmount disposes every server-side subscription. */\nexport function useIterateContext(\n  itx: IterateContextHandle | undefined,\n  opts: { consumes?: string[]; liveState?: string[] } = {},\n): {\n  events: IterateContextEvent[];\n  caughtUp: boolean;\n  error?: string;\n  processors: { rows: IterateContextProcessorRow[]; loaded: boolean; error?: string };\n  presence: { actors: IterateContextPresence[]; rpcStubs: string[] };\n  liveState: Record<string, LiveStateResult>;\n} {\n  // ── the log ──\n  const [events, setEvents] = useState<Map<number, IterateContextEvent>>(() => new Map());\n  const [caughtUp, setCaughtUp] = useState(false);\n  const [error, setError] = useState<string | undefined>();\n  const consumesKey = JSON.stringify(opts.consumes || [\"*\"]);\n  useEffect(() => {\n    setEvents(new Map());\n    setCaughtUp(false);\n    setError(undefined);\n    if (!itx) return;\n    let disposed = false;\n    const merge = (batch: unknown[]) =>\n      setEvents((held) => {\n        const next = new Map(held);\n        for (const raw of batch) {\n          const event = toIterateContextEvent(raw);\n          if (event) next.set(event.offset, event);\n        }\n        return next;\n      });\n    let subscription: { [Symbol.dispose](): void } | undefined;\n    (async () => {\n      const handle = await itx.subscribe({\n        consumes: JSON.parse(consumesKey) as string[],\n        target: (batch) => !disposed && merge(batch),\n      });\n      // An unmount while the subscribe was pending ran the cleanup before this handle existed:\n      // release it here, or the server keeps delivering to nobody.\n      if (disposed) {\n        handle[Symbol.dispose]();\n        return;\n      }\n      subscription = handle;\n      for (let after = 0; ; ) {\n        const page = await itx.readEvents(after, 500);\n        if (disposed) return;\n        merge(page.events);\n        if (page.atHead || page.scannedThroughOffset <= after) break;\n        after = page.scannedThroughOffset;\n      }\n      setCaughtUp(true);\n    })().catch((e: unknown) => !disposed && setError(e instanceof Error ? e.message : String(e)));\n    return () => {\n      disposed = true;\n      subscription?.[Symbol.dispose]();\n    };\n  }, [itx, consumesKey]);\n  const sorted = useMemo(() => [...events.values()].sort((a, b) => a.offset - b.offset), [events]);\n\n  // ── the processors table ──\n  // The table and the last failure remember WHICH itx they came from: a page that swaps contexts\n  // (one route, another organization) shows an empty, not-yet-loaded table for the new one rather\n  // than the old one's rows or error until the new read lands.\n  const [table, setTable] = useState<{\n    itx: IterateContextHandle;\n    rows: IterateContextProcessorRow[];\n  }>();\n  const [failure, setFailure] = useState<{ itx: IterateContextHandle; message: string }>();\n  const tableVersion = sorted.reduce(\n    (last, event) =>\n      event.type.startsWith(\"events.iterate.com/stream/subscription-\") ? event.offset : last,\n    0,\n  );\n  useEffect(() => {\n    if (!itx) return;\n    let disposed = false;\n    Promise.resolve(itx.processors.list()).then(\n      (list) => {\n        if (disposed) return;\n        setTable({ itx, rows: list });\n        setFailure(undefined); // a read that recovered clears the last failure\n      },\n      (e: unknown) =>\n        !disposed && setFailure({ itx, message: e instanceof Error ? e.message : String(e) }),\n    );\n    return () => {\n      disposed = true;\n    };\n  }, [itx, tableVersion]);\n  const currentTable = itx && table?.itx === itx ? table : undefined;\n\n  // ── who is here ──\n  const [census, setCensus] = useState<{ itx: IterateContextHandle; rpcStubs: string[] }>();\n  const head = sorted.at(-1)?.offset ?? 0;\n  useEffect(() => {\n    if (!itx?.rpcStubs) return;\n    let disposed = false;\n    Promise.resolve(itx.rpcStubs.list()).then(\n      (list) => !disposed && setCensus({ itx, rpcStubs: list }),\n      () => undefined, // presence is nice to have; a failed census shows nothing\n    );\n    return () => {\n      disposed = true;\n    };\n  }, [itx, head]);\n  // keyed by its itx: a swapped context shows no census until its own lands\n  const rpcStubs = itx && census?.itx === itx ? census.rpcStubs : [];\n  const actors = useMemo(() => {\n    const byActor = new Map<string, IterateContextPresence>();\n    for (const event of sorted) {\n      const principal = event.source?.principal;\n      if (!principal) continue;\n      byActor.set(principal.actor, {\n        actor: principal.actor,\n        email: principal.email,\n        grant: event.source?.grant,\n        lastSeenAt: event.createdAt,\n      });\n    }\n    return [...byActor.values()].sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));\n  }, [sorted]);\n\n  // ── named facets' live state ──\n  // N subscriptions in ONE effect keyed by the name set — it changes at runtime as the processors\n  // table loads (the default set is `core` plus the table's hosted facets) — since hooks cannot run\n  // in a loop: client/live-state.ts's store reduces each, and this mirrors every change into React\n  // state. The entries remember WHICH itx and name set they came from (as the table does), so a\n  // swapped context or a changed set shows fresh connecting entries, never the last one's values.\n  const liveStateKey = JSON.stringify(\n    opts.liveState || [\n      \"core\",\n      ...(currentTable?.rows || []).flatMap((row) =>\n        row.hostedFacet ? [row.hostedFacet.name] : [],\n      ),\n    ],\n  );\n  const [liveStates, setLiveStates] = useState<{\n    itx: IterateContextHandle;\n    key: string;\n    entries: Record<string, LiveStateResult>;\n  }>();\n  useEffect(() => {\n    if (!itx) return;\n    const names = JSON.parse(liveStateKey) as string[];\n    if (names.length === 0) return;\n    let disposed = false;\n    const unmounted = new AbortController(); // an unmount while a first seed is pending recalls that row\n    const disposers: Array<() => void | Promise<void>> = [];\n    const patch = (name: string, change: Partial<LiveStateResult>) =>\n      setLiveStates((held) =>\n        held && held.itx === itx && held.key === liveStateKey\n          ? { ...held, entries: { ...held.entries, [name]: { ...held.entries[name], ...change } } }\n          : held,\n      );\n    setLiveStates({\n      itx,\n      key: liveStateKey,\n      entries: Object.fromEntries(names.map((name) => [name, LIVE_STATE_CONNECTING])),\n    });\n    for (const name of names) {\n      connectLiveState<unknown>(itx, {\n        key: name,\n        door: async () =>\n          // the engine's own `{ rev, state }` seed, as `liveSnapshot()` answers it\n          (await itx.invoke(`itx.facets.get('${name}').liveSnapshot()`)) as LiveStateSeed<unknown>,\n        signal: unmounted.signal,\n        onResync: (result) => {\n          if (disposed) return;\n          if (result === \"healed\") patch(name, { status: \"live\", error: undefined });\n          // the store keeps its last value; the next delta retries the heal\n          else patch(name, { status: \"error\", error: result.message });\n        },\n      }).then(\n        (connection) => {\n          if (disposed) {\n            void connection.dispose(); // unmounted while connecting — still tear the row down\n            return;\n          }\n          disposers.push(connection.dispose);\n          disposers.push(\n            connection.store.subscribe(() =>\n              patch(name, { value: connection.store.get(), rev: connection.store.rev() }),\n            ),\n          );\n          patch(name, {\n            value: connection.store.get(),\n            rev: connection.store.rev(),\n            status: \"live\",\n          });\n        },\n        (e: unknown) => {\n          if (disposed) return;\n          patch(name, { status: \"error\", error: e instanceof Error ? e.message : String(e) });\n        },\n      );\n    }\n    return () => {\n      disposed = true;\n      unmounted.abort();\n      for (const dispose of disposers) void dispose();\n    };\n  }, [itx, liveStateKey]);\n  // One entry per name, always: a name the effect has not reached yet (the render right after the\n  // set changed) reads as connecting rather than missing.\n  const liveState = useMemo(() => {\n    const names = JSON.parse(liveStateKey) as string[];\n    const held =\n      itx && liveStates?.itx === itx && liveStates.key === liveStateKey ? liveStates.entries : {};\n    return Object.fromEntries(names.map((name) => [name, held[name] || LIVE_STATE_CONNECTING]));\n  }, [itx, liveStateKey, liveStates]);\n\n  return {\n    events: sorted,\n    caughtUp,\n    error,\n    processors: {\n      rows: currentTable?.rows || [],\n      loaded: Boolean(currentTable),\n      error: itx && failure?.itx === itx ? failure.message : undefined,\n    },\n    presence: { actors, rpcStubs },\n    liveState,\n  };\n}\n"],"mappings":"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"}

package/dist/next/sdk/auth.d.ts

@@ -0,0 +1,5 @@
+/** Project ingress strips public identity headers and stamps the verified caller.
+ * This guard runs locally in the config worker, before it proxies an app. */
+export declare const auth: {
+    require(request: Request): Response | null;
+};

package/dist/next/sdk/index.d.ts

@@ -0,0 +1,112 @@
+import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import type { IterateContextApi } from "../api.ts";
+import { type ScannedRange, type StreamProcessor, type StreamEvent, type StreamEventInput } from "../stream/processor.ts";
+import { auth } from "./auth.ts";
+export { auth };
+export { StreamProcessor, defineProcessorContract, jsonEqual, type ConsumedEvent, type EventCatalog, type EventDefinition, type EmittedEventInput, type EventInput, type ProcessorContract, type ProcessorState, type ProcessorStream, type ProcessEventArgs, type ReduceArgs, type ScannedRange, type StreamEvent, type StreamEventInput, } from "../stream/processor.ts";
+export { z } from "zod";
+export { newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse } from "capnweb";
+export { applyPatch, diff, type PatchOp } from "../lib.ts";
+export { LiveState, type LiveStateSink } from "../stream/processor.ts";
+/** What the parent mints the class with — the whole identity. */
+export type StreamProcessorProps = {
+    iterateContextName: string;
+    name: string;
+};
+/** The itx scope as `env.ITX.get()` hands it over: a context's declared API (api.ts) — a capnweb stub
+ *  of os-next's `IterateContextRpcTarget`, which satisfies it. */
+export type ItxScope = IterateContextApi;
+/** What hands the scope over: the loopback entrypoint a loaded worker has as `env.ITX`, or the one a
+ *  class of the platform's own worker mints from `ctx.exports`. */
+export type ItxEntrypointService = {
+    get(): ItxScope;
+};
+/** The least a host needs of its scope: the fixed-point log calls the engine makes. The platform's own
+ *  facets pass the Workers-RPC STUB of a context (every dotted step pipelined; a property there is a
+ *  promise), which no plain-promise interface can name — so the constraint is this, not `ItxScope`. */
+export type ProcessorScope = {
+    append(...events: StreamEventInput[]): Promise<unknown>;
+    readEvents(afterOffset?: number, limit?: number): Promise<unknown>;
+    /** The engine's claim on the context's alarm (processor.ts rule 3): "come back by `at`", or null. */
+    processors: {
+        claim(name: string, at: number | null): Promise<unknown>;
+    };
+    /** Another context of the project — where `appendTo` lands — by its dotted surface (`.append`),
+     *  which the platform's handle and a loaded worker's alike answer. Through the table like every
+     *  other word here: a loaded processor's `cd` goes down only (the app wall), the platform's own
+     *  go anywhere. */
+    cd(path: string): {
+        append(...events: StreamEventInput[]): Promise<unknown>;
+    };
+};
+/** THE SCOPE ACCESSOR a host hands its processor: one pipelined round trip on the context's itx,
+ *  released after (`StreamProcessorDurableObject.withItx`). A processor that needs an effect —
+ *  `itx.cfArtifacts.create(path)`, `itx.ai.run(…)` — takes this and nothing else, so a unit test
+ *  hands it a fake and the e2e lends one by rule on the context. */
+export type WithItx<Scope = ItxScope> = <T>(call: (itx: Scope) => T) => Promise<Awaited<T>>;
+export declare abstract class StreamProcessorDurableObject<State = unknown, Env extends {
+    ITX?: ItxEntrypointService;
+} = {
+    ITX: ItxEntrypointService;
+}, Scope extends ProcessorScope = ItxScope> extends DurableObject<Env, StreamProcessorProps> {
+    #private;
+    /** The processor this object hosts — `processor = new PresenceProcessor()` at the top of the subclass. */
+    abstract readonly processor: StreamProcessor<State>;
+    /** After a runtime field on the processor moved OUTSIDE a batch (an RPC method on this object);
+     *  inside `processEvent` the engine re-projects on its own. */
+    protected publishLiveState(): void;
+    /** THE push door: the context hands over each committed batch with its scanned-range proof. */
+    processEventBatch(events: StreamEvent[], range: ScannedRange): Promise<void>;
+    /** Catch up from the log (the read-your-writes entry after an eviction). */
+    catchUpFromLog(): Promise<void>;
+    /** THE REVIVE: the context's alarm pass calls it for a due claim — catch up, then run the
+     *  at-head pass, so an attempt the last incarnation was running is started again from state. */
+    revive(): Promise<void>;
+    /** Caught up through the log, then `{ offset, state }`. */
+    snapshot(): Promise<{
+        offset: number;
+        state: State;
+    }>;
+    /** The live-state seed door: `{ rev, state: projectLiveState(reduced) }`. */
+    liveSnapshot(): Promise<{
+        rev: number;
+        state: unknown;
+    }>;
+    /** The barrier: resolves once processed at least through `offset` (default timeout 10s). */
+    waitUntilProcessed(input: {
+        offset: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** ONE pipelined round trip on the itx scope, then RELEASE it: `env.ITX.get()` and the call
+     *  pipelined on it PIN THE PARENT DO until GC (the "GC is too late" defect the DO's facet door
+     *  fixes in the other direction). Await the answer — plain data, the wire already copied it —
+     *  then dispose the call AND the get. Protected: a host with methods of its own (the workspace,
+     *  src/workspace/durable-object.ts) reaches its context the same way. */
+    protected withItx<T>(call: (itx: Scope) => T): Promise<Awaited<T>>;
+}
+export type ConfigWorkerItx = ItxScope;
+export type ConfigEventArgs = {
+    event: StreamEvent;
+    range: ScannedRange;
+    itx: ConfigWorkerItx;
+};
+export declare abstract class ConfigWorker<Env extends {
+    ITX: ItxEntrypointService;
+} = {
+    ITX: ItxEntrypointService;
+}> extends WorkerEntrypoint<Env> {
+    /** At fetch entry: `const denied = this.auth.require(request); if (denied) return denied;` */
+    protected readonly auth: {
+        require(request: Request): Response | null;
+    };
+    /** Process an explicitly subscribed batch with this worker's context scope. */
+    processEventBatch(events: StreamEvent[], range: ScannedRange): Promise<void>;
+    /** THE AUTHOR HOOK — one event at a time, in offset order. Append reactions through the itx scope;
+     *  make them idempotent (a redelivery must be a no-op). Default: ignore the event. */
+    processEvent(_args: ConfigEventArgs): void | Promise<void>;
+    /** THE WEB ROOT — the Request a project host with no app label rode in on (`x-iterate-app` absent;
+     *  the project's configured ingress target). Route by hostname to `this.env.ITX.get().apps.<x>.fetch(request)`
+     *  or answer it here. Default: not found. */
+    fetch(_request: Request): Response | Promise<Response>;
+}
+export { RunContract, RunRequested, RunSettled } from "../stream/run.ts";