iterate 0.2.7 → 0.3.0

package/dist/next/sdk.mjs

@@ -0,0 +1,139 @@
+import { applyPatch, diff, jsonEqual } 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/next/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 the verified caller.
+* This guard runs locally in the config worker, before it proxies an app. */
+const auth = { require(request) {
+	const url = new URL(request.url);
+	if (![
+		"GET",
+		"HEAD",
+		"OPTIONS"
+	].includes(request.method)) {
+		const origin = request.headers.get("origin");
+		if (origin && origin !== url.origin) 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;
+	}
+	if (!["GET", "HEAD"].includes(request.method)) return new Response("Sign in first", { status: 401 });
+	return new Response(null, {
+		status: 302,
+		headers: {
+			Location: `/.auth/login?next=${encodeURIComponent(url.pathname + url.search)}`,
+			"Cache-Control": "no-store"
+		}
+	});
+} };
+//#endregion
+//#region src/next/sdk/index.ts
+var StreamProcessorDurableObject = class extends DurableObject {
+	/** 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 door: 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 read-your-writes entry after an eviction). */
+	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 door: `{ 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)),
+				appendTo: (path, ...events) => this.withItx((itx) => itx.cd(path).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)
+		});
+	}
+	/** ONE pipelined round trip on the itx scope, then RELEASE it: `env.ITX.get()` and the call
+	*  pipelined on it PIN THE PARENT DO until GC (the "GC is too late" defect the DO's facet door
+	*  fixes in the other direction). Await the answer — plain data, the wire already copied it —
+	*  then dispose the call AND the get. Protected: a host with methods of its own (the workspace,
+	*  src/workspace/durable-object.ts) reaches its context the same way. */
+	async withItx(call) {
+		const itx = this.#itxEntrypoint().get();
+		const result = call(itx);
+		try {
+			return await result;
+		} finally {
+			result[Symbol.dispose]?.();
+			itx[Symbol.dispose]?.();
+		}
+	}
+};
+var ConfigWorker = class extends WorkerEntrypoint {
+	/** At fetch entry: `const denied = this.auth.require(request); if (denied) return denied;` */
+	auth = auth;
+	/** Process an explicitly subscribed batch with this worker's context scope. */
+	async processEventBatch(events, range) {
+		const itx = this.env.ITX.get();
+		try {
+			for (const event of events) await this.processEvent({
+				event,
+				range,
+				itx
+			});
+		} finally {
+			itx[Symbol.dispose]?.();
+		}
+	}
+	/** 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 — the Request a project host with no app label rode in on (`x-iterate-app` absent;
+	*  the project's configured ingress target). Route by hostname to `this.env.ITX.get().apps.<x>.fetch(request)`
+	*  or answer it here. Default: not found. */
+	fetch(_request) {
+		return new Response("Not found\n", { status: 404 });
+	}
+};
+//#endregion
+export { ConfigWorker, LiveState, RunContract, RunRequested, RunSettled, StreamProcessor, StreamProcessorDurableObject, applyPatch, auth, defineProcessorContract, diff, jsonEqual, newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, z };
+
+//# sourceMappingURL=sdk.mjs.map

package/dist/next/sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.mjs","names":["z","#engine","#engineBuiltOnFirstUse","#itxEntrypoint"],"sources":["../../src/next/sdk/auth.ts","../../src/next/sdk/index.ts"],"sourcesContent":["import { z } from \"zod\";\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 the verified caller.\n * This guard runs locally in the config worker, before it proxies an app. */\nexport const auth = {\n  require(request: Request): Response | null {\n    const url = new URL(request.url);\n    if (![\"GET\", \"HEAD\", \"OPTIONS\"].includes(request.method)) {\n      const origin = request.headers.get(\"origin\");\n      if (origin && origin !== url.origin)\n        return new Response(\"Cross-site request refused\", { status: 403 });\n    }\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    if (![\"GET\", \"HEAD\"].includes(request.method))\n      return new Response(\"Sign in first\", { status: 401 });\n    return new Response(null, {\n      status: 302,\n      headers: {\n        Location: `/.auth/login?next=${encodeURIComponent(url.pathname + url.search)}`,\n        \"Cache-Control\": \"no-store\",\n      },\n    });\n  },\n};\n","// sdk/index.ts — THE userspace SDK surface, bundled (zod included — the owner's call) into every\n// loaded isolate as `processor.js` (os-next's scripts/vite-plugin-processor-sdk.ts bundles it):\n//\n//   import { StreamProcessor, StreamProcessorDurableObject, defineProcessorContract, z } from \"./processor.js\";\n//\n// The two workerd HOSTS live here too (this file imports cloudflare:workers; the node lane never imports it):\n//   StreamProcessorDurableObject — the `DurableObject` shell that hosts ONE `StreamProcessor` as a facet\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\";\nexport { auth };\nexport {\n  StreamProcessor,\n  defineProcessorContract,\n  jsonEqual,\n  type ConsumedEvent,\n  type EventCatalog,\n  type EventDefinition,\n  type EmittedEventInput,\n  type EventInput,\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// eslint-disable-next-line iterate/no-capnweb-http-batch -- userspace one-shot remote calls; see above\nexport { newHttpBatchRpcSession, newWebSocketRpcSession, newWorkersRpcResponse } from \"capnweb\";\nexport { applyPatch, diff, type PatchOp } from \"../lib.ts\";\nexport { LiveState, type LiveStateSink } from \"../stream/processor.ts\";\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) => env.ITX.get().append(e) }, \"chat\", {…})` — a field initializer\n// cannot await — then `set` to mutate and `snapshot()` as the client seed door (stream/processor.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 (`new Notifier(this.env.ITX)`), and so the\n// same class is constructed bare in a test.\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). THE STREAM is the itx scope\n// behind `env.ITX.get()` (iterate-context.ts `ItxEntrypoint`); the engine's `append`/`read` ride it like any other\n// 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/** What the parent mints the class with — the whole identity. */\nexport type StreamProcessorProps = { iterateContextName: string; name: string };\n\n/** The itx scope as `env.ITX.get()` hands it over: a context's declared API (api.ts) — a capnweb stub\n *  of os-next'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 — where `appendTo` lands — by its dotted surface (`.append`),\n   *  which the platform's handle and a loaded worker's alike answer. Through the table like every\n   *  other word here: a loaded processor's `cd` goes down only (the app wall), the platform's own\n   *  go anywhere. */\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 DurableObject<Env, StreamProcessorProps> {\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 is `this.env.ITX.get()`, typed; identity is `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  // ── the doors the delivery loop and `itx.facets.get(name)` reach ──\n\n  /** THE push door: 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 read-your-writes entry after an eviction). */\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  /** 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 door: `{ 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. `appendTo` is `cd` through the same table: a first-party saga (the\n      // platform's mint) reaches `/`; a loaded processor's `cd` goes down only.\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        appendTo: (path, ...events) =>\n          this.withItx((itx) => itx.cd(path).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    }));\n  }\n\n  /** ONE pipelined round trip on the itx scope, then RELEASE it: `env.ITX.get()` and the call\n   *  pipelined on it PIN THE PARENT DO until GC (the \"GC is too late\" defect the DO's facet door\n   *  fixes in the other direction). Await the answer — plain data, the wire already copied it —\n   *  then dispose the call AND the get. Protected: a host with methods of its own (the workspace,\n   *  src/workspace/durable-object.ts) reaches its context the same way. */\n  protected async withItx<T>(call: (itx: Scope) => T): Promise<Awaited<T>> {\n    const itx = this.#itxEntrypoint().get();\n    const result = call(itx);\n    try {\n      return await result;\n    } finally {\n      (result as unknown as Disposable)[Symbol.dispose]?.();\n      (itx as unknown as Disposable)[Symbol.dispose]?.();\n    }\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 ConfigWorkerItx = ItxScope;\nexport type ConfigEventArgs = { event: StreamEvent; range: ScannedRange; itx: ConfigWorkerItx };\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  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    const itx = this.env.ITX.get();\n    try {\n      for (const event of events) {\n        await this.processEvent({ event, range, itx });\n      }\n    } finally {\n      (itx as unknown as Disposable)[Symbol.dispose]?.();\n    }\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 — the Request a project host with no app label rode in on (`x-iterate-app` absent;\n   *  the project's configured ingress target). Route by hostname to `this.env.ITX.get().apps.<x>.fetch(request)`\n   *  or answer it here. 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/processor.d.ts

@@ -0,0 +1,378 @@
+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> = {
+    slug: string;
+    /** Bumping this re-reduces state from offset 0 (reduce only — side effects never re-run). */
+    version: string;
+    description?: string;
+    /** What it reacts to: type strings, or "*" for every DURABLE event. Ephemeral events are
+     *  delivered ONLY when their type is named here — `"*"` never sweeps them. */
+    consumes: readonly string[];
+    /** What its `append` is allowed to emit. */
+    emits: readonly string[];
+    /** The schema-initial state ("{} with every field defaulted" for zod contracts). */
+    initialState: () => State;
+    /** The zod payload schema for a consumed event type (owned or a dep's), or undefined if the type
+     *  is unknown or the contract declares no `events` catalog. The engine validates a consumed event's
+     *  payload against it before reducing (a malformed payload for a KNOWN event is skipped, never
+     *  folded). Present on `defineProcessorContract` contracts; a hand-built core contract omits it and
+     *  reduces unvalidated. */
+    payloadSchemaFor?: (type: string) => z.ZodType | undefined;
+};
+/** The stream a processor reduces. `read` answers durable rows plus the proof: `scannedThroughOffset`
+ *  is how far the read is CONTIGUOUSLY known (never past the durable mark — stream.ts), and `atHead`
+ *  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;
+        atHead: boolean;
+    }>;
+    /** This processor's claim on its context's alarm: "come back by `at`" (the context's alarm pass
+     *  then calls `revive()`), or `null` to release it. Durable on the context, never a log event. */
+    claim(at: number | null): Promise<unknown>;
+};
+/** How long after an attempt starts a dead host is revived: the recovery bound. A revive that finds
+ *  the attempt still in flight claims again with the delay doubled, up to `REVIVE_AFTER_MAX_MS`. */
+export declare const REVIVE_AFTER_MS = 20000;
+export declare const REVIVE_AFTER_MAX_MS: number;
+/** The contiguity proof a delivery carries: the half-open offset window `(after, through]`. A chain
+ *  of these (each `after` === the previous `through`) is how a subscriber proves it missed nothing. */
+export type ScannedRange = {
+    after: number;
+    through: number;
+};
+export type ReduceArgs<State, Event = StreamEvent> = {
+    event: Event;
+    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. */
+Emitted extends StreamEventInput = StreamEventInput> = {
+    /** The consumed event — or `null` for the eventless at-head pass. */
+    event: Event | null;
+    state: State;
+    previousState: State;
+    /** Emit (validated against `emits`, provenance-stamped) onto this processor's own stream. Declared
+     *  as METHODS (not arrow-typed properties) on purpose: a subclass that narrows `Emitted` must stay
+     *  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. */
+    runInBackground: (work: () => Promise<unknown>) => void;
+    delivery: {
+        caughtUp: boolean;
+    };
+};
+/** THE ONE consumes rule — the processor engine, the subscription delivery loop, and the inline
+ *  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. */
+export declare function consumesEvent(consumes: readonly string[] | undefined, event: {
+    type: string;
+    ephemeral?: boolean;
+}): boolean;
+/** THE AUTHOR CLASS: a contract, three hooks and one helper. Deps an effect needs arrive through
+ *  the subclass's own constructor, as for any class. One instance lives as long as its host; a field
+ *  on it is RUNTIME state (gone with the host), which `projectLiveState` may reduce into the live view. */
+export declare abstract class StreamProcessor<State, Event extends StreamEvent = StreamEvent> {
+    abstract readonly contract: ProcessorContract<State>;
+    /** Pure reduce. Return the NEXT state (a new object) — or null/undefined to keep the current. The
+     *  `Event` type param — a discriminated union of the events the contract consumes — narrows
+     *  `event.payload` per `event.type` inside the body, so no cast is needed; it defaults to the
+     *  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"]>`:
+     *  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;
+    /** The live-state PROJECTION — the shape clients see and the diffs are computed over. DEFAULT: the
+     *  reduced state verbatim, so every processor is live out of the box; that is deliberate — the
+     *  delta is an EPHEMERAL event, so "always live" costs an offset and a cheap diff, nothing durable.
+     *  Override to redact, or to REDUCE IN RUNTIME FIELDS (`return { ...state, lastSeenMs: this.lastSeenMs }`);
+     *  the engine re-projects after EVERY batch, and a field changed outside a batch needs the host's
+     *  `publishLiveState()`. */
+    projectLiveState(state: State): unknown;
+    /** Stable idempotency key namespaced by slug; pass the event being processed for a per-event key. */
+    idempotencyKey(key: string, event?: StreamEvent): string;
+}
+/** THE ENGINE: everything below the author's three hooks — the serial chain, the checkpoint, gap
+ *  repair, the at-head pass, version re-reduces, live-state publishing. Constructed by the host
+ *  (`StreamProcessorDurableObject`; a test with the stand-ins in test-support.ts). */
+export declare class ProcessorEngine<State> {
+    #private;
+    readonly processor: StreamProcessor<State>;
+    constructor(processor: StreamProcessor<State>, deps: {
+        stream: ProcessorStream;
+        storage: ReduceCheckpointTable;
+    });
+    /** THE SEED DOOR for live-state clients (LiveState.snapshot), caught up first. */
+    liveSnapshot(): Promise<{
+        rev: number;
+        state: unknown;
+    }>;
+    /** Emit a delta for the CURRENT projection (reduced + any runtime fields) if it changed. The engine
+     *  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
+     *  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
+     *  failed batch, a missed push, or a fresh incarnation can never skip a durable event. */
+    catchUpFromLog(): Promise<void>;
+    /** Reduce-and-effects caught up through the log, then `{ offset, state }`. */
+    snapshot(): Promise<{
+        offset: number;
+        state: State;
+    }>;
+    /** THE barrier verb (read-your-writes): resolves once processed AT LEAST through `offset`. An
+     *  offset ABOVE the durable mark (an ephemeral's) is reached only if this processor was pushed it —
+     *  the log cannot prove past the mark, so a wake alone never advances there. */
+    waitUntilProcessed(input: {
+        offset: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** THE REVIVE — the context's alarm pass calls this for a due claim (spent by then): catch up
+     *  from the log and run the at-head pass, so a processor restarts what state says is still owed
+     *  (rule 3). A fresh incarnation finds nothing in flight and starts it; an attempt still in flight
+     *  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. */
+export type StreamEventInput = {
+    /** Convention: `events.iterate.com/<domain>/<fact>`. */
+    type: string;
+    payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    /** Provenance: which processor (while processing what) appended this — stamped by the engine's
+     *  `append` — and WHO: the session's verified principal (src/principal.ts), set by the DO's append
+     *  root from the session's project token and never taken from a client. */
+    source?: {
+        /** The durable schedule definition responsible for this occurrence. */
+        schedule?: {
+            key: string;
+            scheduledAtOffset: number;
+            at: string;
+            /** Attribution of the definition, distinct from the platform writing the occurrence. */
+            definedBy?: Omit<NonNullable<StreamEventInput["source"]>, "schedule">;
+        };
+        processor?: {
+            slug: string;
+            version: string;
+            whileProcessing?: {
+                offset: number;
+                type: string;
+            };
+        };
+        principal?: {
+            actor: string;
+            email?: string;
+        };
+        /** 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. */
+        grant?: string;
+    };
+    /** 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
+     *  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
+     *  offset, triggers zero writes, and its body is gone the moment the incarnation ends — nobody can
+     *  redeliver it (stream.ts, the zero-write contract). A durable OMITS the field. */
+    ephemeral?: true;
+};
+/** A committed event: the input plus the identity the stream assigned at its commit point. */
+export type StreamEvent = Omit<StreamEventInput, "offset"> & {
+    offset: number;
+    createdAt: string;
+    path: string;
+};
+export declare function idempotencyConflictMessage(idempotencyKey: string, existingOffset: number): string;
+/** Structural equality of the parts an idempotent retry must not change. */
+export declare function sameIdempotentEvent(existingEvent: StreamEventInput, requestedEvent: StreamEventInput): boolean;
+/** Sync SQLite as the platform hands it over (`ctx.storage.sql`): a query is a LAZY cursor —
+ *  iterate it, or `toArray()`. Spelled structurally so a node:sqlite stand-in satisfies it. */
+export type SqlStorageHandle = {
+    exec<T extends Record<string, SqlStorageValue>>(query: string, ...bindings: unknown[]): Iterable<T> & {
+        toArray(): T[];
+    };
+};
+/** A persisted checkpoint as read back: the version it was reduced under (the caller gates on it),
+ *  the offset reduced through, and the state — `undefined` when the reduce never changed it. */
+export type ReduceCheckpoint<State> = {
+    reducerVersion: string;
+    reducedThroughOffset: number;
+    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). */
+export declare class ReduceCheckpointTable {
+    #private;
+    /** `createTable: false` when the caller knows the table exists (the stream's storage skips every
+     *  CREATE on a re-wake); a facet host constructs one per incarnation and lets it create. */
+    constructor(sql: SqlStorageHandle, options?: {
+        createTable: boolean;
+    });
+    static createTable(sql: SqlStorageHandle): void;
+    read<State>(slug: string): ReduceCheckpoint<State> | undefined;
+    /** ALWAYS the cursor; the state ONLY when `stateChanged` — one write either way. */
+    write<State>(slug: string, cursor: {
+        reducerVersion: string;
+        reducedThroughOffset: number;
+    }, 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. */
+export type LiveStateSink = {
+    append(event: {
+        type: string;
+        ephemeral?: true;
+        payload?: Record<string, unknown>;
+    }): unknown;
+};
+export declare class LiveState<S> {
+    #private;
+    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
+     *  a client chain patches exactly instead of guessing which changes its snapshot already contains. */
+    snapshot(): {
+        rev: number;
+        state: S;
+    };
+    /** Replace the value: diff the last serialized base → next; on a real change bump the revision
+     *  and append the delta. Build a NEW value (don't mutate `next` in place) — the diff is over JSON.
+     *  A diff/append failure degrades to a LOST notification (the client re-seeds on the chain gap),
+     *  never a throw the caller sees. */
+    set(next: S): void;
+}
+/** One owned event: its description and the zod schema for its payload. `ephemeral: true` marks a
+ *  non-durable event (delivered only when its type is named in `consumes`). */
+export type EventDefinition = {
+    description: string;
+    payloadSchema: z.ZodType;
+    ephemeral?: true;
+};
+/** A durable event type string → its definition. */
+export type EventCatalog = Record<string, EventDefinition>;
+/** A `processorDeps` entry's own event catalog. */
+type DepCatalog<Dep> = Dep extends {
+    events: infer Events extends EventCatalog;
+} ? Events : never;
+/** The definition owning `Type` — local events win, then each dep. */
+type DefinitionForType<Events extends EventCatalog, Deps extends readonly unknown[], Type extends string> = Type extends keyof Events ? Events[Type] : Deps[number] extends infer Dep ? Dep extends unknown ? Type extends keyof DepCatalog<Dep> ? DepCatalog<Dep>[Type] : never : never : never;
+/** The committed event for one resolved type: `StreamEvent` narrowed to its `{ type, payload }`. */
+type EventForType<Events extends EventCatalog, Deps extends readonly unknown[], Type extends string> = Type extends unknown ? DefinitionForType<Events, Deps, Type> extends {
+    payloadSchema: infer Schema extends z.ZodType;
+} ? StreamEvent & {
+    type: Type;
+    payload: z.output<Schema>;
+} : never : never;
+/** The reduce union for a `consumes` tuple — `"*"` alone means any `StreamEvent`. */
+type EventForTypes<Events extends EventCatalog, Deps extends readonly unknown[], Types extends readonly string[]> = "*" extends Types[number] ? StreamEvent : EventForType<Events, Deps, Types[number]>;
+/** A contract's `processorDeps` tuple, defaulting to empty. */
+type DepsOf<Contract> = Contract extends {
+    processorDeps: infer Deps extends readonly unknown[];
+} ? Deps : readonly [];
+/** A contract's reduced-state type, inferred from its `stateSchema`. */
+export type ProcessorState<Contract> = Contract extends {
+    stateSchema: infer Schema extends z.ZodType;
+} ? z.output<Schema> : never;
+/** The committed-event union a contract's `consumes` list can deliver to `reduce`/`processEvent`. */
+export type ConsumedEvent<Contract> = Contract extends {
+    events: infer Events extends EventCatalog;
+    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
+ *  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 {
+    payloadSchema: infer Schema extends z.ZodType;
+} ? {
+    type: Type;
+    payload: z.input<Schema>;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+} & (DefinitionForType<Events, Deps, Type> extends {
+    ephemeral: true;
+} ? {
+    ephemeral: true;
+} : {
+    ephemeral?: never;
+}) : never : never;
+/** What a processor's `append`/`appendTo` take: 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 {
+    events: infer Events extends EventCatalog;
+    emits: infer Emits extends readonly string[];
+} ? string[] extends Emits ? StreamEventInput : Emits extends readonly [] ? StreamEventInput : EventInputForType<Events, DepsOf<Contract>, Emits[number]> : StreamEventInput;
+/** What a caller APPENDS for one of a contract's OWNED events — the typed write on an entity
+ *  (`itx.agents.get(path).append(…)`, library.ts): the type string, the payload as its schema takes
+ *  it (`z.input`), a key and metadata; `ephemeral` only where the definition says so. Derived from
+ *  the catalog, so a payload field renamed in the contract is a type error at every call site. */
+export type EventInput<Contract> = Contract extends {
+    events: infer Events extends EventCatalog;
+} ? {
+    [Type in keyof Events & string]: {
+        type: Type;
+        payload: z.input<Events[Type]["payloadSchema"]>;
+        idempotencyKey?: string;
+        metadata?: Record<string, unknown>;
+    } & (Events[Type] extends {
+        ephemeral: true;
+    } ? {
+        ephemeral: true;
+    } : {
+        ephemeral?: never;
+    });
+}[keyof Events & string] : never;
+/** What `defineProcessorContract` returns: the base the engine reads, plus the events catalog and the
+ *  resolved deps. (Events are written LITERALLY at the call site — `itx.append({ type, payload })` —
+ *  so there is no event-builder here; the engine validates the payload against `payloadSchemaFor` at
+ *  reduce, and `ConsumedEvent`/`ProcessorState` give the reduce its types.) */
+export type DefinedProcessorContract<StateSchema extends z.ZodType, Events extends EventCatalog, Consumes extends readonly string[], Deps extends readonly unknown[], Emits extends readonly string[] = readonly string[]> = ProcessorContract<z.output<StateSchema>> & {
+    stateSchema: StateSchema;
+    events: Events;
+    consumes: Consumes;
+    emits: Emits;
+    processorDeps: Deps;
+};
+export declare function defineProcessorContract<const StateSchema extends z.ZodType, const Events extends EventCatalog = Record<string, never>, const Consumes extends readonly string[] = readonly string[], const Deps extends readonly {
+    events: EventCatalog;
+}[] = readonly [], const Emits extends readonly string[] = readonly string[]>(contract: {
+    slug: string;
+    version: string;
+    description: string;
+    /** Must parse `{}` — the initial state is `stateSchema.parse({})` (all fields defaulted). */
+    stateSchema: StateSchema;
+    /** The events this contract OWNS, keyed by durable type string. Omit for a kernel-generic
+     *  processor that types its own reduce through the `Event` param instead of an events catalog. */
+    events?: Events;
+    /** Other processors' contracts whose events this one may `consumes`/`emits` without owning. */
+    processorDeps?: Deps;
+    consumes: Consumes;
+    emits: Emits;
+}): DefinedProcessorContract<StateSchema, Events, Consumes, Deps, Emits>;