iterate 0.3.0 → 0.4.0

package/dist/sdk.mjs

@@ -1,2 +1,245 @@
-import { a as createProcessorHost, i as StreamProcessorFacet, n as IterateWorkerEntrypoint, o as itxProjectStream, r as StreamProcessorDurableObject, s as serveItx, t as IterateDurableObject } from "./sdk-DMB-IM11.mjs";
-export { IterateDurableObject, IterateWorkerEntrypoint, StreamProcessorDurableObject, StreamProcessorFacet, createProcessorHost, itxProjectStream, serveItx };
+import { applyPatch, diff, isSameOriginBrowserRequest, jsonEqual, releaseRpcSessions } from "./lib.mjs";
+import { LiveState, ProcessorEngine, ReduceCheckpointTable, StreamProcessor, defineProcessorContract } from "./stream/processor.mjs";
+import { ITX_PRINCIPAL_HEADER } from "./principal.mjs";
+import { RunContract, RunRequested, RunSettled } from "./stream/run.mjs";
+import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import { z, z as z$1 } from "zod";
+import { newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse } from "capnweb";
+//#region src/sdk/auth.ts
+const Principal = z$1.object({
+	actor: z$1.string().min(1),
+	email: z$1.string().optional()
+});
+/** 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. */
+const auth = { require(request) {
+	const isWebSocketUpgrade = request.headers.get("upgrade")?.toLowerCase() === "websocket";
+	if (!([
+		"GET",
+		"HEAD",
+		"OPTIONS"
+	].includes(request.method) && !isWebSocketUpgrade) && !isSameOriginBrowserRequest(request)) return new Response("Cross-site request refused", { status: 403 });
+	const principal = request.headers.get(ITX_PRINCIPAL_HEADER);
+	if (principal) {
+		Principal.parse(JSON.parse(principal));
+		return null;
+	}
+	return new Response("Sign in\n", {
+		status: 401,
+		headers: {
+			"WWW-Authenticate": "Bearer realm=\"iterate\"",
+			"Cache-Control": "no-store"
+		}
+	});
+} };
+//#endregion
+//#region src/sdk/record-pipelined-steps.ts
+/** 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());
+*/
+async function withItx(entrypoint, call) {
+	const steps = [];
+	const itx = entrypoint.get();
+	try {
+		return await call(recordPipelinedSteps(itx, steps));
+	} finally {
+		releaseRpcSessions([itx, ...steps]);
+	}
+}
+/** `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. */
+function recordPipelinedSteps(stub, steps) {
+	const wrapped = /* @__PURE__ */ new WeakMap();
+	const record = (value, receiver) => {
+		if (!value || typeof value !== "object" && typeof value !== "function") return value;
+		const proxy = new Proxy(value, {
+			get(target, key) {
+				const member = Reflect.get(target, key);
+				if (key === "then" && typeof member === "function") return (onFulfilled, onRejected) => Reflect.apply(member, target, [typeof onFulfilled === "function" ? (answer) => {
+					if (typeof answer !== "function") return onFulfilled(answer);
+					steps.push(answer);
+					return onFulfilled(record(answer, void 0));
+				} : onFulfilled, onRejected]);
+				if (typeof key === "symbol" || key === "then" || key === "catch" || key === "finally") return typeof member === "function" ? member.bind(target) : member;
+				return record(member, target);
+			},
+			apply(target, _proxyReceiver, args) {
+				const result = Reflect.apply(target, receiver, args.map((arg) => wrapped.get(Object(arg)) ?? arg));
+				steps.push(result);
+				return record(result, void 0);
+			}
+		});
+		wrapped.set(proxy, value);
+		return proxy;
+	};
+	return record(stub, void 0);
+}
+//#endregion
+//#region src/sdk/index.ts
+/** 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. */
+var FacetDurableObject = class extends DurableObject {
+	/** 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 = ["fetch"];
+	/** 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() {
+		return this.constructor.publicMethods;
+	}
+};
+var StreamProcessorDurableObject = class extends FacetDurableObject {
+	/** 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 = [
+		...super.publicMethods,
+		"snapshot",
+		"liveSnapshot",
+		"waitUntilProcessed"
+	];
+	/** 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. */
+	publishLiveState() {
+		this.#engine.publishLiveState();
+	}
+	/** THE push: the context hands over each committed batch with its scanned-range proof. */
+	processEventBatch(events, range) {
+		return this.#engine.processEventBatch(events, range);
+	}
+	/** Catch up from the log (the delivery loop's, when a row is configured or resumed). */
+	catchUpFromLog() {
+		return this.#engine.catchUpFromLog();
+	}
+	/** 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() {
+		return this.#engine.revive();
+	}
+	/** Caught up through the log, then `{ offset, state }`. */
+	snapshot() {
+		return this.#engine.snapshot();
+	}
+	/** The live-state seed read: `{ rev, state: projectLiveState(reduced) }`. */
+	liveSnapshot() {
+		return this.#engine.liveSnapshot();
+	}
+	/** The barrier: resolves once processed at least through `offset` (default timeout 10s). */
+	waitUntilProcessed(input) {
+		return this.#engine.waitUntilProcessed(input);
+	}
+	/** The loopback to this facet's context: a LOADED class gets it as `env.ITX` (the loader bakes the
+	*  stub in, worker-loader.ts); a class of THIS worker hosted through `ctx.exports` has the
+	*  worker's real env and mints the same stub itself from its props — `ctx.exports` is populated
+	*  inside a facet (__workers-tests__/facet-props.test.ts). */
+	#itxEntrypoint() {
+		return this.env.ITX ?? this.ctx.exports.ItxEntrypoint({ props: {
+			iterateContextName: this.ctx.props.iterateContextName,
+			platform: true
+		} });
+	}
+	#engineBuiltOnFirstUse;
+	get #engine() {
+		return this.#engineBuiltOnFirstUse ??= new ProcessorEngine(this.processor, {
+			stream: {
+				append: (...events) => this.withItx((itx) => itx.append(...events)),
+				read: (after, limit) => this.withItx((itx) => itx.readEvents(after, limit)),
+				claim: (at) => this.withItx((itx) => itx.processors.claim(this.ctx.props.name, at))
+			},
+			storage: new ReduceCheckpointTable(this.ctx.storage.sql),
+			fedByPushes: this.ctx.props.fedByPushes === true
+		});
+	}
+	/** 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. */
+	withItx(call) {
+		return withItx(this.#itxEntrypoint(), call);
+	}
+};
+var ConfigWorker = class extends WorkerEntrypoint {
+	/** 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"' } });
+	*  ``` */
+	auth = auth;
+	/** Process an explicitly subscribed batch with this worker's context scope. */
+	async processEventBatch(events, range) {
+		await this.withItx(async (itx) => {
+			for (const event of events) await this.processEvent({
+				event,
+				range,
+				itx
+			});
+		});
+	}
+	/** 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). */
+	withItx(call) {
+		return withItx(this.env.ITX, call);
+	}
+	/** 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) {}
+	/** 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) {
+		return new Response("Not found\n", { status: 404 });
+	}
+};
+//#endregion
+export { ConfigWorker, FacetDurableObject, LiveState, RunContract, RunRequested, RunSettled, StreamProcessor, StreamProcessorDurableObject, applyPatch, defineProcessorContract, diff, jsonEqual, newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, withItx, z };
+
+//# sourceMappingURL=sdk.mjs.map

package/dist/sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.mjs","names":["z","#engine","#engineBuiltOnFirstUse","#itxEntrypoint"],"sources":["../src/sdk/auth.ts","../src/sdk/record-pipelined-steps.ts","../src/sdk/index.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { isSameOriginBrowserRequest } from \"../lib.ts\";\nimport { ITX_PRINCIPAL_HEADER } from \"../principal.ts\";\n\nconst Principal = z.object({ actor: z.string().min(1), email: z.string().optional() });\n\n/** Project ingress strips public identity headers and stamps `x-itx-principal` for a project member\n *  only: a visitor signed out, signed in without this project, or riding a session cookie on a\n *  cross-site write arrives without one. This guard runs in the config worker, before it proxies an\n *  app.\n *\n *  Signed out, every request gets `401` with `WWW-Authenticate: Bearer realm=\"iterate\"`: the\n *  platform's edge turns that answer into the sign-in for a page load (or into \"sign in again with\n *  this project\" for someone signed in without it), whatever path the app is served under, and hands\n *  a fetch, a write or a WebSocket upgrade the 401 itself. Any app can ask for a signed-in visitor\n *  the same way:\n *\n *  ```js\n *  if (!request.headers.get(\"x-itx-principal\"))\n *    return new Response(\"Sign in\\n\", { status: 401, headers: { \"WWW-Authenticate\": 'Bearer realm=\"iterate\"' } });\n *  ```\n *\n *  A write or a WebSocket upgrade must also come from this origin (or carry no Origin, a non-browser\n *  client), else 403. The edge already sends such a cookie request on anonymous; this repeats the\n *  check where the app runs. The handshake is a GET, but it opens a two-way channel, and the app\n *  session cookie is `SameSite=Lax`: every `<routingSlug>--<project>.iterate.app` host is same-site with\n *  every other, so a page on another project's host could otherwise open a socket to this app with\n *  the visitor's cookie. */\nexport const auth = {\n  require(request: Request): Response | null {\n    const isWebSocketUpgrade = request.headers.get(\"upgrade\")?.toLowerCase() === \"websocket\";\n    const isRead = [\"GET\", \"HEAD\", \"OPTIONS\"].includes(request.method) && !isWebSocketUpgrade;\n    if (!isRead && !isSameOriginBrowserRequest(request))\n      return new Response(\"Cross-site request refused\", { status: 403 });\n    const principal = request.headers.get(ITX_PRINCIPAL_HEADER);\n    if (principal) {\n      Principal.parse(JSON.parse(principal)); // Platform-owned stamp; malformed means a defect.\n      return null;\n    }\n    return new Response(\"Sign in\\n\", {\n      status: 401,\n      headers: { \"WWW-Authenticate\": 'Bearer realm=\"iterate\"', \"Cache-Control\": \"no-store\" },\n    });\n  },\n};\n","// sdk/record-pipelined-steps.ts — `withItx`, THE one way code reaches its context: ONE round trip on\n// `env.ITX`, then RELEASE a Workers-RPC round trip completely — the scope and every call it made, not\n// only the last. Loaded code imports it from \"./processor.js\" (`withItx(this.env.ITX, (itx) => …)`); the\n// SDK's hosts (`StreamProcessorDurableObject.withItx`, `ConfigWorker.withItx`) delegate to it. No\n// workerd import, so the unit tests run it in node (record-pipelined-steps.test.ts) and the platform\n// bundles it alone for a script's isolate (apps/os `runScriptModule`); on native RpcPromises it is\n// proven by every apps/os e2e row that reaches a facet, and pinned by\n// apps/os/e2e/context-residency.e2e.test.ts (\"… does not outlive …\": a facet that kept one value from\n// its context stayed running, billed). Lint refuses the raw `env.ITX.get()` (iterate/no-raw-itx-get).\n\nimport { releaseRpcSessions } from \"../lib.ts\";\n\n/** ONE round trip on `entrypoint.get()`, then RELEASE EVERYTHING IT REACHED: the scope and every call\n *  `call` made through it or through a handle it awaited, the last first. A release that throws is reported and the rest still run\n *  (lib.ts `releaseRpcSessions`), so the call's answer stands. Data it answers stays usable; a stub or\n *  handle it answers is released with the rest, so return data.\n *\n *    const { projectSlug } = await withItx(this.env.ITX, (itx) => itx.whoami());\n */\nexport async function withItx<Scope, T>(\n  entrypoint: { get(): Scope },\n  call: (itx: Scope) => T,\n): Promise<Awaited<T>> {\n  const steps: unknown[] = [];\n  const itx = entrypoint.get();\n  try {\n    return await call(recordPipelinedSteps(itx, steps));\n  } finally {\n    releaseRpcSessions([itx, ...steps]);\n  }\n}\n\n/** `stub` as the caller sees it, except that every CALL made through it — at any depth, on the stub,\n *  on a call's result, or on the handle a call's result resolves to once awaited — is pushed onto\n *  `steps`, so the caller can dispose each one: a Workers-RPC call's result is a stub-bearing promise\n *  that keeps its session open until disposed, awaited or not. Awaiting hands back a handle (a stub\n *  is callable, in workerd and capnweb alike) recorded and pushed too, and plain data untouched, so\n *  data still copies across RPC. `catch`/`finally` and symbol members (`Symbol.dispose`) are the\n *  value's own, bound to it, so disposing behaves exactly as on the bare stub; an argument that is\n *  itself a recorded value crosses the wire as the stub it wraps. */\nexport function recordPipelinedSteps<T>(stub: T, steps: unknown[]): T {\n  const wrapped = new WeakMap<object, object>();\n  const record = (value: unknown, receiver: unknown): unknown => {\n    // oxlint-disable-next-line iterate/simple-truthiness-check -- a Proxy target must be an object or a function: a call may answer any value, and only those two can be wrapped\n    if (!value || (typeof value !== \"object\" && typeof value !== \"function\")) return value;\n    const proxy = new Proxy(value, {\n      get(target, key) {\n        const member: unknown = Reflect.get(target, key);\n        if (key === \"then\" && typeof member === \"function\")\n          // `const repo = await itx.repos.get(p); await repo.whoami()`: disposing the step releases\n          // `repo` (workerd disposes a promise's result with it), never `whoami`'s call, and an\n          // awaited property (`await itx.repos`) is no step at all.\n          return (onFulfilled?: unknown, onRejected?: unknown) =>\n            Reflect.apply(member, target, [\n              typeof onFulfilled === \"function\"\n                ? (answer: unknown) => {\n                    if (typeof answer !== \"function\") return onFulfilled(answer);\n                    steps.push(answer);\n                    return onFulfilled(record(answer, undefined));\n                  }\n                : onFulfilled,\n              onRejected,\n            ]);\n        if (typeof key === \"symbol\" || key === \"then\" || key === \"catch\" || key === \"finally\")\n          return typeof member === \"function\" ? member.bind(target) : member;\n        return record(member, target);\n      },\n      apply(target, _proxyReceiver, args: unknown[]) {\n        // Only a callable target reaches this trap; the call runs on the unwrapped receiver, as\n        // `stub.method(…)` would have.\n        const result: unknown = Reflect.apply(\n          target as (...args: unknown[]) => unknown,\n          receiver,\n          // `Object(arg)` is a fresh wrapper for a primitive, so only a recorded value is found.\n          args.map((arg) => wrapped.get(Object(arg)) ?? arg),\n        );\n        steps.push(result);\n        return record(result, undefined);\n      },\n    });\n    wrapped.set(proxy, value);\n    return proxy;\n  };\n  // The proxy answers every member the stub does (it forwards each one), so it is the stub's type.\n  return record(stub, undefined) as T;\n}\n","// sdk/index.ts — THE userspace SDK surface, bundled (zod included — the owner's call) into every\n// loaded isolate as `processor.js` (apps/os/scripts/build.ts bundles it):\n//\n//   import { StreamProcessor, StreamProcessorDurableObject, defineProcessorContract, z } from \"./processor.js\";\n//\n// The workerd HOSTS live here too (this file imports cloudflare:workers; the Node unit tests never import it):\n//   FacetDurableObject           — the `DurableObject` shell a context hosts as a facet: its class lists\n//                                  the methods a caller reaches by itx expression (`publicMethods`)\n//   StreamProcessorDurableObject — the facet shell that hosts ONE `StreamProcessor`\n//   ConfigWorker                 — the stateless `WorkerEntrypoint` a project's one event handler extends\n\nimport { DurableObject, WorkerEntrypoint } from \"cloudflare:workers\";\nimport type { IterateContextApi, StreamPage } from \"../api.ts\";\nimport {\n  ProcessorEngine,\n  type ScannedRange,\n  type StreamProcessor,\n  ReduceCheckpointTable,\n  type StreamEvent,\n  type StreamEventInput,\n} from \"../stream/processor.ts\";\nimport { auth } from \"./auth.ts\";\nimport { withItx } from \"./record-pipelined-steps.ts\";\n// THE ONE WAY code reaches its context: `withItx(this.env.ITX, (itx) => …)` — one round trip, then\n// everything it reached released (record-pipelined-steps.ts). A host's `this.withItx(fn)` is the same\n// function. Never `env.ITX.get()` alone: whatever it hands out keeps this isolate, and the object\n// hosting it, running and billed after the context is evicted (lint: iterate/no-raw-itx-get).\nexport { withItx };\nexport {\n  // LIVE STATE for a mini-app DO that is NOT a processor (a processor's base owns one internally):\n  // `new LiveState({ append: (e) => withItx(this.env.ITX, (itx) => itx.append(e)) }, \"chat\", {…})` — a\n  // field initializer cannot await — then `set` to mutate and `snapshot()` as the client's seed read\n  // (stream/processor.ts).\n  LiveState,\n  StreamProcessor,\n  defineProcessorContract,\n  type ConsumedEvent,\n  type EventCatalog,\n  type EventDefinition,\n  type EmittedEventInput,\n  type EventInput,\n  type LiveStateSink,\n  type ProcessorContract,\n  type ProcessorState,\n  type ProcessorStream,\n  type ProcessEventArgs,\n  type ReduceArgs,\n  type ScannedRange,\n  type StreamEvent,\n  type StreamEventInput,\n} from \"../stream/processor.ts\";\nexport { z } from \"zod\";\n// capnweb's CLIENT constructors, so userspace can dial a remote capnweb API from inside its isolate\n// through the context's own egress, and `newWorkersRpcResponse`, the SERVER half, so a loaded worker\n// can serve a capnweb API over its `fetch`. The HTTP batch is exported ON PURPOSE beside the\n// WebSocket session: a stateless entrypoint answering one method with one remote call has no session\n// to hold across calls, and a one-shot POST is the honest shape (the lint rule targets long-lived workers).\n// oxlint-disable-next-line iterate/no-capnweb-http-batch -- userspace one-shot remote calls; see above\nexport { newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse } from \"capnweb\";\nexport { applyPatch, diff, jsonEqual, type PatchOp } from \"../lib.ts\";\n// ── StreamProcessorDurableObject ── THE SDK HOST: the `DurableObject` shell that hosts ONE\n// `StreamProcessor` as a facet of its context. An author writes the pure processor and its host,\n// one line long:\n//\n//   export class PresenceDurableObject extends StreamProcessorDurableObject {\n//     processor = new PresenceProcessor();\n//   }\n//\n// hosted through the ordinary `itx.facets.get('presence', { source, className: 'PresenceDurableObject' })`\n// — a processor is a named facet that additionally gets pushed every commit. `processor` is a FIELD\n// so it can take what its effects need from this object — reach as a `WithItx` accessor, never a\n// scope: `new Notifier((call) => this.withItx(call))` — and so the same class is constructed bare in\n// a test. A method of the host's own that callers reach by itx expression goes on its list:\n// `static override publicMethods = [...super.publicMethods, \"message\"]`.\n//\n// IDENTITY is `ctx.props` — `{ iterateContextName, name }`, minted by the parent, the only party\n// that knows it (pinned in __workers-tests__/facet-props.test.ts), plus `fedByPushes` when a row\n// pushes it (FacetProps). THE STREAM is the itx scope `this.withItx(fn)` hands `fn` (apps/os\n// iterate-context.ts `ItxEntrypoint`); the engine's `append`/`read` ride it like any other dotted call.\n//\n// NEVER define alarm(): facets have none (workerd#6810 — the runtime answers \"Facets currently\n// cannot set alarms.\"); a timer, when one is needed, is a scheduled append on the context. The\n// engine's own recovery is a CLAIM on the context's alarm (processor.ts, rule 3): while a\n// `runInBackground` attempt is in flight the context owes this facet a `revive()`, so a host that\n// dies mid-attempt is re-materialized and runs its at-head pass again\n// (__workers-tests__/agent-revive.test.ts: an LLM call survives its context's death).\n//\n// THE CLAIM IS ALSO WHAT KEEPS A FACET RUNNING: a loaded facet that holds none when its context\n// starts a new incarnation is reset then (os FacetHost `resetUnclaimedLoadedFacets`). So work that\n// must outlive the call that started it — a model request, a retry's backoff sleep, an open\n// provider socket — runs through `runInBackground` (ProcessEventArgs), never as a bare floating\n// promise, a `ctx.waitUntil` or a timer the facet keeps on its own.\n\n/** What the parent mints a facet's class with — the whole identity, and one fact about its feed. */\nexport type FacetProps = {\n  iterateContextName: string;\n  name: string;\n  /** Set when, as this facet started, a subscription row of its context pushed it every commit it\n   *  consumes (`processEventBatch`, the delivery loop's push): a processor's engine then trusts the\n   *  head a catch-up read until the next push (stream/processor.ts, the read verbs). Absent, only a\n   *  push is proof, so a processor no row pushes reads its log on every read. */\n  fedByPushes?: true;\n};\n\n/** THE FACET SHELL: a `DurableObject` a context hosts as a facet — `itx.facets.get(name, { source,\n *  className })`, a rule naming it, or a processor's row. A caller reaches a facet by itx expression\n *  (`itx.facets.get(name).<method>(…)`) only through what its class lists in `publicMethods`: the\n *  context refuses any other first step FORBIDDEN before the call reaches the facet\n *  (apps/os context/facet-public-methods.ts). The platform's own calls — the delivery loop's push\n *  and catch-up, the alarm's revive — never go through the list. A loaded class that does not\n *  extend this shell lists nothing, so no caller reaches it by expression. */\nexport abstract class FacetDurableObject<Env = unknown> extends DurableObject<Env, FacetProps> {\n  /** What a caller may reach by itx expression: the FIRST step of `itx.facets.get(name).<step>…`, a\n   *  method or a property of this class. A subclass lists its own on top of its parent's:\n   *  `static override publicMethods = [...super.publicMethods, \"send\"]`. */\n  static publicMethods: readonly string[] = [\"fetch\"];\n\n  /** This class's `publicMethods`, for the context that loaded it — a static does not cross the\n   *  isolate. On no list: only the context asks it. */\n  listPublicMethods(): readonly string[] {\n    // `this.constructor` is the concrete facet class, a subclass of this one; TypeScript types it as\n    // `Function`, which has no `publicMethods`.\n    return (this.constructor as typeof FacetDurableObject).publicMethods;\n  }\n}\n\n/** The itx scope `withItx` hands its callback: a context's declared API (api.ts) — a capnweb stub\n *  of apps/os's `IterateContextRpcTarget`, which satisfies it. */\nexport type ItxScope = IterateContextApi;\n/** What hands the scope over: the loopback entrypoint a loaded worker has as `env.ITX`, or the one a\n *  class of the platform's own worker mints from `ctx.exports`. */\nexport type ItxEntrypointService = { get(): ItxScope };\n/** The least a host needs of its scope: the fixed-point log calls the engine makes. The platform's own\n *  facets pass the Workers-RPC STUB of a context (every dotted step pipelined; a property there is a\n *  promise), which no plain-promise interface can name — so the constraint is this, not `ItxScope`. */\nexport type ProcessorScope = {\n  append(...events: StreamEventInput[]): Promise<unknown>;\n  readEvents(afterOffset?: number, limit?: number): Promise<unknown>;\n  /** The engine's claim on the context's alarm (processor.ts rule 3): \"come back by `at`\", or null. */\n  processors: { claim(name: string, at: number | null): Promise<unknown> };\n  /** Another context of the project by its dotted surface (`.append`), which the platform's handle\n   *  and a loaded worker's alike answer — how an entity's processor cross-posts its certificate to\n   *  `/` (`withItx((itx) => itx.cd(\"/\").append(certificate))`). Through the table like every other\n   *  word here: a loaded processor's `cd` goes down only (the app wall), the platform's own go\n   *  anywhere within the project. */\n  cd(path: string): { append(...events: StreamEventInput[]): Promise<unknown> };\n};\n\n/** THE SCOPE ACCESSOR a host hands its processor: one pipelined round trip on the context's itx,\n *  released after (`StreamProcessorDurableObject.withItx`). A processor that needs an effect —\n *  `itx.cfArtifacts.create(path)`, `itx.ai.run(…)` — takes this and nothing else, so a unit test\n *  hands it a fake and the e2e lends one by rule on the context. */\nexport type WithItx<Scope = ItxScope> = <T>(call: (itx: Scope) => T) => Promise<Awaited<T>>;\n\nexport abstract class StreamProcessorDurableObject<\n  State = unknown,\n  Env extends { ITX?: ItxEntrypointService } = { ITX: ItxEntrypointService },\n  Scope extends ProcessorScope = ItxScope,\n> extends FacetDurableObject<Env> {\n  /** The reads a caller reaches on every processor: `fetch`, and the state caught up through the log\n   *  (`snapshot`, `liveSnapshot`) or awaited (`waitUntilProcessed`). What feeds the processor —\n   *  `processEventBatch`, `catchUpFromLog`, `revive` — is the platform's, never a caller's. */\n  static override publicMethods = [\n    ...super.publicMethods,\n    \"snapshot\",\n    \"liveSnapshot\",\n    \"waitUntilProcessed\",\n  ];\n\n  /** The processor this object hosts — `processor = new PresenceProcessor()` at the top of the subclass. */\n  abstract readonly processor: StreamProcessor<State>;\n\n  // ── what an author reaches (the itx scope: `this.withItx(fn)`; identity: `this.ctx.props`) ──\n\n  /** After a runtime field on the processor moved OUTSIDE a batch (an RPC method on this object);\n   *  inside `processEvent` the engine re-projects on its own. */\n  protected publishLiveState(): void {\n    this.#engine.publishLiveState();\n  }\n\n  // ── what the platform calls: the delivery loop's push and catch-up, the alarm's revive ──\n\n  /** THE push: the context hands over each committed batch with its scanned-range proof. */\n  processEventBatch(events: StreamEvent[], range: ScannedRange): Promise<void> {\n    return this.#engine.processEventBatch(events, range);\n  }\n  /** Catch up from the log (the delivery loop's, when a row is configured or resumed). */\n  catchUpFromLog(): Promise<void> {\n    return this.#engine.catchUpFromLog();\n  }\n  /** THE REVIVE: the context's alarm pass calls it for a due claim — catch up, then run the\n   *  at-head pass, so an attempt the last incarnation was running is started again from state. */\n  revive(): Promise<void> {\n    return this.#engine.revive();\n  }\n\n  // ── what a caller reaches by itx expression (`publicMethods`) ──\n\n  /** Caught up through the log, then `{ offset, state }`. */\n  snapshot(): Promise<{ offset: number; state: State }> {\n    return this.#engine.snapshot();\n  }\n  /** The live-state seed read: `{ rev, state: projectLiveState(reduced) }`. */\n  liveSnapshot(): Promise<{ rev: number; state: unknown }> {\n    return this.#engine.liveSnapshot();\n  }\n  /** The barrier: resolves once processed at least through `offset` (default timeout 10s). */\n  waitUntilProcessed(input: { offset: number; timeoutMs?: number }): Promise<void> {\n    return this.#engine.waitUntilProcessed(input);\n  }\n\n  /** The loopback to this facet's context: a LOADED class gets it as `env.ITX` (the loader bakes the\n   *  stub in, worker-loader.ts); a class of THIS worker hosted through `ctx.exports` has the\n   *  worker's real env and mints the same stub itself from its props — `ctx.exports` is populated\n   *  inside a facet (__workers-tests__/facet-props.test.ts). */\n  #itxEntrypoint(): { get(): Scope } {\n    return (this.env.ITX ??\n      (\n        this.ctx.exports as unknown as {\n          ItxEntrypoint: (options: { props: object }) => ItxEntrypointService;\n        }\n      ).ItxEntrypoint({\n        // PLATFORM: this worker's own class, minted from its own exports — the full handle, the fixed\n        // point spellable, `cd` free to go up. A LOADED class never reaches this branch (it has\n        // `env.ITX`, baked in by the loader, and its own module's exports).\n        props: { iterateContextName: this.ctx.props.iterateContextName, platform: true },\n      })) as unknown as {\n      get(): Scope;\n    };\n  }\n  // ── the engine: one ProcessorEngine over `processor` and this object's storage, built on first use —\n  // `processor` is a subclass field, which does not exist yet while this base class constructs. ──\n  #engineBuiltOnFirstUse?: ProcessorEngine<State>;\n  get #engine(): ProcessorEngine<State> {\n    return (this.#engineBuiltOnFirstUse ??= new ProcessorEngine(this.processor, {\n      // The engine's own emits, catch-up and gap repair are the CONTEXT ROOTS `append`, `readEvents`,\n      // `processors.claim` — implicit in every context (itx-expression-rewriting.ts rule 3), so they\n      // resolve to this log with no row and no hop; a row at `itx.append` is the OWNER's deliberate\n      // wall (a jailed processor halts visibly), never a loaded worker's — the fixed point is not a\n      // loaded worker's word.\n      stream: {\n        // A stub scope's answers are pipelined shapes by type and plain data on the wire (the\n        // engine awaits them): the engine's own types, asserted.\n        append: (...events) =>\n          this.withItx((itx) => itx.append(...events)) as Promise<StreamEvent[]>,\n        read: (after, limit) =>\n          this.withItx((itx) => itx.readEvents(after, limit)) as Promise<StreamPage>,\n        claim: (at) => this.withItx((itx) => itx.processors.claim(this.ctx.props.name, at)),\n      },\n      storage: new ReduceCheckpointTable(this.ctx.storage.sql),\n      fedByPushes: this.ctx.props.fedByPushes === true,\n    }));\n  }\n\n  /** ONE round trip on the itx scope, then RELEASE EVERYTHING IT REACHED: the get, and every call the\n   *  callback made through it — not only the last. A Workers-RPC value this facet leaves undisposed —\n   *  the `itx.cd(path)` of `itx.cd(path).append(…)`, the `cfArtifacts.get(p)` of `.remote()`, an\n   *  answer awaited inside the callback (`const { state } = await context.invoke(…)`), data included —\n   *  keeps THIS FACET running after its context is evicted, until V8 collects the value, which an\n   *  idle isolate may not do for many minutes: each new incarnation of the context reattaches to the\n   *  facet, and the object stays billed (measured 2026-09-23: a new website project's `/` and\n   *  `/repos/config` billed 60 s of every minute for 30 min with no request). The context's own\n   *  `invoke` cannot end this from its side: the facet holds the value (context-residency.e2e.test.ts,\n   *  \"… does not outlive …\"). Protected: a host with methods of its own (the workspace,\n   *  src/workspace/durable-object.ts) reaches its context the same way. */\n  protected withItx<T>(call: (itx: Scope) => T): Promise<Awaited<T>> {\n    return withItx(this.#itxEntrypoint(), call);\n  }\n}\n\n// ConfigWorker is a stateless event handler loaded with an explicit workers.get spec.\n// Subscribe its processEventBatch method explicitly; fetch routing is configured separately.\nexport type ConfigEventArgs = { event: StreamEvent; range: ScannedRange; itx: ItxScope };\n\nexport abstract class ConfigWorker<\n  Env extends { ITX: ItxEntrypointService } = { ITX: ItxEntrypointService },\n> extends WorkerEntrypoint<Env> {\n  /** At fetch entry: `const denied = this.auth.require(request); if (denied) return denied;`\n   *  `x-itx-principal` is on a request only when a project member (or the operator) sent it, safe\n   *  to act on. A private route written by hand answers the platform's sign-in challenge, which\n   *  the edge turns into the sign-in for a page load (`auth.require` does the same):\n   *\n   *  ```js\n   *  if (!request.headers.get(\"x-itx-principal\"))\n   *    return new Response(\"Sign in\\n\", { status: 401, headers: { \"WWW-Authenticate\": 'Bearer realm=\"iterate\"' } });\n   *  ``` */\n  protected readonly auth = auth;\n  /** Process an explicitly subscribed batch with this worker's context scope. */\n  async processEventBatch(events: StreamEvent[], range: ScannedRange): Promise<void> {\n    await this.withItx(async (itx) => {\n      for (const event of events) {\n        await this.processEvent({ event, range, itx });\n      }\n    });\n  }\n\n  /** ONE round trip on the itx scope, then release the scope and every call made through it\n   *  (`StreamProcessorDurableObject.withItx` says why an undisposed step keeps a context billed). */\n  protected withItx<T>(call: (itx: ItxScope) => T): Promise<Awaited<T>> {\n    return withItx(this.env.ITX, call);\n  }\n\n  /** THE AUTHOR HOOK — one event at a time, in offset order. Append reactions through the itx scope;\n   *  make them idempotent (a redelivery must be a no-op). Default: ignore the event. */\n  processEvent(_args: ConfigEventArgs): void | Promise<void> {}\n\n  /** THE WEB ROOT — every Request on a host of the project (the project's configured ingress\n   *  target). The host's routing slug is in `x-iterate-routing-slug` (`notes` for\n   *  `notes--<project>.<hostname>`; absent on the apex), written only by the platform: route on it\n   *  in plain code, answering here (reaching the context through `this.withItx`) or forwarding the\n   *  Request. Default: not found. */\n  override fetch(_request: Request): Response | Promise<Response> {\n    return new Response(\"Not found\\n\", { status: 404 });\n  }\n}\n\nexport { RunContract, RunRequested, RunSettled } from \"../stream/run.ts\";\n"],"mappings":"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"}

package/dist/{next/stream → stream}/processor.d.ts

@@ -1,6 +1,5 @@
 import type { SqlStorageValue } from "@cloudflare/workers-types";
 import { z } from "zod";
-import { jsonEqual } from "../lib.ts";
 /** What a processor declares: its checkpoint slug and reducer version, what it consumes and emits,
  *  and its initial state (`defineProcessorContract` below builds one from zod schemas). */
 export type ProcessorContract<State = unknown> = {
@@ -27,9 +26,6 @@ export type ProcessorContract<State = unknown> = {
  *  says whether the page was cut; its length says nothing (a budget cut is short of `limit`). */
 export type ProcessorStream = {
     append(...events: StreamEventInput[]): Promise<StreamEvent[]> | StreamEvent[];
-    /** Append onto ANOTHER context of the same project, by path — how an entity's processor lands its
-     *  birth certificate on `/` for the project catalog. A stand-in with one path may omit it. */
-    appendTo?(path: string, ...events: StreamEventInput[]): Promise<StreamEvent[]> | StreamEvent[];
     read(afterOffset?: number, limit?: number): Promise<{
         events: StreamEvent[];
         scannedThroughOffset: number;
@@ -54,8 +50,8 @@ export type ReduceArgs<State, Event = StreamEvent> = {
     state: State;
 };
 export type ProcessEventArgs<State, Event = StreamEvent, 
-/** What `append`/`appendTo` take: `EmittedEventInput<typeof Contract>` for a processor that
- *  declares one — each type the contract `emits`, its payload as the catalog spells it. */
+/** What `append` takes: `EmittedEventInput<typeof Contract>` for a processor that declares one —
+ *  each type the contract `emits`, its payload as the catalog spells it. */
 Emitted extends StreamEventInput = StreamEventInput> = {
     /** The consumed event — or `null` for the eventless at-head pass. */
     event: Event | null;
@@ -66,8 +62,6 @@ Emitted extends StreamEventInput = StreamEventInput> = {
      *  assignable to `StreamProcessor<State>` (the host's field), and only method parameters are
      *  compared bivariantly. */
     append(...events: Emitted[]): Promise<StreamEvent[]>;
-    /** The same, onto the context at `path` (apps/os's `appendTo`): a certificate cross-posted to `/`. */
-    appendTo(path: string, ...events: Emitted[]): Promise<StreamEvent[]>;
     /** Hold the cursor until `work` settles; FIFO with other blockers of the SAME event. */
     blockProcessorWhile: (work: () => Promise<unknown>) => void;
     /** Fire-and-forget attempt; may overtake later events; outcome must be state-recoverable. */
@@ -80,8 +74,8 @@ Emitted extends StreamEventInput = StreamEventInput> = {
  *  reduces all call this; there is no second copy to drift. `consumes` undefined = every durable event
  *  (a subscriber's default). "*" = every durable event. A NAMED type opts that type in, INCLUDING
  *  ephemerals ("*" NEVER sweeps ephemerals) — so a live-state watcher spells
- *  `consumes: ["events.iterate.com/live-state/changed"]` and filters `payload.key` itself. The wake
- *  record (`stream/woken`) is a durable event like any other: a "*" row receives every incarnation's. */
+ *  `consumes: ["events.iterate.com/itx/live-state-changed"]` and filters `payload.key` itself. The wake
+ *  record (`itx/woken`) is a durable event like any other: a "*" row receives every incarnation's. */
 export declare function consumesEvent(consumes: readonly string[] | undefined, event: {
     type: string;
     ephemeral?: boolean;
@@ -97,7 +91,7 @@ export declare abstract class StreamProcessor<State, Event extends StreamEvent =
      *  untyped `StreamEvent` for processors that don't declare one. */
     reduce(_args: ReduceArgs<State, Event>): State | null | undefined;
     /** Side-effect hook. Synchronous by design: register async work via the two helpers on args.
-     *  `append`/`appendTo` take what THIS class's `contract` emits (`EmittedEventInput<this["contract"]>`:
+     *  `append` takes what THIS class's `contract` emits (`EmittedEventInput<this["contract"]>`:
      *  a subclass whose `contract` is a defined one gets each emitted type's payload as its catalog
      *  spells it; the base, and a hand-built contract, take any input). */
     processEvent(_args: ProcessEventArgs<State, Event, EmittedEventInput<this["contract"]>>): undefined;
@@ -120,8 +114,12 @@ export declare class ProcessorEngine<State> {
     constructor(processor: StreamProcessor<State>, deps: {
         stream: ProcessorStream;
         storage: ReduceCheckpointTable;
+        /** The host's word that a subscription row pushes this processor every commit it consumes
+         *  (`processEventBatch`). The read verbs then trust the head a catch-up read until a push shows
+         *  a later one; absent, only a push's head is trusted, so an unpushed processor reads each time. */
+        fedByPushes?: boolean;
     });
-    /** THE SEED DOOR for live-state clients (LiveState.snapshot), caught up first. */
+    /** THE SEED READ for live-state clients (LiveState.snapshot), caught up first. */
     liveSnapshot(): Promise<{
         rev: number;
         state: unknown;
@@ -130,7 +128,7 @@ export declare class ProcessorEngine<State> {
      *  calls this after every batch; the host calls it after a runtime field moved outside a batch. A
      *  throwing projection loses only its notification (the client re-seeds on the chain gap). */
     publishLiveState(): void;
-    /** THE push door: contiguous → reduce it directly (no read); anything else → gap repair from the
+    /** THE push method: contiguous → reduce it directly (no read); anything else → gap repair from the
      *  own cursor first. Fire-and-forget safe: enqueues on the serial chain. */
     processEventBatch(events: StreamEvent[], range: ScannedRange): Promise<void>;
     /** Catch up from the own checkpoint (a cold boot, the read verbs, the barrier), page by page — a
@@ -154,11 +152,11 @@ export declare class ProcessorEngine<State> {
      *  here claims again, later each time (20 s, 40 s, … `REVIVE_AFTER_MAX_MS`). */
     revive(): Promise<void>;
 }
-export { jsonEqual };
 /** What `append` accepts: the event body, before the stream assigns its committed identity. The
- *  door checks ONE rule by hand: `type` is a non-empty string. */
+ *  append method checks ONE rule by hand: `type` is a non-empty string. */
 export type StreamEventInput = {
-    /** Convention: `events.iterate.com/<domain>/<fact>`. */
+    /** `events.iterate.com/<namespace>/<event>` for the platform's types, named by the rules in
+     *  packages/iterate/README.md#event-types; any other string is the appender's own. */
     type: string;
     payload?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
@@ -188,12 +186,16 @@ export type StreamEventInput = {
         };
         /** THE CONNECTION the principal acted through: the OAuth grant's id — one per
          *  connected client (a Claude Code install, a dash sign-in, a personal token). Stamped beside
-         *  `principal` by the DO's append root (src/principal.ts); absent for the admin secret and the kernel. */
+         *  `principal` by the platform when it appends; absent for the admin secret and the kernel. */
         grant?: string;
+        /** THE PLATFORM WROTE THIS FACT, on the principal's behalf:
+         *  what a processor folding an account's or an organization's facts requires — a client can
+         *  append any type to a context it holds, never this. */
+        platform?: true;
     };
     /** Same key + same body = dedupe (the existing event is returned); different body = loud error. */
     idempotencyKey?: string;
-    /** OPTIONAL PRECONDITION (apps/os): land at exactly this offset or refuse the whole batch with
+    /** OPTIONAL PRECONDITION: land at exactly this offset or refuse the whole batch with
      *  OFFSET_CONFLICT — "nothing has happened since I last looked". Never stored in the body. */
     offset?: number;
     /** An EPHEMERAL event rides the stream to live subscribers but is NEVER persisted: it consumes an
@@ -225,7 +227,7 @@ export type ReduceCheckpoint<State> = {
     state: State | undefined;
 };
 /** What BOTH hosts read and write their checkpoints through — the stream's storage and a facet's
- *  own (the unit lane drives it over node:sqlite, stream/test-support.ts). */
+ *  own (the Node unit tests drive it over node:sqlite, stream/test-support.ts). */
 export declare class ReduceCheckpointTable {
     #private;
     /** `createTable: false` when the caller knows the table exists (the stream's storage skips every
@@ -242,7 +244,9 @@ export declare class ReduceCheckpointTable {
     }, state: State, stateChanged: boolean): void;
 }
 /** The only thing a LiveState needs from its host: somewhere to append the delta. A
- *  `ProcessorStream` and the itx scope both satisfy it. */
+ *  `ProcessorStream` satisfies it; a facet that is no processor passes one round trip per delta,
+ *  `{ append: (e) => withItx(this.env.ITX, (itx) => itx.append(e)) }` (sdk/index.ts), never a scope it
+ *  holds. */
 export type LiveStateSink = {
     append(event: {
         type: string;
@@ -255,7 +259,7 @@ export declare class LiveState<S> {
     constructor(sink: LiveStateSink, key: string, initial: S);
     /** The current value (reflects every `set`). */
     get(): S;
-    /** THE seed door: `{rev, state}` read together (single-threaded ⇒ atomically), which is what lets
+    /** THE seed read: `{rev, state}` read together (single-threaded ⇒ atomically), which is what lets
      *  a client chain patches exactly instead of guessing which changes its snapshot already contains. */
     snapshot(): {
         rev: number;
@@ -305,7 +309,7 @@ export type ConsumedEvent<Contract> = Contract extends {
     consumes: infer Consumes extends readonly string[];
 } ? EventForTypes<Events, DepsOf<Contract>, Consumes> : never;
 /** The input for ONE event type as a catalog spells it (`EventInput`'s row) — or, for a type no
- *  catalog defines (a core control event a processor emits, `project/ingress-configured`), the plain
+ *  catalog defines (a core control event a processor emits, `itx/ingress-configured`), the plain
  *  input: it widens the whole union, so a contract that emits one undefined type appends untyped
  *  until that type is in a catalog it depends on. */
 type EventInputForType<Events extends EventCatalog, Deps extends readonly unknown[], Type extends string> = Type extends unknown ? [DefinitionForType<Events, Deps, Type>] extends [never] ? StreamEventInput : DefinitionForType<Events, Deps, Type> extends {
@@ -322,7 +326,7 @@ type EventInputForType<Events extends EventCatalog, Deps extends readonly unknow
 } : {
     ephemeral?: never;
 }) : never : never;
-/** What a processor's `append`/`appendTo` take: one input per type the contract `emits` — its own
+/** What a processor's `append` takes: one input per type the contract `emits` — its own
  *  events and its deps' as their catalogs spell them (`z.input`), a type no catalog defines as the
  *  plain input under that name. A contract whose `emits` is not a literal tuple gets every input. */
 export type EmittedEventInput<Contract> = Contract extends {
@@ -376,3 +380,4 @@ export declare function defineProcessorContract<const StateSchema extends z.ZodT
     consumes: Consumes;
     emits: Emits;
 }): DefinedProcessorContract<StateSchema, Events, Consumes, Deps, Emits>;
+export {};