iterate 0.3.0 → 0.4.0

package/dist/project-ingress.d.ts

@@ -0,0 +1,58 @@
+/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's
+ *  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or
+ *  deletes it on every project-host request, and the context DO deletes it from every other
+ *  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */
+export declare const ITERATE_ROUTING_SLUG_HEADER = "x-iterate-routing-slug";
+/** How projects are reached over HTTP; null ⇒ no ingress (`/api` and `/mcp` still answer). */
+export type IngressRouting = {
+    type: "subdomains";
+    hostname: string;
+} | {
+    type: "paths";
+} | null;
+/** What a request names: the project (its slug, as written — whether it EXISTS is the directory's
+ *  answer), the routing slug (null ⇒ the apex; either way the project's config worker answers), and
+ *  the path prefix the edge strips before the config worker sees the URL ("" under subdomains;
+ *  "/projects/<project>" or "/projects/<project>/<routingSlug>" under paths). */
+export type ProjectAddress = {
+    project: string;
+    routingSlug: string | null;
+    basePath: string;
+};
+/** The project + routing slug `url` names under `routing`, or null when it names none. Pure. */
+export declare function projectAddressOf(routing: IngressRouting, url: URL, platformOrigin: string): ProjectAddress | null;
+/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os
+ *  `urls.projectWildcard`, `{ hostname: "iterate.com", project: "iterate" }`): the zone's apex and
+ *  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the
+ *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for
+ *  anything else. Case and a trailing dot are forgiven. Pure. */
+export declare function projectWildcardHostOf(hostname: string, wildcard: {
+    hostname: string;
+    project: string;
+    excludedHostnames?: string[];
+} | undefined): {
+    routingSlug: null;
+    project: string;
+} | null;
+/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os
+ *  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing
+ *  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The
+ *  hostnames a request's host could be a project's own hostname for, most specific first: the host
+ *  itself (the apex), then its parent with the first label as the routing slug. The caller
+ *  looks them up in that order; the first a project holds wins. Case and a trailing dot are
+ *  forgiven. Pure. */
+export declare function customHostnameCandidatesOf(host: string): {
+    hostname: string;
+    routingSlug: string | null;
+}[];
+/** The URL of `routingSlug` (null ⇒ the apex) 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 slug; a `path` that climbs out of its routing slug). subdomains: the
+ *  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+ *  `http://<routingSlug>--<project>.localhost:8788/…`); paths:
+ *  `<platformOrigin>/projects/<project>[/<routingSlug>]<path>`. Pure. */
+export declare function projectUrlOf(routing: IngressRouting, platformOrigin: string, target: {
+    project: string;
+    routingSlug?: string | null;
+    path?: string;
+}): URL | null;

package/dist/project-ingress.mjs

