iterate 0.2.7 → 0.3.0

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

@@ -0,0 +1,186 @@
+import { DurableObject } from "cloudflare:workers";
+import type { LiveStateCursor } from "../sdk/capnweb/live-state/protocol.ts";
+import type { LiveStateRpc } from "../sdk/capnweb/live-state/types.ts";
+import type { ProcessorStream } from "./stream-handle.ts";
+import type { MaybePromise } from "./stream-processor.ts";
+import type { ProcessorRuntimeState, ProcessorSnapshot, StreamProcessorWakeRequest, StreamProcessorWakeResponse } from "./rpc-types.ts";
+import { type StreamProcessorRegistry } from "./stream-processor-registry.ts";
+/**
+ * Where the configured identity lives in the facet's own kv. Exported so a
+ * subclass's own doors can self-heal a fresh incarnation (re-run the
+ * idempotent `configure` from the stash) before the base's boot microtask has
+ * run — see apps/os `ProcessorFacet.#requireRegistry`.
+ */
+export declare const FACET_IDENTITY_KEY = "iterate:processor-facet:identity";
+/**
+ * The identity a {@link ProcessorFacet} is configured with on first contact —
+ * stashed durably in the facet's own kv, never passed again. `path` +
+ * `projectId` are the registry's wake coordinate fence; `parentName` is how
+ * the facet dials BACK to the Durable Object hosting it (the Stream DO) for
+ * the alarm proxy.
+ */
+export type ProcessorFacetIdentity = {
+    /** Durable Object name of the hosting parent (the Stream DO). */
+    parentName: string;
+    /** Owning project of the hosted stream, or null on a deployment-global stream. */
+    projectId: string | null;
+    /** Path of the hosted stream. */
+    path: string;
+};
+/**
+ * The three parent-side alarm doors a facet dials in place of its own
+ * (unimplemented) `ctx.storage` alarm verbs. The parent implements them over
+ * its REAL platform alarm and replays each fire into the facet's
+ * {@link ProcessorFacet.handleAlarm}. The parent's implementations MUST
+ * tolerate being called reentrantly while the parent itself is still awaiting
+ * `handleAlarm` — the keepalive re-arms from inside its own alarm turn.
+ */
+export type ProcessorFacetAlarmProxy = {
+    proxySetAlarm(scheduledTimeMs: number): MaybePromise<unknown>;
+    proxyDeleteAlarm(): MaybePromise<unknown>;
+    proxyGetAlarm(): MaybePromise<number | null>;
+};
+/**
+ * Everything app-specific about one facet host, derived from the stashed
+ * identity by {@link ProcessorFacet.createHost}: the stream handle processors
+ * append through, the worker deploy version (keepalive crash-loop budget
+ * reset), and the per-host processor composition — the subclass constructs its
+ * processors here and registers each under its subscription name.
+ */
+export type ProcessorFacetHost = {
+    /** The hosted stream — how processors append/read (colocated: a dial back
+     * to the parent Stream DO's stream surface). */
+    stream: ProcessorStream;
+    /** Worker deploy version — pass this worker's build identity. A change
+     * resets each keepalive's crash-loop budget (the antidote deploy). */
+    version: string;
+    /** Injected clock for tests; production omits it (Date.now). */
+    now?: () => number;
+    /** Assemble this node's live state; omit for the primary runner's fold. */
+    getLiveState?: () => Record<string, unknown>;
+    /** Construct and register this host's processors (`registry.register(new
+     * XProcessor({...}), { recovery, name })`) — called once, right after the
+     * registry is built. Per-processor recovery stays the author's explicit
+     * choice, exactly as on a hosting DO. */
+    registerProcessors(registry: StreamProcessorRegistry): void;
+};
+/**
+ * A facet's `DurableObjectState` facade for `createStreamProcessorRegistry`:
+ * ONLY `storage.setAlarm` / `storage.deleteAlarm` / `storage.getAlarm` are
+ * overridden to dial the parent's {@link ProcessorFacetAlarmProxy}; kv,
+ * waitUntil, and everything else pass through untouched. `parentAlarms` is
+ * invoked PER CALL — the parent stub must be resolved lazily from the stashed
+ * identity, because the recovery adapter's boot reconcile issues alarm calls
+ * at construction and a stub captured once would outlive its RPC session.
+ */
+export declare function facetProcessorDurableObjectState(ctx: DurableObjectState, parentAlarms: () => ProcessorFacetAlarmProxy): DurableObjectState;
+/**
+ * Plain-copy an `AlarmInvocationInfo` before a facet hop. The platform hands
+ * the parent's `alarm()` a host object that does not serialize across RPC;
+ * a parent replaying a fire into {@link ProcessorFacet.handleAlarm} must send
+ * this copy instead.
+ */
+export declare function plainAlarmInvocationInfo(info: AlarmInvocationInfo | undefined): AlarmInvocationInfo | undefined;
+/**
+ * Generic base for hosting stream processors in a Durable Object facet.
+ * Subclasses are the per-host composition (the facets task's target shape) and
+ * supply exactly two things: how to dial the parent's alarm proxy and what
+ * this host runs —
+ *
+ * ```ts
+ * export class AgentProcessors extends ProcessorFacet<Env> {
+ *   protected parentAlarms({ parentName }: ProcessorFacetIdentity) {
+ *     return this.env.STREAM.getByName(parentName);
+ *   }
+ *   protected createHost({ path, projectId }: ProcessorFacetIdentity): ProcessorFacetHost {
+ *     const stream = ...; // dial the parent stream
+ *     return {
+ *       stream,
+ *       version: workerVersion(this.env),
+ *       registerProcessors: (registry) => {
+ *         registry.register(
+ *           new AgentProcessor({ stream, path, projectId, ... }),
+ *           { recovery: true, name: "agent" },
+ *         );
+ *       },
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * The parent creates it with `ctx.facets.get(name, () => ({ class:
+ * ctx.exports.AgentProcessors }))`, calls `configure()` once (idempotent), and
+ * routes wakes/alarms/doors to the RPC surface below.
+ *
+ * THIS CLASS MUST NEVER DEFINE `alarm()` — and neither may a subclass. The
+ * fire arrives as `handleAlarm` (an ordinary RPC verb) instead: workerd
+ * reserves `alarm` for its native handler, and with one present a failed
+ * native `setAlarm` poisons the facet's output gate (workerd#6810). The
+ * constructor enforces this.
+ */
+export declare abstract class ProcessorFacet<Env = unknown> extends DurableObject<Env> {
+    #private;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * Resolve the parent's alarm-proxy stub for the stashed identity — e.g.
+     * `this.env.STREAM.getByName(identity.parentName)`. Called once per alarm
+     * verb invocation (stubs must not outlive their call turn).
+     */
+    protected abstract parentAlarms(identity: ProcessorFacetIdentity): ProcessorFacetAlarmProxy;
+    /** Build this host's app-specific wiring from the stashed identity — called
+     * once per incarnation, lazily on first use. */
+    protected abstract createHost(identity: ProcessorFacetIdentity): ProcessorFacetHost;
+    /**
+     * First-contact identity stash, idempotent: re-configuring with the same
+     * identity is a no-op (and ensures the host is built); a DIFFERENT identity
+     * throws — a facet's coordinate never changes, so a mismatch is a miswire,
+     * not a migration.
+     */
+    configure(identity: ProcessorFacetIdentity): void;
+    /** The wake door — the parent's colocated delivery dial. Routes to the
+     * registry: name-first resolution, coordinate fence, per-batch settlement
+     * through each batch's independent `reportDeliveryResult`. */
+    wakeStreamProcessor(request: StreamProcessorWakeRequest): Promise<StreamProcessorWakeResponse>;
+    /**
+     * The parent's alarm replay door — deliberately NOT named `alarm` (see the
+     * class doc). The parent plain-copies its `AlarmInvocationInfo`
+     * ({@link plainAlarmInvocationInfo}) and awaits this; a rejection propagates
+     * so the parent can rethrow and get the platform's alarm retry.
+     */
+    handleAlarm(info?: AlarmInvocationInfo): Promise<void>;
+    /** One consistent read of a hosted processor's committed fold. `name` may be
+     * omitted on a single-processor host. */
+    snapshot(args?: {
+        name?: string;
+    }): Promise<ProcessorSnapshot<unknown>>;
+    /** The hosted processor's runtime state (runner snapshot + contributed
+     * runtime bag). `name` may be omitted on a single-processor host. */
+    getRuntimeState(args?: {
+        name?: string;
+    }): Promise<ProcessorRuntimeState>;
+    /** Resolve once the named processor's acknowledged cursor reaches `offset` —
+     * the read-your-writes barrier. The subscription catalog's uniform
+     * `waitUntilProcessed` delegates its facet-placed processor rows here. */
+    waitUntilProcessed(args: {
+        offset: number;
+        timeoutMs?: number;
+        name?: string;
+    }): Promise<void>;
+    /** Pull the named processor through the durable stream tail — the parent
+     * facade's catch-up-before-snapshot leg, dialed before every facet read.
+     * `name` may be omitted on a single-processor host. */
+    catchUp(args?: {
+        name?: string;
+    }): Promise<void>;
+    /** Read a transient snapshot or delta for the parent's current stream lifetime.
+     * Cold or replaced processors hydrate from durable progress. Warm reads use
+     * committed local state: polling must not call back into the parent stream
+     * for every processor while it is delivering events to this facet. */
+    readLiveState(args: {
+        streamId: string;
+        cursor?: LiveStateCursor;
+        patchVersion?: 2 | 3;
+    }): Promise<import("../sdk/capnweb/index.ts").LiveStateRead<Record<string, unknown>>>;
+    /** Direct subscriptions retain their callbacks across the Workers RPC hop. */
+    liveState(): LiveStateRpc<Record<string, unknown>>;
+}

