iterate 0.2.7 → 0.3.0

package/dist/processor-host-capabilities-BMFH3KTM.mjs

@@ -0,0 +1,56 @@
+//#region src/processors/processor-host-capabilities.ts
+/**
+* The two live capabilities every processor host hands the stream alongside
+* its event-batch callback, shared by the DO registry and browser runtime so they cannot
+* drift. `getRuntimeState` assembles the published shape from its two honest
+* sources: the SNAPSHOT from the runner (`opts.snapshot` — the cursor owner),
+* the `runtime` bag from the processor, with the self-measured metrics merged
+* in host-side so a subclass override cannot accidentally drop them.
+*/
+function hostRuntimeCapabilities(processor, opts) {
+	return {
+		getRuntimeState: async () => {
+			const contributed = await processor.getRuntimeState();
+			const metrics = processor.eventConsumptionMetrics.report();
+			return {
+				snapshot: await opts.snapshot(),
+				runtime: {
+					...contributed.runtime,
+					metrics
+				}
+			};
+		},
+		ping: (input) => {
+			const t1 = opts.now();
+			const oneWayEstimateMs = opts.oneWayEstimateMs?.();
+			if (oneWayEstimateMs !== void 0) processor.eventConsumptionMetrics.notePingObserved({
+				t0: input.t0,
+				t1,
+				oneWayEstimateMs
+			});
+			return {
+				t0: input.t0,
+				t1,
+				t2: opts.now()
+			};
+		}
+	};
+}
+/** Serializable processor contract carried by server and browser hosts. */
+function announceContract(contract) {
+	return {
+		slug: contract.slug,
+		version: contract.version,
+		description: contract.description,
+		consumes: [...contract.consumes],
+		emits: [...contract.emits],
+		ownedEvents: Object.entries(contract.events).map(([type, definition]) => ({
+			type,
+			...definition.description === void 0 ? {} : { description: definition.description }
+		}))
+	};
+}
+//#endregion
+export { hostRuntimeCapabilities as n, announceContract as t };
+
+//# sourceMappingURL=processor-host-capabilities-BMFH3KTM.mjs.map