@@ -0,0 +1,104 @@
+//#region src/project-ingress.ts
+/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's
+*  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or
+*  deletes it on every project-host request, and the context DO deletes it from every other
+*  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */
+const ITERATE_ROUTING_SLUG_HEADER = "x-iterate-routing-slug";
+/** A DNS label: lowercase letters and digits, single hyphens inside. */
+const DNS_LABEL = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A routing slug: a DNS label starting with a letter. */
+const ROUTING_SLUG = /^[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 + routing slug `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 [routingSlug, project] = second !== void 0 ? [first, second] : separator === -1 ? [null, first] : [first.slice(0, separator), first.slice(separator + 2)];
+		if (!DNS_LABEL.test(project) || routingSlug !== null && !ROUTING_SLUG.test(routingSlug)) return null;
+		return {
+			routingSlug,
+			project,
+			basePath: ""
+		};
+	}
+	if (url.origin !== new URL(platformOrigin).origin) return null;
+	const [, prefix, project = "", routingSlug] = url.pathname.split("/");
+	if (prefix !== "projects" || !DNS_LABEL.test(project)) return null;
+	if (routingSlug === void 0 || routingSlug === "") return {
+		routingSlug: null,
+		project,
+		basePath: `/projects/${project}`
+	};
+	if (!ROUTING_SLUG.test(routingSlug)) return null;
+	return {
+		routingSlug,
+		project,
+		basePath: `/projects/${project}/${routingSlug}`
+	};
+}
+/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os
+*  `urls.projectWildcard`, `{ hostname: "iterate.com", project: "iterate" }`): the zone's apex and
+*  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the
+*  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for
+*  anything else. Case and a trailing dot are forgiven. Pure. */
+function projectWildcardHostOf(hostname, wildcard) {
+	if (!wildcard) return null;
+	const normalized = hostname.toLowerCase().replace(/\.$/, "");
+	if (wildcard.excludedHostnames?.includes(normalized)) return null;
+	const suffix = `.${wildcard.hostname}`;
+	const label = normalized.endsWith(suffix) ? normalized.slice(0, -suffix.length) : null;
+	return normalized === wildcard.hostname || label && !label.includes(".") ? {
+		routingSlug: null,
+		project: wildcard.project
+	} : null;
+}
+/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os
+*  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing
+*  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The
+*  hostnames a request's host could be a project's own hostname for, most specific first: the host
+*  itself (the apex), then its parent with the first label as the routing slug. The caller
+*  looks them up in that order; the first a project holds wins. Case and a trailing dot are
+*  forgiven. Pure. */
+function customHostnameCandidatesOf(host) {
+	const hostname = host.toLowerCase().replace(/\.$/, "");
+	const dot = hostname.indexOf(".");
+	const [routingSlug, parent] = [hostname.slice(0, dot), hostname.slice(dot + 1)];
+	return [{
+		hostname,
+		routingSlug: null
+	}, ...dot > 0 && parent.includes(".") && ROUTING_SLUG.test(routingSlug) ? [{
+		hostname: parent,
+		routingSlug
+	}] : []];
+}
+/** The URL of `routingSlug` (null ⇒ the apex) 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 slug; a `path` that climbs out of its routing slug). subdomains: the
+*  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+*  `http://<routingSlug>--<project>.localhost:8788/…`); paths:
+*  `<platformOrigin>/projects/<project>[/<routingSlug>]<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 routingSlug = target.routingSlug || null;
+	const origin = new URL(platformOrigin);
+	const url = routing.type === "subdomains" ? new URL(path, `${origin.protocol}//${routingSlug ? `${routingSlug}--` : ""}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : ""}`) : new URL(`/projects/${target.project}${routingSlug ? `/${routingSlug}` : ""}${path}`, origin.origin);
+	const parsed = projectAddressOf(routing, url, platformOrigin);
+	return parsed && parsed.project === target.project && parsed.routingSlug === routingSlug ? url : null;
+}
+//#endregion
+export { ITERATE_ROUTING_SLUG_HEADER, customHostnameCandidatesOf, projectAddressOf, projectUrlOf, projectWildcardHostOf };
+
+//# sourceMappingURL=project-ingress.mjs.map