package/dist/processors/processor-host-capabilities.d.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import type { GetProcessorRuntimeState, ProcessorSnapshot, StreamConnectionPing } from "./rpc-types.ts";
+import type { ProcessorContractAnnouncement } from "./processor-contracts.ts";
+import type { EventConsumptionMetrics } from "./event-consumption-metrics.ts";
+import type { ProcessorRuntimeContribution } from "./stream-processor.ts";
+/**
+ * The processor surface shared by the Durable Object registry
+ * (stream-processor-registry.ts) and the browser host (stream-browser-store.ts):
+ * the contract description returned by `wakeStreamProcessor`, the
+ * processor-contributed runtime bag, and self-measured event-consumption metrics.
+ * Deliberately NOT the drive surface — cursors, snapshots, and delivery live
+ * in the StreamProcessorRunner, which reaches the protected hooks through
+ * `StreamProcessor.runnerHooks`.
+ */
+export type AnyHostedProcessor = {
+    contract: {
+        slug: string;
+        version: string;
+        description: string;
+        stateSchema: z.ZodType;
+        consumes: readonly string[];
+        emits: readonly string[];
+        events: Record<string, {
+            description?: string;
+            payloadSchema?: unknown;
+        }>;
+    };
+    /** The processor-contributed runtime bag; the snapshot half comes from the runner. */
+    getRuntimeState(): Promise<ProcessorRuntimeContribution>;
+    readonly eventConsumptionMetrics: Pick<EventConsumptionMetrics, "report" | "notePingObserved" | "noteAppendCommitted" | "clearPendingAppends">;
+};
+/**
+ * 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.
+ */
+export declare function hostRuntimeCapabilities(processor: AnyHostedProcessor, opts: {
+    now: () => number;
+    /** The driving runner's committed snapshot (`() => runner.snapshot()`). */
+    snapshot: () => Promise<ProcessorSnapshot<unknown>>;
+    oneWayEstimateMs?: () => number | undefined;
+}): {
+    getRuntimeState: GetProcessorRuntimeState;
+    ping: StreamConnectionPing;
+};
+/** Serializable processor contract carried by server and browser hosts. */
+export declare function announceContract(contract: {
+    slug: string;
+    version: string;
+    description: string;
+    consumes: readonly string[];
+    emits: readonly string[];
+    events: Record<string, {
+        description?: string;
+        payloadSchema?: unknown;
+    }>;
+}): ProcessorContractAnnouncement;

package/dist/processors/prompt-sections.d.ts

@@ -0,0 +1,17 @@
+export type PromptSection = {
+    key: string;
+    content: string;
+};
+/**
+ * Parse a prompt file's authoring syntax into sections, in file order.
+ * Content inside `<section key="x">...</section>` becomes a section with
+ * that key; content outside any tag (including a whole untagged file)
+ * becomes a section with `fallbackKey` — so an untagged prompt file parses
+ * to one section and keeps working unchanged. Throws on malformed authoring
+ * (unclosed or nested tags): this runs at append time, where a loud failure
+ * beats silently shipping tag soup to a model.
+ */
+export declare function parsePromptSections(input: {
+    content: string;
+    fallbackKey: string;
+}): PromptSection[];