package/dist/processor-host-capabilities-BMFH3KTM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor-host-capabilities-BMFH3KTM.mjs","names":[],"sources":["../src/processors/processor-host-capabilities.ts"],"sourcesContent":["import type { z } from \"zod\";\nimport type {\n  GetProcessorRuntimeState,\n  ProcessorSnapshot,\n  StreamPingInput,\n  StreamConnectionPing,\n} from \"./rpc-types.ts\";\nimport type { ProcessorContractAnnouncement } from \"./processor-contracts.ts\";\nimport type { EventConsumptionMetrics } from \"./event-consumption-metrics.ts\";\nimport type { ProcessorRuntimeContribution } from \"./stream-processor.ts\";\n\n/**\n * The processor surface shared by the Durable Object registry\n * (stream-processor-registry.ts) and the browser host (stream-browser-store.ts):\n * the contract description returned by `wakeStreamProcessor`, the\n * processor-contributed runtime bag, and self-measured event-consumption metrics.\n * Deliberately NOT the drive surface — cursors, snapshots, and delivery live\n * in the StreamProcessorRunner, which reaches the protected hooks through\n * `StreamProcessor.runnerHooks`.\n */\nexport type AnyHostedProcessor = {\n  contract: {\n    slug: string;\n    version: string;\n    description: string;\n    stateSchema: z.ZodType;\n    consumes: readonly string[];\n    emits: readonly string[];\n    events: Record<string, { description?: string; payloadSchema?: unknown }>;\n  };\n  /** The processor-contributed runtime bag; the snapshot half comes from the runner. */\n  getRuntimeState(): Promise<ProcessorRuntimeContribution>;\n  readonly eventConsumptionMetrics: Pick<\n    EventConsumptionMetrics,\n    \"report\" | \"notePingObserved\" | \"noteAppendCommitted\" | \"clearPendingAppends\"\n  >;\n};\n\n/**\n * The two live capabilities every processor host hands the stream alongside\n * its event-batch callback, shared by the DO registry and browser runtime so they cannot\n * drift. `getRuntimeState` assembles the published shape from its two honest\n * sources: the SNAPSHOT from the runner (`opts.snapshot` — the cursor owner),\n * the `runtime` bag from the processor, with the self-measured metrics merged\n * in host-side so a subclass override cannot accidentally drop them.\n */\nexport function hostRuntimeCapabilities(\n  processor: AnyHostedProcessor,\n  opts: {\n    now: () => number;\n    /** The driving runner's committed snapshot (`() => runner.snapshot()`). */\n    snapshot: () => Promise<ProcessorSnapshot<unknown>>;\n    oneWayEstimateMs?: () => number | undefined;\n  },\n): { getRuntimeState: GetProcessorRuntimeState; ping: StreamConnectionPing } {\n  return {\n    getRuntimeState: async () => {\n      const contributed = await processor.getRuntimeState();\n      const metrics = processor.eventConsumptionMetrics.report();\n      return {\n        snapshot: await opts.snapshot(),\n        runtime: { ...contributed.runtime, metrics },\n      };\n    },\n    ping: (input: StreamPingInput) => {\n      const t1 = opts.now();\n      const oneWayEstimateMs = opts.oneWayEstimateMs?.();\n      if (oneWayEstimateMs !== undefined) {\n        processor.eventConsumptionMetrics.notePingObserved({ t0: input.t0, t1, oneWayEstimateMs });\n      }\n      return { t0: input.t0, t1, t2: opts.now() };\n    },\n  };\n}\n\n/** Serializable processor contract carried by server and browser hosts. */\nexport function announceContract(contract: {\n  slug: string;\n  version: string;\n  description: string;\n  consumes: readonly string[];\n  emits: readonly string[];\n  events: Record<string, { description?: string; payloadSchema?: unknown }>;\n}): ProcessorContractAnnouncement {\n  return {\n    slug: contract.slug,\n    version: contract.version,\n    description: contract.description,\n    consumes: [...contract.consumes],\n    emits: [...contract.emits],\n    ownedEvents: Object.entries(contract.events).map(([type, definition]) => ({\n      type,\n      ...(definition.description === undefined ? {} : { description: definition.description }),\n    })),\n  };\n}\n"],"mappings":";;;;;;;;;AA8CA,SAAgB,wBACd,WACA,MAM2E;CAC3E,OAAO;EACL,iBAAiB,YAAY;GAC3B,MAAM,cAAc,MAAM,UAAU,gBAAgB;GACpD,MAAM,UAAU,UAAU,wBAAwB,OAAO;GACzD,OAAO;IACL,UAAU,MAAM,KAAK,SAAS;IAC9B,SAAS;KAAE,GAAG,YAAY;KAAS;IAAQ;GAC7C;EACF;EACA,OAAO,UAA2B;GAChC,MAAM,KAAK,KAAK,IAAI;GACpB,MAAM,mBAAmB,KAAK,mBAAmB;GACjD,IAAI,qBAAqB,KAAA,GACvB,UAAU,wBAAwB,iBAAiB;IAAE,IAAI,MAAM;IAAI;IAAI;GAAiB,CAAC;GAE3F,OAAO;IAAE,IAAI,MAAM;IAAI;IAAI,IAAI,KAAK,IAAI;GAAE;EAC5C;CACF;AACF;;AAGA,SAAgB,iBAAiB,UAOC;CAChC,OAAO;EACL,MAAM,SAAS;EACf,SAAS,SAAS;EAClB,aAAa,SAAS;EACtB,UAAU,CAAC,GAAG,SAAS,QAAQ;EAC/B,OAAO,CAAC,GAAG,SAAS,KAAK;EACzB,aAAa,OAAO,QAAQ,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,iBAAiB;GACxE;GACA,GAAI,WAAW,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,WAAW,YAAY;EACxF,EAAE;CACJ;AACF"}

package/dist/processors/cloudflare.d.ts

@@ -0,0 +1,3 @@
+export * from "./stream-processor-registry.ts";
+export * from "./durable-object-processor-durability.ts";
+export * from "./processor-facet.ts";

package/dist/processors/durable-object-processor-durability.d.ts