package/dist/project-ingress.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ingress.mjs","names":[],"sources":["../src/project-ingress.ts"],"sourcesContent":["// project-ingress.ts — HOW PROJECTS ARE REACHED OVER HTTP, both directions in ONE pure file. A\n// deployment's `urls.ingressRouting` (apps/os app-config.ts) names the mechanism; `projectAddressOf`\n// parses a request's URL into the project and routing slug it names, `projectUrlOf` composes the URL\n// of a routing slug in a project. The platform's edge parses; the platform, the dash and an app\n// compose — one implementation, table-tested to round-trip (project-ingress.test.ts). No imports.\n//\n// The edge picks the PROJECT only: every host of a project reaches the project's config worker\n// `fetch`, with the routing slug in `x-iterate-routing-slug` (absent on the apex), and the config\n// worker routes on it in plain code.\n//\n//   subdomains  `<routingSlug>--<project>.<hostname>`, `<routingSlug>.<project>.<hostname>`, the apex\n//               `<project>.<hostname>` — every routing slug its own origin, under one wildcard on `hostname`.\n//   paths       `<platformOrigin>/projects/<project>/<routingSlug>/…`, 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 a project serves.\n\n/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's\n *  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or\n *  deletes it on every project-host request, and the context DO deletes it from every other\n *  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */\nexport const ITERATE_ROUTING_SLUG_HEADER = \"x-iterate-routing-slug\";\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 routing slug (null ⇒ the apex; either way the project's config worker answers), and\n *  the path prefix the edge strips before the config worker sees the URL (\"\" under subdomains;\n *  \"/projects/<project>\" or \"/projects/<project>/<routingSlug>\" under paths). */\nexport type ProjectAddress = { project: string; routingSlug: 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/** A routing slug: a DNS label starting with a letter. */\nconst ROUTING_SLUG = /^[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 + routing slug `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 `<routingSlug>.<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 `<routingSlug>--<project>`\n    const [routingSlug, project] =\n      // oxlint-disable-next-line iterate/simple-truthiness-check -- a PRESENT-but-empty second label (`<routingSlug>..<base>`) is the `<routingSlug>.<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] // `<routingSlug>.<project>`\n        : separator === -1\n          ? [null, first] // the apex, `<project>`\n          : [first.slice(0, separator), first.slice(separator + 2)]; // `<routingSlug>--<project>`\n    // oxlint-disable-next-line iterate/simple-truthiness-check -- an empty routing slug (`--<project>.<base>`) must still be rejected by ROUTING_SLUG; truthiness would skip the check and admit it\n    if (!DNS_LABEL.test(project) || (routingSlug !== null && !ROUTING_SLUG.test(routingSlug)))\n      return null;\n    return { routingSlug, project, basePath: \"\" };\n  }\n  if (url.origin !== new URL(platformOrigin).origin) return null;\n  const [, prefix, project = \"\", routingSlug] = 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 a routing slug\n  if (routingSlug === undefined || routingSlug === \"\")\n    return { routingSlug: null, project, basePath: `/projects/${project}` };\n  if (!ROUTING_SLUG.test(routingSlug)) return null;\n  return { routingSlug, project, basePath: `/projects/${project}/${routingSlug}` };\n}\n\n/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os\n *  `urls.projectWildcard`, `{ hostname: \"iterate.com\", project: \"iterate\" }`): the zone's apex and\n *  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the\n *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for\n *  anything else. Case and a trailing dot are forgiven. Pure. */\nexport function projectWildcardHostOf(\n  hostname: string,\n  wildcard: { hostname: string; project: string; excludedHostnames?: string[] } | undefined,\n): { routingSlug: null; project: string } | null {\n  if (!wildcard) return null;\n  const normalized = hostname.toLowerCase().replace(/\\.$/, \"\");\n  if (wildcard.excludedHostnames?.includes(normalized)) return null;\n  const suffix = `.${wildcard.hostname}`;\n  const label = normalized.endsWith(suffix) ? normalized.slice(0, -suffix.length) : null;\n  return normalized === wildcard.hostname || (label && !label.includes(\".\"))\n    ? { routingSlug: null, project: wildcard.project }\n    : null;\n}\n\n/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os\n *  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing\n *  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The\n *  hostnames a request's host could be a project's own hostname for, most specific first: the host\n *  itself (the apex), then its parent with the first label as the routing slug. The caller\n *  looks them up in that order; the first a project holds wins. Case and a trailing dot are\n *  forgiven. Pure. */\nexport function customHostnameCandidatesOf(\n  host: string,\n): { hostname: string; routingSlug: string | null }[] {\n  const hostname = host.toLowerCase().replace(/\\.$/, \"\");\n  const dot = hostname.indexOf(\".\");\n  const [routingSlug, parent] = [hostname.slice(0, dot), hostname.slice(dot + 1)];\n  return [\n    { hostname, routingSlug: null },\n    ...(dot > 0 && parent.includes(\".\") && ROUTING_SLUG.test(routingSlug)\n      ? [{ hostname: parent, routingSlug }]\n      : []),\n  ];\n}\n\n/** The URL of `routingSlug` (null ⇒ the apex) in `project` under `routing`, at `path` (default \"/\",\n *  must start with \"/\"). Null when there is no ingress, or when the result would not parse back to\n *  the same address (a bad slug; a `path` that climbs out of its routing slug). subdomains: the\n *  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so\n *  `http://<routingSlug>--<project>.localhost:8788/…`); paths:\n *  `<platformOrigin>/projects/<project>[/<routingSlug>]<path>`. Pure. */\nexport function projectUrlOf(\n  routing: IngressRouting,\n  platformOrigin: string,\n  target: { project: string; routingSlug?: 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 routingSlug = target.routingSlug || null;\n  const origin = new URL(platformOrigin);\n  const url =\n    routing.type === \"subdomains\"\n      ? new URL(\n          path,\n          `${origin.protocol}//${routingSlug ? `${routingSlug}--` : \"\"}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : \"\"}`,\n        )\n      : new URL(\n          `/projects/${target.project}${routingSlug ? `/${routingSlug}` : \"\"}${path}`,\n          origin.origin,\n        );\n  const parsed = projectAddressOf(routing, url, platformOrigin);\n  return parsed && parsed.project === target.project && parsed.routingSlug === routingSlug\n    ? url\n    : null;\n}\n"],"mappings":"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"}