@@ -0,0 +1,79 @@
+import type { ProcessorStream } from "./stream-handle.ts";
+import type { ProcessorProgressStore, ProcessorRecovery } from "./stream-processor-runner.ts";
+/** The two-cursor progress record ({@link ProcessorProgress}). */
+export declare const processorProgressKey: (name: string) => string;
+/** The per-runner keepalive record ({@link KeepaliveRecord}). */
+export declare const processorKeepaliveKey: (name: string) => string;
+/**
+ * The runner's durable progress store over DO KV (`storage.kv` — synchronous,
+ * single-threaded isolate, so read-check-write is atomic without awaits).
+ */
+export declare function durableObjectProgressStore<State>(args: {
+    storage: DurableObjectStorage;
+    /** The registered processor name (subscription name = contract slug) —
+     * keys the progress record. */
+    name: string;
+    /** Synchronously clear related projections when the source stream is replaced. */
+    resetForStream?: () => void;
+    /**
+     * An optional bounded reduction cache. Processing cursors always remain
+     * durable; a cold runner refolds reduce-only from initialState when the
+     * predicate declines a large cache.
+     */
+    reductionCache?: {
+        shouldCacheReduction(state: State): boolean;
+        initialState(): State;
+    };
+}): ProcessorProgressStore<State>;
+/**
+ * The runner's recovery adapter for a Durable Object: wraps ONE
+ * {@link ProcessorKeepalive} for THIS runner (per-runner recovery identity, so
+ * a revival names exactly which processor owed work). The keepalive machinery
+ * — mark-before-work, bounded backoff, quiet-clean reset,
+ * deploy-version reset, wedged-work detection — is reused wholesale, never
+ * reimplemented.
+ *
+ * DO-shaped seams are INJECTED, not reached for:
+ *   - `armAlarm` — the hosting registry's alarm slice for this runner. A DO
+ *     has ONE alarm; the registry merges every runner's desire (plus its own)
+ *     and arms the earliest, exactly like the host's `setAlarmSlice`. This
+ *     adapter never touches `storage.setAlarm`.
+ *   - `waitUntil` — calls the hosting DO's `ctx.waitUntil`, keeping the
+ *     incarnation alive while tracked work runs.
+ *
+ * Revival appends the core `stream/processor-revived` fact (ONE type for
+ * every processor — {@link STREAM_PROCESSOR_REVIVED_EVENT_TYPE}; the payload's
+ * `processorSlug` and the idempotency key carry the per-processor identity)
+ * to the stream and STOPS: the append wakes the source stream's event sender (its
+ * `woken` handlers cold-boot the stream DO if the deploy evicted it too), and
+ * wake-mode delivery reaches head and guarantees a turn: either the contract
+ * consumes the fact and receives it, or the runner supplies its eventless
+ * `processEvent(event: null, caughtUp: true)` pass. No self-driven catch-up
+ * here, unlike the host's `catchUpInternal` loop: delivery has ONE entrypoint.
+ *
+ * Construction re-issues a persisted armed desire through `armAlarm` (the
+ * host's boot-time reconcile): a platform `setAlarm` that failed after the KV
+ * record committed — or an eviction in the fire→re-arm window — would
+ * otherwise leave the only thing that revives this DO permanently lost.
+ */
+export declare function durableObjectRecovery(args: {
+    storage: DurableObjectStorage;
+    /** The registered processor name (subscription name = contract slug) —
+     * keys the per-runner keepalive record and the revival fact's idempotency
+     * key, and fills the revival payload's `processorSlug`. */
+    name: string;
+    /** The processor's home stream: revived facts and crash-loop evidence land here. */
+    stream: ProcessorStream;
+    /** Worker deploy version; a change resets the keepalive's crash-loop budget
+     * (the antidote deploy). Pass `workerVersion(env)`. REQUIRED for the same
+     * reason the host requires it: a silent default could never take the
+     * version-reset code path. */
+    version: string;
+    /** The registry's alarm-slice seam for this runner (null = disarm). */
+    armAlarm: (atMs: number | null) => void;
+    /** The hosting DO's `ctx.waitUntil` — keeps the incarnation alive while
+     * tracked work runs. */
+    waitUntil: (work: Promise<unknown>) => void;
+    /** Injected clock for the test harness; production uses Date.now. */
+    now?: () => number;
+}): ProcessorRecovery;

package/dist/processors/event-consumption-metrics.d.ts

@@ -0,0 +1,82 @@
+import { type LatencyStats } from "./stream-runtime-metrics.ts";
+/** The `runtime.metrics` slice a host reports through `getRuntimeState()`. */
+export type EventConsumptionMetricsReport = {
+    /** ISO timestamp when this host runtime started measuring (in-memory; resets on reload). */
+    measuredSince: string;
+    /**
+     * The full consume-your-own-appends loop, one clock: this host called
+     * `append()` at t0, and its OWN event connection later delivered (and the
+     * host fully ingested) THAT COMMITTED OFFSET.
+     *
+     * Samples only exist for appends that came back. An append of a type this
+     * host does not consume, or one the stream never hands back, contributes
+     * NOTHING here — it is not a slow loop, it is no loop, and the two must not
+     * be spelled the same. `null` is "no such append observed", never a
+     * fabricated number.
+     */
+    consumeOwnAppendMs: LatencyStats | null;
+    /** `append()` call → commit acknowledged (the RPC round trip incl. commit). */
+    appendRoundTripMs: LatencyStats | null;
+    /**
+     * Age of the newest event in each batch when the host finished ingesting
+     * it, i.e. commit-to-consumed for OTHER producers' events too. Crosses
+     * clocks (event `createdAt` is stream time), corrected by the ping-derived
+     * offset estimate when one exists — an estimate, and labeled as such in UIs.
+     */
+    deliveryAgeMs: LatencyStats | null;
+    /** Time the host spent ingesting each delivered batch (fold/SQLite write). */
+    ingestMs: LatencyStats | null;
+    batchesIngested: number;
+    eventsIngested: number;
+    /** Estimated host−stream clock skew (ms) from observed pings; `null` until pinged. */
+    clockOffsetMs: number | null;
+};
+export declare class EventConsumptionMetrics {
+    #private;
+    constructor(nowMs: number);
+    /**
+     * An `append()` this host issued resolved: `t0` is when the host called it,
+     * `atMs` is when the commit came back, and `maxCommittedOffset` is the
+     * highest committed offset that CAN come back to this host — the caller's
+     * judgement, because only the caller knows what it consumes. `null` means
+     * the append carried nothing this host will ever be delivered, and is timed
+     * for its round trip alone.
+     */
+    noteAppendCommitted(args: {
+        maxCommittedOffset: number | null;
+        t0: number;
+        atMs: number;
+    }): void;
+    /** One delivered batch fully ingested (fold applied / SQLite write done). */
+    noteBatchIngested(args: {
+        /** Highest offset the host has now ingested through (its cursor, not just this batch). */
+        ingestedThroughOffset: number;
+        /**
+         * The offsets this batch actually CARRIED.
+         *
+         * The cursor above sweeps past rows this host was never handed — a
+         * filtered subscription skips them durably — so it cannot tell an own
+         * append that came back from one that never will. These can.
+         */
+        ingestedOffsets: readonly number[];
+        /** `Date.parse(newestEvent.createdAt)` for the newest event in the batch, if any. */
+        newestEventCreatedAtMs?: number;
+        /** When the host started ingesting this batch. */
+        ingestStartedAtMs: number;
+        atMs: number;
+    }): void;
+    /**
+     * The stream pinged this host: `t0` is the stream's send time (stream
+     * clock), `t1` the host's receive time (host clock). With a one-way-delay
+     * estimate (half the host's measured transport RTT, when it has one) this
+     * yields the host−stream clock offset used to correct delivery ages.
+     */
+    notePingObserved(args: {
+        t0: number;
+        t1: number;
+        oneWayEstimateMs?: number;
+    }): void;
+    /** The host's event connection reopened: in-flight own-append correlations are void. */
+    clearPendingAppends(): void;
+    report(): EventConsumptionMetricsReport;
+}

package/dist/processors/idempotency.d.ts

@@ -0,0 +1,13 @@
+type EventBody = {
+    type: string;
+    payload?: unknown;
+    metadata?: unknown;
+    ephemeral?: boolean | undefined;
+};
+export declare function idempotencyConflictMessage(idempotencyKey: string, existingOffset: number): string;
+export declare function isIdempotencyConflict(error: unknown): boolean;
+/** Whether a requested append names the SAME event an idempotency key already committed. */
+export declare function sameIdempotentEvent(existing: EventBody, requested: EventBody): boolean;
+/** Structural JSON equality (key-order-insensitive). */
+export declare function jsonValuesEqual(left: unknown, right: unknown): boolean;
+export {};

package/dist/processors/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./schemas.ts";
+export * from "./rpc-types.ts";
+export * from "./stream-handle.ts";
+export * from "./idempotency.ts";
+export * from "./processor-contracts.ts";
+export * from "./stream-processor.ts";
+export * from "./stream-processor-runner.ts";
+export * from "./stream-processor-keepalive.ts";
+export * from "./processor-host-capabilities.ts";
+export * from "./event-consumption-metrics.ts";
+export * from "./stream-runtime-metrics.ts";
+export * from "./prompt-sections.ts";

package/dist/processors/processor-contracts.d.ts