package/dist/{next/react.mjs → react.mjs}

@@ -1,9 +1,9 @@
 import { connectLiveState } from "./client.mjs";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-//#region src/next/client/react.tsx
+//#region src/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`
+*  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `readSeed`
 *  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. */
@@ -11,21 +11,21 @@ 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;
+	const readSeedRef = useRef(opts.readSeed);
+	readSeedRef.current = opts.readSeed;
 	useEffect(() => {
 		setStore(void 0);
 		setStatus("connecting");
 		setError(void 0);
 		if (!itx) return;
-		const door = doorRef.current;
+		const readSeed = readSeedRef.current;
 		let disposed = false;
 		let dispose;
 		const unmounted = new AbortController();
 		connectLiveState(itx, {
 			key: opts.key,
 			name: opts.name,
-			door,
+			readSeed,
 			signal: unmounted.signal,
 			onResync: (r) => {
 				if (disposed) return;
@@ -67,10 +67,10 @@ function useLiveState(itx, opts) {
 		error
 	};
 }
-/** A wire event (a capnweb proxy value or a plain object) as an `IterateContextEvent`, or null when
+/** A wire event (a capnweb proxy value or a plain object) as a `StreamEvent`, 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) {
+function toStreamEvent(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;
@@ -108,7 +108,7 @@ function useIterateContext(itx, opts = {}) {
 		const merge = (batch) => setEvents((held) => {
 			const next = new Map(held);
 			for (const raw of batch) {
-				const event = toIterateContextEvent(raw);
+				const event = toStreamEvent(raw);
 				if (event) next.set(event.offset, event);
 			}
 			return next;
@@ -158,11 +158,11 @@ function useIterateContext(itx, opts = {}) {
 		return () => {
 			disposed = true;
 		};
-	}, [itx, sorted.reduce((last, event) => event.type.startsWith("events.iterate.com/stream/subscription-") ? event.offset : last, 0)]);
+	}, [itx, sorted.reduce((last, event) => event.type.startsWith("events.iterate.com/itx/subscription-") ? event.offset : last, 0)]);
 	const currentTable = itx && table?.itx === itx ? table : void 0;
 	const [census, setCensus] = useState();
 	useEffect(() => {
-		if (!itx?.rpcStubs) return;
+		if (!itx) return;
 		let disposed = false;
 		Promise.resolve(itx.rpcStubs.list()).then((list) => !disposed && setCensus({
 			itx,
@@ -213,7 +213,7 @@ function useIterateContext(itx, opts = {}) {
 		});
 		for (const name of names) connectLiveState(itx, {
 			key: name,
-			door: async () => await itx.invoke(`itx.facets.get('${name}').liveSnapshot()`),
+			readSeed: async () => await itx.invoke(`itx.facets.get('${name}').liveSnapshot()`),
 			signal: unmounted.signal,
 			onResync: (result) => {
 				if (disposed) return;

package/dist/react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.mjs","names":[],"sources":["../src/client/react.tsx"],"sourcesContent":["/** @jsxImportSource react */\n// client/react.tsx — the React binding for live state, shared by every UI. `useLiveState` subscribes a component to a producer's live\n// state (a processor slug, a mini-app key), seeds from it, 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// Kept to the one shape a UI or test needs — no reconnect/backoff/ping-watchdog (that policy belongs\n// to whoever owns the capnweb session; here the caller passes a ready `itx`).\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport type { SubscriptionListEntry } from \"../api.ts\";\nimport type { StreamEvent } from \"../stream/processor.ts\";\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 `readSeed`\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; readSeed: () => 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 readSeed 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 seed (cross-key contamination after a key/session switch).\n  const readSeedRef = useRef(opts.readSeed);\n  readSeedRef.current = opts.readSeed;\n\n  useEffect(() => {\n    setStore(undefined);\n    setStatus(\"connecting\");\n    setError(undefined);\n    if (!itx) return;\n    const readSeed = readSeedRef.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      readSeed,\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 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. `invoke` seeds a named facet's live state\n *  (`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<SubscriptionListEntry[]> | SubscriptionListEntry[] };\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 a `StreamEvent`, 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 toStreamEvent(raw: unknown): StreamEvent | 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 StreamEvent; // 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: StreamEvent[];\n  caughtUp: boolean;\n  error?: string;\n  processors: { rows: SubscriptionListEntry[]; 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, StreamEvent>>(() => 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 = toStreamEvent(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: SubscriptionListEntry[];\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/itx/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) 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        readSeed: 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/sdk/auth.d.ts

@@ -0,0 +1,25 @@
+/** Project ingress strips public identity headers and stamps `x-itx-principal` for a project member
+ *  only: a visitor signed out, signed in without this project, or riding a session cookie on a
+ *  cross-site write arrives without one. This guard runs in the config worker, before it proxies an
+ *  app.
+ *
+ *  Signed out, every request gets `401` with `WWW-Authenticate: Bearer realm="iterate"`: the
+ *  platform's edge turns that answer into the sign-in for a page load (or into "sign in again with
+ *  this project" for someone signed in without it), whatever path the app is served under, and hands
+ *  a fetch, a write or a WebSocket upgrade the 401 itself. Any app can ask for a signed-in visitor
+ *  the same way:
+ *
+ *  ```js
+ *  if (!request.headers.get("x-itx-principal"))
+ *    return new Response("Sign in\n", { status: 401, headers: { "WWW-Authenticate": 'Bearer realm="iterate"' } });
+ *  ```
+ *
+ *  A write or a WebSocket upgrade must also come from this origin (or carry no Origin, a non-browser
+ *  client), else 403. The edge already sends such a cookie request on anonymous; this repeats the
+ *  check where the app runs. The handshake is a GET, but it opens a two-way channel, and the app
+ *  session cookie is `SameSite=Lax`: every `<routingSlug>--<project>.iterate.app` host is same-site with
+ *  every other, so a page on another project's host could otherwise open a socket to this app with
+ *  the visitor's cookie. */
+export declare const auth: {
+    require(request: Request): Response | null;
+};

package/dist/sdk/index.d.ts

@@ -0,0 +1,155 @@
+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 { withItx } from "./record-pipelined-steps.ts";
+export { withItx };
+export { LiveState, StreamProcessor, defineProcessorContract, type ConsumedEvent, type EventCatalog, type EventDefinition, type EmittedEventInput, type EventInput, type LiveStateSink, 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, jsonEqual, type PatchOp } from "../lib.ts";
+/** What the parent mints a facet's class with — the whole identity, and one fact about its feed. */
+export type FacetProps = {
+    iterateContextName: string;
+    name: string;
+    /** Set when, as this facet started, a subscription row of its context pushed it every commit it
+     *  consumes (`processEventBatch`, the delivery loop's push): a processor's engine then trusts the
+     *  head a catch-up read until the next push (stream/processor.ts, the read verbs). Absent, only a
+     *  push is proof, so a processor no row pushes reads its log on every read. */
+    fedByPushes?: true;
+};
+/** THE FACET SHELL: a `DurableObject` a context hosts as a facet — `itx.facets.get(name, { source,
+ *  className })`, a rule naming it, or a processor's row. A caller reaches a facet by itx expression
+ *  (`itx.facets.get(name).<method>(…)`) only through what its class lists in `publicMethods`: the
+ *  context refuses any other first step FORBIDDEN before the call reaches the facet
+ *  (apps/os context/facet-public-methods.ts). The platform's own calls — the delivery loop's push
+ *  and catch-up, the alarm's revive — never go through the list. A loaded class that does not
+ *  extend this shell lists nothing, so no caller reaches it by expression. */
+export declare abstract class FacetDurableObject<Env = unknown> extends DurableObject<Env, FacetProps> {
+    /** What a caller may reach by itx expression: the FIRST step of `itx.facets.get(name).<step>…`, a
+     *  method or a property of this class. A subclass lists its own on top of its parent's:
+     *  `static override publicMethods = [...super.publicMethods, "send"]`. */
+    static publicMethods: readonly string[];
+    /** This class's `publicMethods`, for the context that loaded it — a static does not cross the
+     *  isolate. On no list: only the context asks it. */
+    listPublicMethods(): readonly string[];
+}
+/** The itx scope `withItx` hands its callback: a context's declared API (api.ts) — a capnweb stub
+ *  of apps/os'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 by its dotted surface (`.append`), which the platform's handle
+     *  and a loaded worker's alike answer — how an entity's processor cross-posts its certificate to
+     *  `/` (`withItx((itx) => itx.cd("/").append(certificate))`). 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 within the project. */
+    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 FacetDurableObject<Env> {
+    #private;
+    /** The reads a caller reaches on every processor: `fetch`, and the state caught up through the log
+     *  (`snapshot`, `liveSnapshot`) or awaited (`waitUntilProcessed`). What feeds the processor —
+     *  `processEventBatch`, `catchUpFromLog`, `revive` — is the platform's, never a caller's. */
+    static publicMethods: string[];
+    /** 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: 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 delivery loop's, when a row is configured or resumed). */
+    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 read: `{ 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 round trip on the itx scope, then RELEASE EVERYTHING IT REACHED: the get, and every call the
+     *  callback made through it — not only the last. A Workers-RPC value this facet leaves undisposed —
+     *  the `itx.cd(path)` of `itx.cd(path).append(…)`, the `cfArtifacts.get(p)` of `.remote()`, an
+     *  answer awaited inside the callback (`const { state } = await context.invoke(…)`), data included —
+     *  keeps THIS FACET running after its context is evicted, until V8 collects the value, which an
+     *  idle isolate may not do for many minutes: each new incarnation of the context reattaches to the
+     *  facet, and the object stays billed (measured 2026-09-23: a new website project's `/` and
+     *  `/repos/config` billed 60 s of every minute for 30 min with no request). The context's own
+     *  `invoke` cannot end this from its side: the facet holds the value (context-residency.e2e.test.ts,
+     *  "… does not outlive …"). 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 ConfigEventArgs = {
+    event: StreamEvent;
+    range: ScannedRange;
+    itx: ItxScope;
+};
+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;`
+     *  `x-itx-principal` is on a request only when a project member (or the operator) sent it, safe
+     *  to act on. A private route written by hand answers the platform's sign-in challenge, which
+     *  the edge turns into the sign-in for a page load (`auth.require` does the same):
+     *
+     *  ```js
+     *  if (!request.headers.get("x-itx-principal"))
+     *    return new Response("Sign in\n", { status: 401, headers: { "WWW-Authenticate": 'Bearer realm="iterate"' } });
+     *  ``` */
+    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>;
+    /** ONE round trip on the itx scope, then release the scope and every call made through it
+     *  (`StreamProcessorDurableObject.withItx` says why an undisposed step keeps a context billed). */
+    protected withItx<T>(call: (itx: ItxScope) => T): Promise<Awaited<T>>;
+    /** 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 — every Request on a host of the project (the project's configured ingress
+     *  target). The host's routing slug is in `x-iterate-routing-slug` (`notes` for
+     *  `notes--<project>.<hostname>`; absent on the apex), written only by the platform: route on it
+     *  in plain code, answering here (reaching the context through `this.withItx`) or forwarding the
+     *  Request. Default: not found. */
+    fetch(_request: Request): Response | Promise<Response>;
+}
+export { RunContract, RunRequested, RunSettled } from "../stream/run.ts";

package/dist/sdk/record-pipelined-steps.d.ts

@@ -0,0 +1,19 @@
+/** ONE round trip on `entrypoint.get()`, then RELEASE EVERYTHING IT REACHED: the scope and every call
+ *  `call` made through it or through a handle it awaited, the last first. A release that throws is reported and the rest still run
+ *  (lib.ts `releaseRpcSessions`), so the call's answer stands. Data it answers stays usable; a stub or
+ *  handle it answers is released with the rest, so return data.
+ *
+ *    const { projectSlug } = await withItx(this.env.ITX, (itx) => itx.whoami());
+ */
+export declare function withItx<Scope, T>(entrypoint: {
+    get(): Scope;
+}, call: (itx: Scope) => T): Promise<Awaited<T>>;
+/** `stub` as the caller sees it, except that every CALL made through it — at any depth, on the stub,
+ *  on a call's result, or on the handle a call's result resolves to once awaited — is pushed onto
+ *  `steps`, so the caller can dispose each one: a Workers-RPC call's result is a stub-bearing promise
+ *  that keeps its session open until disposed, awaited or not. Awaiting hands back a handle (a stub
+ *  is callable, in workerd and capnweb alike) recorded and pushed too, and plain data untouched, so
+ *  data still copies across RPC. `catch`/`finally` and symbol members (`Symbol.dispose`) are the
+ *  value's own, bound to it, so disposing behaves exactly as on the bare stub; an argument that is
+ *  itself a recorded value crosses the wire as the stub it wraps. */
+export declare function recordPipelinedSteps<T>(stub: T, steps: unknown[]): T;