@@ -0,0 +1,342 @@
+import { z } from "zod";
+import type { StreamEvent, StreamEventInput } from "./schemas.ts";
+/**
+ * Merge one processor configuration patch into its current configuration.
+ *
+ * Configuration patches recurse only through plain JSON objects. Arrays,
+ * scalars, and `null` replace the previous value wholesale; omitted keys are
+ * retained. Processors validate the merged result with their own complete
+ * configuration schema before storing it in reduced state.
+ */
+export declare function mergeProcessorConfig(base: unknown, patch: unknown): unknown;
+/**
+ * One documented example payload for an owned event, rendered on the public
+ * event docs site (events.iterate.com). The payload must parse against the
+ * event's `payloadSchema` — enforced by the event-docs unit tests rather than
+ * at module load, so a bad example fails CI instead of bricking a worker boot.
+ */
+export type EventExample = {
+    /** What this example shows, e.g. "Durable delivery to another stream". */
+    description: string;
+    /** The example payload, in the payload schema's input shape. */
+    payload: unknown;
+};
+/** One owned event: its payload schema plus optional human description and examples. */
+export type EventDefinition<PayloadOutput = unknown, PayloadInput = PayloadOutput> = {
+    description?: string;
+    payloadSchema: z.ZodType<PayloadOutput, PayloadInput>;
+    /**
+     * FORCIBLY ephemeral: every append and parse built from this definition
+     * defaults the envelope's `ephemeral` flag to `true` and REJECTS an explicit
+     * `ephemeral: false`. For events that must never become durable stream
+     * facts (streaming chunks) — declaring it here makes forgetting the flag at
+     * an append site impossible instead of a silent storage leak.
+     */
+    ephemeral?: true;
+    examples?: readonly EventExample[];
+};
+/** A contract's owned events, keyed by the durable event type string. */
+export type EventCatalog = Record<string, EventDefinition<unknown, unknown>>;
+/** The string-keyed event definitions of a catalog object (index signatures excluded). */
+type EventCatalogFromObject<Value> = {
+    [Key in keyof Value as string extends Key ? never : number extends Key ? never : Value[Key] extends EventDefinition ? Key : never]: Value[Key];
+};
+/**
+ * A `processorDeps` entry may be a full contract (`{ events: ... }`) or a
+ * standalone event catalog, so a processor can depend on another processor's
+ * contract or on a small shared catalog.
+ */
+type ContractEventCatalog<ContractOrCatalog> = ContractOrCatalog extends {
+    events: infer Events;
+} ? EventCatalogFromObject<Events> : EventCatalogFromObject<ContractOrCatalog>;
+/** All event type strings resolvable from local `events` plus `processorDeps`. */
+type ResolvedEventType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[]> = Extract<keyof EventCatalogFromObject<Events> | EventTypeFromProcessorDeps<ProcessorDeps>, string>;
+/** Union of every event type string owned by any `processorDeps` entry. */
+type EventTypeFromProcessorDeps<ProcessorDeps extends readonly unknown[]> = ProcessorDeps[number] extends infer ProcessorDep ? ProcessorDep extends unknown ? keyof ContractEventCatalog<ProcessorDep> : never : never;
+/**
+ * Resolve a string event type to the definition that owns it. Local events win
+ * in the type-level lookup; runtime validation rejects duplicate ownership.
+ */
+type EventDefinitionForType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Type extends string> = Type extends keyof Events ? Events[Type] : ProcessorDeps[number] extends infer ProcessorDep ? ProcessorDep extends unknown ? Type extends keyof ContractEventCatalog<ProcessorDep> ? ContractEventCatalog<ProcessorDep>[Type] : never : never : never;
+/** `StreamEventInput` with `type`/`payload` narrowed to one event definition. */
+type TypedStreamEventInput<Type extends string = string, Payload = Record<string, unknown>> = Omit<StreamEventInput, "payload" | "type"> & {
+    type: Type;
+    payload: Payload;
+};
+/**
+ * A durable processor input. Wake processors never receive ephemeral events, so
+ * a domain object's processor-typed append door must not claim that they do.
+ */
+type TypedConsumedEventInput<Type extends string = string, Payload = Record<string, unknown>> = Omit<TypedStreamEventInput<Type, Payload>, "ephemeral"> & {
+    ephemeral?: never;
+};
+/** `StreamEvent` with `type`/`payload` narrowed to one event definition. */
+type TypedStreamEvent<Type extends string = string, Payload = Record<string, unknown>> = Omit<StreamEvent, "payload" | "type"> & TypedStreamEventInput<Type, Payload>;
+/** Committed event for one resolved type (payload parsed, so required). */
+type EventFromType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Type extends string> = Type extends unknown ? EventDefinitionForType<Events, ProcessorDeps, Type> extends EventDefinition<infer PayloadOutput, unknown> ? TypedStreamEvent<Type, PayloadOutput> & {
+    payload: PayloadOutput;
+} & ParsedEphemeralEnvelope<EventDefinitionForType<Events, ProcessorDeps, Type>> : never : never;
+/** A committed event resolved from a contract's owned events or processor dependencies.
+ * Unknown event-type strings retain the untyped {@link StreamEvent} shape. */
+export type ResolvedEvent<Contract, Type extends string> = Contract extends {
+    events: EventCatalog;
+} ? Type extends ResolvedEventType<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>> ? EventFromType<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, Type> : StreamEvent : StreamEvent;
+/** Union of committed-event shapes for a `consumes` tuple; `"*"` alone means any `StreamEvent`. */
+type EventFromTypes<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Types extends readonly string[]> = "*" extends Types[number] ? [Exclude<Types[number], "*">] extends [never] ? StreamEvent : EventFromType<Events, ProcessorDeps, Exclude<Types[number], "*">> : EventFromType<Events, ProcessorDeps, Types[number]>;
+/** Append input for one resolved type (payload accepts the schema's input shape). */
+type InputFromType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Type extends string> = Type extends unknown ? EventDefinitionForType<Events, ProcessorDeps, Type> extends EventDefinition<unknown, infer PayloadInput> ? TypedStreamEventInput<Type, PayloadInput> : never : never;
+/** Durable append input for one event delivered to a wake processor. */
+type ConsumedInputFromType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Type extends string> = Type extends unknown ? EventDefinitionForType<Events, ProcessorDeps, Type> extends EventDefinition<unknown, infer PayloadInput> ? TypedConsumedEventInput<Type, PayloadInput> : never : never;
+/** Durable append-input shapes for a processor's `consumes` tuple. */
+type ConsumedInputFromTypes<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Types extends readonly string[]> = "*" extends Types[number] ? Omit<StreamEventInput, "ephemeral"> & {
+    ephemeral?: never;
+} : ConsumedInputFromType<Events, ProcessorDeps, Types[number]>;
+/** Parsed append input for one resolved type (payload validated, so required). */
+type ParsedInputFromType<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Type extends string> = Type extends unknown ? EventDefinitionForType<Events, ProcessorDeps, Type> extends EventDefinition<infer PayloadOutput, unknown> ? TypedStreamEventInput<Type, PayloadOutput> & {
+    payload: PayloadOutput;
+} & ParsedEphemeralEnvelope<EventDefinitionForType<Events, ProcessorDeps, Type>> : never : never;
+/** Contract-forced ephemeral inputs default to `true` during parsing. */
+type ParsedEphemeralEnvelope<Definition> = Definition extends {
+    ephemeral: true;
+} ? {
+    ephemeral: true;
+} : unknown;
+/** A typed builder preserves the supplied envelope while returning parsed payload/default output. */
+type BuiltInputFromEvent<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Event extends {
+    type: string;
+}> = Event extends unknown ? Omit<Event, "payload"> & Pick<ParsedInputFromType<Events, ProcessorDeps, Event["type"]>, "payload"> & ParsedEphemeralEnvelope<EventDefinitionForType<Events, ProcessorDeps, Event["type"]>> : never;
+/** Parsed durable inputs for a processor's `consumes` tuple. */
+type ParsedConsumedInputFromTypes<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Types extends readonly string[]> = "*" extends Types[number] ? Omit<StreamEventInput, "ephemeral"> & {
+    ephemeral?: never;
+} : Types[number] extends infer Type extends string ? EventDefinitionForType<Events, ProcessorDeps, Type> extends EventDefinition<infer PayloadOutput, unknown> ? TypedConsumedEventInput<Type, PayloadOutput> : never : never;
+/** Union of committed-event shapes a contract's `consumes` list can deliver to `reduce`. */
+export type ConsumedEvent<Contract> = Contract extends {
+    events: EventCatalog;
+    consumes: infer Consumes extends readonly string[];
+} ? EventFromTypes<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, Consumes> : never;
+/**
+ * Union of durable append-input shapes accepted by a contract's `consumes`
+ * list. Ephemeral events are excluded because hosted processors cannot consume
+ * them; append those intentionally through the raw Stream door. This is a
+ * schema/vocabulary union, not proof that an event is valid in the processor's
+ * current state or came from a particular provenance.
+ */
+export type ConsumedInput<Contract> = Contract extends {
+    events: EventCatalog;
+    consumes: infer Consumes extends readonly string[];
+} ? ConsumedInputFromTypes<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, Consumes> : never;
+/** Union of append-input shapes a contract's `emits` list allows a processor to append. */
+export type EmittedInput<Contract> = Contract extends {
+    events: EventCatalog;
+    emits: infer Emits extends readonly string[];
+} ? InputFromType<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, Emits[number]> : never;
+/** A contract's `processorDeps` tuple, defaulting to empty when absent. */
+type ProcessorDepsOf<Contract> = Contract extends {
+    processorDeps?: infer ProcessorDeps;
+} ? ProcessorDeps extends readonly unknown[] ? ProcessorDeps : readonly [] : readonly [];
+/** A contract's reduced-state type, inferred from its `stateSchema`. */
+export type ProcessorState<Contract> = Contract extends {
+    stateSchema: infer State extends z.ZodType;
+} ? z.output<State> : never;
+/** Reduced state must be object-shaped and must accept `{}` (the empty initial state). */
+type DefaultableObjectStateSchema<StateSchema extends z.ZodType> = z.output<StateSchema> extends Record<string, unknown> ? {} extends z.input<StateSchema> ? StateSchema : never : never;
+/**
+ * Compile-time typo guard for `consumes` / `emits`: resolves to `unknown` when
+ * every string in `Types` is resolvable (leaving the contract argument
+ * unchanged), `never` when one is not — failing the call where the bad string
+ * is written. `AllowStar` admits the `"*"` wildcard (consumes only).
+ */
+type ResolvedEventTypesOnly<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Types extends readonly string[], AllowStar extends string = never> = [Exclude<Exclude<Types[number], AllowStar>, ResolvedEventType<Events, ProcessorDeps>>] extends [
+    never
+] ? unknown : never;
+/** `contract.buildEvent(...)`: validate an append input against the resolved payload schema. */
+type ProcessorContractBuildEvent<Events extends EventCatalog, ProcessorDeps extends readonly unknown[]> = <const Event extends InputFromType<Events, ProcessorDeps, ResolvedEventType<Events, ProcessorDeps>> & {
+    type: string;
+}>(event: Event) => BuiltInputFromEvent<Events, ProcessorDeps, Event>;
+/** Resolved contract types compatible with an event's current discriminator type. */
+type ResolvedTypeFromEvent<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Event extends {
+    type: string;
+}> = Extract<ResolvedEventType<Events, ProcessorDeps>, Event["type"]>;
+/** `contract.parseEvent(...)`: validate a committed event and infer its output from `event.type`. */
+type ProcessorContractParseEvent<Events extends EventCatalog, ProcessorDeps extends readonly unknown[]> = <const Event extends StreamEvent>(event: Event) => EventFromType<Events, ProcessorDeps, ResolvedTypeFromEvent<Events, ProcessorDeps, Event>>;
+/**
+ * Same as `parseEvent`, but for append inputs that do not yet have an offset or
+ * createdAt. This exists for stream-owned pre-commit policy: the Stream Durable
+ * Object must reject some contract-owned events BEFORE they become durable
+ * facts (see the core processor's `validate`) — validating them
+ * later, in the wake side effect, would leave the invalid event committed and
+ * reduced into durable state. The lifecycle e2e tests assert both the rejection
+ * and that nothing was committed.
+ */
+type ProcessorContractParseEventInput<Events extends EventCatalog, ProcessorDeps extends readonly unknown[]> = <const Event extends StreamEventInput>(event: Event) => ParsedInputFromType<Events, ProcessorDeps, ResolvedTypeFromEvent<Events, ProcessorDeps, Event>>;
+/**
+ * `contract.parseConsumedInput(...)`: validate one domain-object append
+ * against the exact event vocabulary delivered to the processor.
+ */
+type ProcessorContractParseConsumedInput<Events extends EventCatalog, ProcessorDeps extends readonly unknown[], Consumes extends readonly string[]> = <const Event extends ConsumedInputFromTypes<Events, ProcessorDeps, Consumes>>(event: Event) => "*" extends Consumes[number] ? ParsedConsumedInputFromTypes<Events, ProcessorDeps, Consumes> : ParsedConsumedInputFromTypes<Events, ProcessorDeps, readonly Extract<Consumes[number], Event["type"]>[]>;
+/**
+ * `getEventSchema` without offset/createdAt (and strict, so an accidental
+ * `offset` key on an append input fails loudly). Gives pre-append policy code
+ * the same payload validation as reducers, without fabricating a committed
+ * event just to get at the typed payload.
+ */
+export declare function getEventInputSchema<const Type extends string, const PayloadSchema extends z.ZodType>(args: {
+    type: Type;
+    payloadSchema: PayloadSchema;
+    ephemeral?: boolean;
+}): z.ZodType<TypedStreamEventInput<Type, z.output<PayloadSchema>>, TypedStreamEventInput<Type, z.input<PayloadSchema>>>;
+/** Memoized {@link getEventSchema} (see {@link eventSchemaCache}). */
+export declare function cachedEventSchema(args: {
+    type: string;
+    payloadSchema: z.ZodType;
+    ephemeral?: boolean;
+}): z.ZodType;
+/** Union of append-input shapes for every event a contract can resolve (own + deps). */
+type ResolvedEventInput<Contract> = Contract extends {
+    events: EventCatalog;
+} ? InputFromType<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, ResolvedEventType<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>>> : never;
+/**
+ * Validate an append input with the payload schema resolved from a processor
+ * contract. Prefer the contract-bound `contract.buildEvent(event)` API, which
+ * carries the same types without repeating the contract in the argument.
+ *
+ * @deprecated Use `contract.buildEvent(event)`.
+ */
+export declare function buildEvent<const Contract extends {
+    slug?: string;
+    events: EventCatalog;
+    processorDeps?: readonly unknown[];
+}, const Event extends ResolvedEventInput<NoInfer<Contract>> & {
+    type: string;
+}>(args: {
+    contract: Contract;
+    event: Event;
+}): BuiltInputFromEvent<ContractEventCatalog<Contract>, ProcessorDepsOf<Contract>, Event>;
+/**
+ * Typed identity for processor contracts: validation plus the pre-bound
+ * `buildEvent` / `parseEvent` / `parseEventInput` / `parseConsumedInput`
+ * helpers.
+ *
+ * The signature enforces the important invariants at authoring time:
+ *
+ * - `stateSchema` must parse `{}` to an object-shaped reduced state;
+ * - every string in `consumes` and `emits` must resolve against local `events`
+ *   plus `processorDeps` (and both are contextually typed for autocomplete);
+ * - local `events` must not redefine an event already owned by a
+ *   `processorDeps` contract. Event ownership is intentionally one processor
+ *   deep: a processor can depend on another owner, but it cannot shadow that
+ *   owner's public event type with a second payload schema.
+ */
+export declare function defineProcessorContract<const StateSchema extends z.ZodType, const Events extends EventCatalog, const Consumes extends readonly (ResolvedEventType<Events, ProcessorDeps> | "*")[], const Emits extends readonly ResolvedEventType<Events, ProcessorDeps>[], const ProcessorDeps extends readonly unknown[] = readonly []>(contract: {
+    slug: string;
+    version: string;
+    description: string;
+    stateSchema: DefaultableObjectStateSchema<StateSchema>;
+    processorDeps?: ProcessorDeps;
+    events: Events;
+    consumes: Consumes & ResolvedEventTypesOnly<Events, ProcessorDeps, Consumes, "*">;
+    emits: Emits & ResolvedEventTypesOnly<Events, ProcessorDeps, Emits>;
+}): {
+    slug: string;
+    version: string;
+    description: string;
+    stateSchema: StateSchema;
+    processorDeps?: ProcessorDeps;
+    events: Events;
+    consumes: Consumes;
+    emits: Emits;
+    buildEvent: ProcessorContractBuildEvent<Events, ProcessorDeps>;
+    parseEvent: ProcessorContractParseEvent<Events, ProcessorDeps>;
+    parseEventInput: ProcessorContractParseEventInput<Events, ProcessorDeps>;
+    parseConsumedInput: ProcessorContractParseConsumedInput<Events, ProcessorDeps, Consumes>;
+};
+/**
+ * Enforces the invariant that reduced processor state is object-shaped (so
+ * state slices can evolve safely and hooks never branch on primitive state).
+ */
+export declare function assertObjectProcessorState(args: {
+    processorSlug: string;
+    value: unknown;
+}): void;
+/**
+ * Resolve the payload schema a processor should use for an incoming event:
+ * the named definition when the type is listed in `consumes`, a permissive
+ * `z.unknown()` definition when the contract consumes `"*"`, and `undefined`
+ * when the event is not consumed at all. Runtime counterpart of
+ * `ConsumedEvent<Contract>`.
+ *
+ * `"*"` NEVER MATCHES AN EPHEMERAL EVENT, and that one rule is what lets
+ * ephemeral types live in `consumes` beside durable ones instead of in a
+ * parallel list. Naming a type explicitly is the opt-in: you cannot be handed
+ * a microphone firehose by a wildcard you wrote for durable facts, and a
+ * processor that wants live events says so by type. Ephemeral bodies live
+ * only in the Stream DO's bounded buffer, so a processor receiving one must
+ * have decided it can cope with never seeing it again — a decision nobody
+ * makes by writing `"*"`.
+ */
+export declare function getConsumedEventDefinition(args: {
+    contract: {
+        events: EventCatalog;
+        processorDeps?: readonly unknown[];
+        consumes: readonly string[];
+    };
+    eventType: string;
+    /** Whether the event being resolved is ephemeral; gates the `"*"` fallback. */
+    ephemeral?: boolean;
+}): EventDefinition | undefined;
+export declare function getResolvedEventDefinition(args: {
+    contract: {
+        events: EventCatalog;
+        processorDeps?: readonly unknown[];
+    };
+    eventType: string;
+}): EventDefinition | undefined;
+/**
+ * The ONE platform revival fact for every recovery-wired stream processor.
+ * Appended by the platform keepalive (`durableObjectRecovery` in
+ * durable-object-processor-durability.ts) when a processor is revived after
+ * its incarnation died owing background work — never emitted by a processor.
+ * Per-processor identity rides the payload's `processorSlug` and the
+ * `processor-revived:<slug>@...` idempotency key, not the type string.
+ * Consuming it is OPTIONAL: a processor should do so only when it reacts to
+ * the fact itself. Its append still wakes delivery when it is unconsumed, and
+ * a head-reaching frame receives the runner's eventless
+ * `processEvent(event: null, caughtUp: true)` pass so open obligations are not
+ * stranded. The event DEFINITION (payload schema) lives with the platform's
+ * core stream contract; this constant is here so contracts and the recovery
+ * adapter agree on the type string without importing that contract.
+ */
+export declare const STREAM_PROCESSOR_REVIVED_EVENT_TYPE = "events.iterate.com/stream/processor-revived";
+/**
+ * A processor contract announcement carried on `connection-opened` when the
+ * callback owner is a hosted stream processor. UIs and tooling read it from
+ * that event and from `runtime.connections[..].openedBy`.
+ */
+export declare const ProcessorContractAnnouncement: z.ZodObject<{
+    slug: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    consumes: z.ZodArray<z.ZodString>;
+    emits: z.ZodArray<z.ZodString>;
+    ownedEvents: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProcessorContractAnnouncement = z.infer<typeof ProcessorContractAnnouncement>;
+/**
+ * Platform stream events a processor contract may CONSUME without owning —
+ * pass as a `processorDeps` entry. Currently just the keepalive revival fact.
+ * Consumption is optional and belongs only in processors that react to the
+ * fact itself; an unconsumed revival tail receives the runner's eventless
+ * at-head turn. The event's authoritative definition lives with the
+ * platform's core stream contract, and this catalog is deliberately
+ * payload-loose.
+ */
+export declare const PLATFORM_STREAM_EVENTS: {
+    "events.iterate.com/stream/processor-revived": {
+        description: string;
+        payloadSchema: z.ZodObject<{}, z.core.$loose>;
+    };
+};
+export {};