@rikalabs/akter 0.1.0-alpha.0

package/dist/handles/actors.d.ts

@@ -0,0 +1,17 @@
+import { Context, type Effect } from "effect";
+import type { ActorError } from "../errors/actor.ts";
+declare const Actors_base: Context.ServiceClass<Actors, "@rikalabs/akter/handles/actors", {
+    /**
+     * Mints a command id for `Actor.commandId`, so a caller can retry one
+     * operation across processes. It reads the database clock, so it fails
+     * `ActorUnavailable` while the database is unreachable.
+     */
+    readonly mintCommandId: Effect.Effect<string, ActorError>;
+}>;
+/**
+ * The runtime's public service. Provide it with `Actors.layer` from
+ * `@rikalabs/akter/runtime`; handles reach the runtime through it.
+ */
+export declare class Actors extends Actors_base {
+}
+export {};

package/dist/handles/actors.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+/**
+ * The runtime's public service. Provide it with `Actors.layer` from
+ * `@rikalabs/akter/runtime`; handles reach the runtime through it.
+ */
+export class Actors extends Context.Service()("@rikalabs/akter/handles/actors") {
+}

package/dist/handles/content.d.ts

@@ -0,0 +1,59 @@
+import { Context, Effect, type Option, type Stream } from "effect";
+import type { ActorError } from "../errors/actor.ts";
+import type { ContentTooLarge } from "../errors/content.ts";
+import { type ActorRef, type Caller } from "../identity/caller.ts";
+import type { ContentRef } from "../identity/content.ts";
+import type { AnyContent } from "../members/blob.ts";
+declare const ContentStore_base: Context.ServiceClass<ContentStore, "@rikalabs/akter/handles/content/ContentStore", {
+    /** Stores bytes already in memory for `tenant` and returns a fresh grant. */
+    readonly uploadBytes: (tenant: string, bytes: Uint8Array) => Effect.Effect<ContentRef, ContentTooLarge | ActorError>;
+    /**
+     * Stores a body as it arrives, hashing it on the way; past `limit` bytes
+     * it fails `ContentTooLarge` and stores nothing.
+     */
+    readonly upload: (tenant: string, body: Stream.Stream<Uint8Array, ActorError>, limit: number) => Effect.Effect<ContentRef, ContentTooLarge | ActorError>;
+    /**
+     * A fresh grant for the content `ref` references under `blob`/`name`, after
+     * the actor's `access` policy and `authorize` allow `caller` the operation `<blob>.grant`; none for a
+     * missing name or content swept meanwhile.
+     */
+    readonly grant: (ref: ActorRef, caller: Caller, blob: string, name: string) => Effect.Effect<Option.Option<ContentRef>, ActorError>;
+    /**
+     * The referenced content's size and bytes, after the actor's `access`
+     * policy and `authorize` allow `caller` the operation `<blob>.get`; none for a missing name. The bytes
+     * come from one snapshot; content swept after the reference resolved
+     * fails the stream before any chunk.
+     */
+    readonly download: (ref: ActorRef, caller: Caller, blob: string, name: string) => Effect.Effect<Option.Option<{
+        readonly size: number;
+        readonly bytes: Stream.Stream<Uint8Array, ActorError>;
+    }>, ActorError>;
+}>;
+/**
+ * The runtime's content operations. They write framework rows on a tenant's
+ * shard outside any turn, so effect executors, which hold no database
+ * capability, never receive this service.
+ */
+export declare class ContentStore extends ContentStore_base {
+}
+/**
+ * Content operations for code outside turns, queries, and executors, with
+ * the ambient tenant and caller.
+ */
+export declare const Content: {
+    /**
+     * Stores `bytes` once for the ambient tenant, up to 64 MiB, and returns a
+     * reference whose grant lasts an hour. Uploading bytes the tenant already
+     * holds stores nothing new and returns a fresh grant.
+     */
+    upload: (bytes: Uint8Array) => Effect.Effect<ContentRef, ContentTooLarge | ActorError, ContentStore>;
+    /**
+     * A fresh grant for the content an actor references, so another actor's
+     * turn can attach it. `access` and `authorize` see the ambient caller with kind
+     * `content` and command `<blob>.grant`. None when the actor holds no reference under `name`.
+     */
+    grant: (actor: {
+        readonly name: string;
+    }, id: string, blob: AnyContent, name: string) => Effect.Effect<Option.Option<ContentRef>, ActorError, ContentStore>;
+};
+export {};

package/dist/handles/content.js

@@ -0,0 +1,36 @@
+import { Context, Effect } from "effect";
+import { outsideTurn } from "../contexts/command.js";
+import { CurrentCaller, Tenant } from "../identity/caller.js";
+/**
+ * The runtime's content operations. They write framework rows on a tenant's
+ * shard outside any turn, so effect executors, which hold no database
+ * capability, never receive this service.
+ */
+export class ContentStore extends Context.Service()("@rikalabs/akter/handles/content/ContentStore") {
+}
+/**
+ * Content operations for code outside turns, queries, and executors, with
+ * the ambient tenant and caller.
+ */
+export const Content = {
+    /**
+     * Stores `bytes` once for the ambient tenant, up to 64 MiB, and returns a
+     * reference whose grant lasts an hour. Uploading bytes the tenant already
+     * holds stores nothing new and returns a fresh grant.
+     */
+    upload: (bytes) => Effect.gen(function* () {
+        yield* outsideTurn;
+        const store = yield* ContentStore;
+        return yield* store.uploadBytes(yield* Tenant, bytes);
+    }),
+    /**
+     * A fresh grant for the content an actor references, so another actor's
+     * turn can attach it. `access` and `authorize` see the ambient caller with kind
+     * `content` and command `<blob>.grant`. None when the actor holds no reference under `name`.
+     */
+    grant: (actor, id, blob, name) => Effect.gen(function* () {
+        yield* outsideTurn;
+        const store = yield* ContentStore;
+        return yield* store.grant({ tenant: yield* Tenant, actor: actor.name, id }, yield* CurrentCaller, blob.name, name);
+    }),
+};

package/dist/handles/intents.d.ts

@@ -0,0 +1,164 @@
+import { Context, DateTime, Duration, Effect, Schema } from "effect";
+import { type ActorRef, type Caller, type MintProof, type Principal } from "../identity/caller.ts";
+/** When a staged intent becomes due: relative to the turn's commit, or at an instant. */
+export declare const Due: Schema.TaggedUnion<{
+    readonly After: Schema.TaggedStruct<"After", {
+        readonly millis: Schema.Int;
+    }>;
+    readonly At: Schema.TaggedStruct<"At", {
+        readonly epochMillis: Schema.Int;
+    }>;
+}>;
+/** When a staged intent becomes due. */
+export type Due = typeof Due.Type;
+/** An intent a turn staged: the command to send `target`, its encoded input, and who it appears to come from. `key` names it for replacement or cancellation. */
+interface StagedIntent {
+    readonly target: ActorRef;
+    readonly command: string;
+    readonly payload: string;
+    readonly caller: Caller;
+    readonly due: Due | undefined;
+    readonly key: string | undefined;
+}
+/** A job a turn enqueued: its tag, encoded instance, and the caller its routes see. */
+interface StagedJob {
+    readonly job: string;
+    readonly payload: string;
+    /** The payload version `payload` is encoded at. */
+    readonly version: number;
+    readonly caller: Caller;
+    readonly due: Due | undefined;
+    readonly key: string | undefined;
+    /** Whether the job declares `concurrency.perActor`, so its claims follow `ready_at_ms`. */
+    readonly capped: boolean;
+}
+/**
+ * A dynamic subscription change a turn staged: `subscribe` from a position,
+ * or `remove`. The last change a turn stages for one source wins.
+ */
+export interface StagedSubscription {
+    readonly subscription: string;
+    readonly source: ActorRef;
+    readonly op: "subscribe" | "remove";
+    /** `"now"`, `"start"`, or an exclusive source cursor; unused by `remove`. */
+    readonly from: string;
+    /** The declaration's event tags, which decide which of the source's commits wake the row. */
+    readonly events: ReadonlyArray<string>;
+}
+/**
+ * Everything one turn asked the outbox to do. `replaced` lists keys whose
+ * committed rows the turn deletes before inserting `intents`;
+ * `cancelledJobs` lists job keys whose committed jobs it cancels before
+ * inserting `jobs`.
+ */
+export interface StagedOutbox {
+    readonly intents: ReadonlyArray<StagedIntent>;
+    readonly replaced: ReadonlyArray<string>;
+    readonly jobs: ReadonlyArray<StagedJob>;
+    readonly subscriptions: ReadonlyArray<StagedSubscription>;
+    readonly cancelledJobs: ReadonlyArray<string>;
+}
+/** The outbox of a turn that staged nothing. */
+export declare const emptyOutbox: StagedOutbox;
+/** Job keys live in the actor's key namespace under this prefix, which intent keys may not use. */
+export declare const JOB_KEY_PREFIX = "$job:";
+declare const InTurn_base: Context.ServiceClass<InTurn, "@rikalabs/akter/handles/intents/InTurn", {
+    readonly turn: symbol;
+}>;
+/**
+ * Marks a command turn. Only the runtime provides it, and `X.toLayer` removes
+ * it from handler requirements, so `X.intents` and `Intent.cancel` outside a
+ * command turn leave an unsatisfiable requirement.
+ */
+export declare class InTurn extends InTurn_base {
+}
+interface Minted {
+    readonly child: ActorRef;
+    readonly createdBy: string;
+    readonly proof: MintProof;
+}
+interface Staging {
+    readonly sender: ActorRef;
+    readonly commandId: string;
+    /** The sender's event sequence before this turn's emits. */
+    readonly head: string;
+    readonly onBehalfOf: Principal | undefined;
+    readonly minted: Map<string, Minted>;
+    open: boolean;
+    intents: Array<StagedIntent>;
+    readonly replaced: Set<string>;
+    jobs: Array<StagedJob>;
+    readonly subscriptions: Map<string, StagedSubscription>;
+    readonly cancelledJobs: Set<string>;
+}
+/**
+ * Opens the outbox of one command turn; `close` returns what it staged and
+ * seals it. A staged job's routes deliver to the enqueuing actor as the job,
+ * on the turn's principal.
+ */
+export declare const openOutbox: ({ sender, commandId, head, onBehalfOf, }: {
+    readonly sender: ActorRef;
+    readonly commandId: string;
+    readonly head: string;
+    readonly onBehalfOf: Principal | undefined;
+}) => {
+    marker: {
+        readonly turn: symbol;
+    };
+    /** Stages a job; the caller checks that its turn is still running. */
+    enqueue: (job: Pick<StagedJob, "job" | "payload" | "version" | "due" | "key" | "capped">) => void;
+    /** Stages the cancellation of the job with `key`; the caller checks the turn. */
+    cancelJob: (key: string) => void;
+    /** The proof the next `turn.mint` call of this turn carries. */
+    nextMint: () => MintProof;
+    /** Records a minted id; its creating intent then carries `proof`. */
+    minted: (child: ActorRef, createdBy: string, proof: MintProof) => void;
+    /** A minted actor that no staged intent to its creating command targets, if any. */
+    uncreated: () => ActorRef | undefined;
+    /**
+     * A minted actor whose creating intent has a key, if any: a later keyed
+     * intent or cancel could remove it before delivery and leave the id uncreated.
+     */
+    keyedCreation: () => ActorRef | undefined;
+    /** Stages a subscription change; a later change for the same source replaces it. */
+    subscribe: (change: StagedSubscription) => void;
+    close: () => StagedOutbox;
+};
+/** Validates a job key (1-200 characters) and returns it prefixed as it is staged and stored. */
+export declare const jobKey: (key: string) => string;
+/** The staging area of the running turn, checked against `marker` when given; dies once the turn ended, so a capability that escaped its turn stages nothing. */
+export declare const currentStaging: (marker?: {
+    readonly turn: symbol;
+} | undefined) => Effect.Effect<{
+    marker: {
+        readonly turn: symbol;
+    };
+    staging: Staging;
+}, never, InTurn>;
+/**
+ * Stages `intent` in the running turn's outbox with the ambient `Intent`
+ * settings. The receiver sees the sending actor, attributed to the sending
+ * turn's principal; only a minted child's creating intent carries the proof
+ * that lets it create the child.
+ */
+export declare const stageIntent: (marker: {
+    readonly turn: symbol;
+}, intent: Pick<StagedIntent, "command" | "payload" | "target">) => Effect.Effect<void, never, InTurn>;
+/**
+ * Options for intents staged by the piped Effect. The outermost setting wins,
+ * so a later `pipe` step overrides an earlier one.
+ */
+export declare const Intent: {
+    /** Delivers no earlier than `duration` after the turn commits. */
+    after: (duration: Duration.Input) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /** Delivers no earlier than `instant`, measured on the database clock. */
+    at: (instant: DateTime.DateTime) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Names the intent within its sending actor. Staging another intent with the
+     * same key, in this turn or a later one, replaces it while it is pending.
+     */
+    key: (key: string) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /** Removes the sending actor's pending intent with `key` when this turn commits. */
+    cancel: (key: string) => Effect.Effect<void, never, InTurn>;
+};
+export {};

package/dist/handles/intents.js

@@ -0,0 +1,214 @@
+import { Context, DateTime, Duration, Effect, Schema } from "effect";
+import { System, } from "../identity/caller.js";
+/** When a staged intent becomes due: relative to the turn's commit, or at an instant. */
+export const Due = Schema.TaggedUnion({
+    After: { millis: Schema.Int },
+    At: { epochMillis: Schema.Int },
+});
+/** The outbox of a turn that staged nothing. */
+export const emptyOutbox = {
+    intents: [],
+    replaced: [],
+    jobs: [],
+    subscriptions: [],
+    cancelledJobs: [],
+};
+/** Job keys live in the actor's key namespace under this prefix, which intent keys may not use. */
+export const JOB_KEY_PREFIX = "$job:";
+const checkKey = (what, key) => {
+    if (key.length === 0 || key.length > 200)
+        throw new Error(`${what} must be 1-200 characters`);
+};
+/**
+ * Outbox keys the framework writes: `$`-prefixed keys and JSON arrays whose
+ * first element is `$`-prefixed. An application key of that shape could
+ * replace or cancel a framework row of the same actor.
+ */
+const isFrameworkKey = (key) => key.startsWith("$") || key.startsWith('["$');
+/**
+ * Marks a command turn. Only the runtime provides it, and `X.toLayer` removes
+ * it from handler requirements, so `X.intents` and `Intent.cancel` outside a
+ * command turn leave an unsatisfiable requirement.
+ */
+export class InTurn extends Context.Service()("@rikalabs/akter/handles/intents/InTurn") {
+}
+/** Keyed by the provided marker, so a hand-built `InTurn` value stages nothing. */
+const stagings = new WeakMap();
+const mintKey = (ref) => JSON.stringify([ref.actor, ref.id]);
+const isSystem = Schema.is(System);
+const creates = (intent, child, createdBy) => intent.command === createdBy &&
+    intent.target.actor === child.actor &&
+    intent.target.id === child.id;
+/**
+ * Opens the outbox of one command turn; `close` returns what it staged and
+ * seals it. A staged job's routes deliver to the enqueuing actor as the job,
+ * on the turn's principal.
+ */
+export const openOutbox = ({ sender, commandId, head, onBehalfOf, }) => {
+    const marker = InTurn.of({ turn: Symbol() });
+    const staging = {
+        sender,
+        commandId,
+        head,
+        onBehalfOf,
+        minted: new Map(),
+        open: true,
+        intents: [],
+        replaced: new Set(),
+        jobs: [],
+        subscriptions: new Map(),
+        cancelledJobs: new Set(),
+    };
+    stagings.set(marker, staging);
+    return {
+        marker,
+        /** Stages a job; the caller checks that its turn is still running. */
+        enqueue: (job) => {
+            if (job.key !== undefined)
+                cancelJobKey(staging, job.key);
+            staging.jobs.push({
+                ...job,
+                caller: System.make({ source: "job", ref: sender, onBehalfOf }),
+            });
+        },
+        /** Stages the cancellation of the job with `key`; the caller checks the turn. */
+        cancelJob: (key) => cancelJobKey(staging, key),
+        /** The proof the next `turn.mint` call of this turn carries. */
+        nextMint: () => ({ commandId, ordinal: staging.minted.size }),
+        /** Records a minted id; its creating intent then carries `proof`. */
+        minted: (child, createdBy, proof) => {
+            staging.minted.set(mintKey(child), { child, createdBy, proof });
+            staging.intents = staging.intents.map((intent) => creates(intent, child, createdBy) && isSystem(intent.caller)
+                ? {
+                    ...intent,
+                    caller: System.make({
+                        source: intent.caller.source,
+                        ref: intent.caller.ref,
+                        onBehalfOf: intent.caller.onBehalfOf,
+                        mint: proof,
+                    }),
+                }
+                : intent);
+        },
+        /** A minted actor that no staged intent to its creating command targets, if any. */
+        uncreated: () => {
+            for (const { child, createdBy, proof } of staging.minted.values())
+                if (!staging.intents.some((intent) => creates(intent, child, createdBy) &&
+                    isSystem(intent.caller) &&
+                    intent.caller.mint?.commandId === proof.commandId &&
+                    intent.caller.mint.ordinal === proof.ordinal))
+                    return child;
+            return undefined;
+        },
+        /**
+         * A minted actor whose creating intent has a key, if any: a later keyed
+         * intent or cancel could remove it before delivery and leave the id uncreated.
+         */
+        keyedCreation: () => {
+            for (const { child, createdBy } of staging.minted.values())
+                if (staging.intents.some((intent) => creates(intent, child, createdBy) && intent.key !== undefined))
+                    return child;
+            return undefined;
+        },
+        /** Stages a subscription change; a later change for the same source replaces it. */
+        subscribe: (change) => {
+            staging.subscriptions.set(JSON.stringify([change.subscription, change.source.actor, change.source.id]), change);
+        },
+        close: () => {
+            staging.open = false;
+            return {
+                intents: staging.intents,
+                replaced: [...staging.replaced],
+                jobs: staging.jobs,
+                subscriptions: [...staging.subscriptions.values()],
+                cancelledJobs: [...staging.cancelledJobs],
+            };
+        },
+    };
+};
+const IntentSettings = Context.Reference("akter/IntentSettings", {
+    defaultValue: () => ({}),
+});
+/** Validates a job key (1-200 characters) and returns it prefixed as it is staged and stored. */
+export const jobKey = (key) => {
+    checkKey("A job key", key);
+    return `${JOB_KEY_PREFIX}${key}`;
+};
+const cancelJobKey = (staging, key) => {
+    staging.jobs = staging.jobs.filter((job) => job.key !== key);
+    staging.cancelledJobs.add(key);
+};
+const replaceKey = (staging, key) => {
+    staging.intents = staging.intents.filter((intent) => intent.key !== key);
+    staging.replaced.add(key);
+};
+/** The staging area of the running turn, checked against `marker` when given; dies once the turn ended, so a capability that escaped its turn stages nothing. */
+export const currentStaging = Effect.fnUntraced(function* (marker) {
+    const current = yield* InTurn;
+    const staging = stagings.get(current);
+    if (staging === undefined || !staging.open || (marker !== undefined && marker !== current))
+        return yield* Effect.die(new Error("Intent capability escaped its turn"));
+    return { marker: current, staging };
+});
+/**
+ * Stages `intent` in the running turn's outbox with the ambient `Intent`
+ * settings. The receiver sees the sending actor, attributed to the sending
+ * turn's principal; only a minted child's creating intent carries the proof
+ * that lets it create the child.
+ */
+export const stageIntent = Effect.fnUntraced(function* (marker, intent) {
+    const { staging } = yield* currentStaging(marker);
+    const { due, key } = yield* IntentSettings;
+    const minted = staging.minted.get(mintKey(intent.target));
+    const attribution = {
+        source: due === undefined ? "actor" : "timer",
+        ref: staging.sender,
+        onBehalfOf: staging.onBehalfOf,
+    };
+    const caller = minted?.createdBy === intent.command
+        ? System.make({ ...attribution, mint: minted.proof })
+        : System.make(attribution);
+    if (key !== undefined)
+        replaceKey(staging, key);
+    staging.intents.push({ ...intent, due, key, caller });
+});
+const configure = (options) => (self) => Effect.gen(function* () {
+    const outer = yield* IntentSettings;
+    return yield* Effect.provideService(self, IntentSettings, { ...options, ...outer });
+});
+/**
+ * Options for intents staged by the piped Effect. The outermost setting wins,
+ * so a later `pipe` step overrides an earlier one.
+ */
+export const Intent = {
+    /** Delivers no earlier than `duration` after the turn commits. */
+    after: (duration) => {
+        const millis = Duration.toMillis(duration);
+        if (!Number.isFinite(millis) || millis < 0)
+            throw new Error("Intent.after needs a finite, non-negative duration");
+        return configure({ due: Due.cases.After.make({ millis: Math.ceil(millis) }) });
+    },
+    /** Delivers no earlier than `instant`, measured on the database clock. */
+    at: (instant) => configure({ due: Due.cases.At.make({ epochMillis: DateTime.toEpochMillis(instant) }) }),
+    /**
+     * Names the intent within its sending actor. Staging another intent with the
+     * same key, in this turn or a later one, replaces it while it is pending.
+     */
+    key: (key) => {
+        checkKey("Intent.key", key);
+        if (key.startsWith(JOB_KEY_PREFIX))
+            throw new Error(`Intent key "${key}" is reserved for jobs`);
+        if (isFrameworkKey(key))
+            throw new Error("Intent.key values starting with $ are reserved");
+        return configure({ key });
+    },
+    /** Removes the sending actor's pending intent with `key` when this turn commits. */
+    cancel: (key) => Effect.gen(function* () {
+        if (key.startsWith(JOB_KEY_PREFIX))
+            return yield* Effect.die(new Error(`Intent key "${key}" is reserved for jobs`));
+        if (isFrameworkKey(key))
+            return yield* Effect.die(new Error("Intent.key values starting with $ are reserved"));
+        const { staging } = yield* currentStaging();
+        replaceKey(staging, key);
+    }),
+};

package/dist/handles/run.d.ts

@@ -0,0 +1,31 @@
+import { Effect, Exit, Option } from "effect";
+import { Workflow as EffectWorkflow } from "effect/workflow";
+import { type RecordedExit } from "../contexts/workflow.ts";
+import type { ActorError } from "../errors/actor.ts";
+import type { AnyWorkflow } from "../members/workflow.ts";
+import type { WorkflowStatus } from "../runtime/members.ts";
+type PollReason = "ActorUnavailable" | "Unauthorized" | "Timeout";
+type CommandReason = "ActorUnavailable" | "CommandConflict" | "CommandExpired" | "InvalidCommandId" | "Unauthorized" | "Timeout" | "RunnerAtCapacity";
+/** One workflow execution, from a start or `X.run(member, executionId)`. */
+export interface WorkflowRun<W extends AnyWorkflow> {
+    readonly executionId: string;
+    /** `None` for an unknown execution; `Suspended` until it finishes. */
+    readonly poll: Effect.Effect<Option.Option<EffectWorkflow.Result<W["success"]["Type"], W["error"]["Type"]>>, ActorError.Of<PollReason>>;
+    /** Polls until the execution finishes; an interrupted execution interrupts. */
+    readonly result: Effect.Effect<W["success"]["Type"], W["error"]["Type"] | ActorError.Of<PollReason>>;
+    /** Durably interrupts the execution; idempotent, and a no-op once it finished. */
+    readonly interrupt: Effect.Effect<void, ActorError.Of<CommandReason>>;
+}
+/** Builds the run of one execution from its owner's poll and interrupt. */
+export declare const workflowRun: <W extends AnyWorkflow>(options: {
+    readonly executionId: string;
+    readonly poll: Effect.Effect<WorkflowStatus | undefined, ActorError>;
+    readonly interrupt: Effect.Effect<void, ActorError>;
+    readonly decode: (recorded: RecordedExit) => Effect.Effect<Exit.Exit<W["success"]["Type"], W["error"]["Type"]>>;
+}) => {
+    executionId: string;
+    poll: Effect.Effect<Option.Option<EffectWorkflow.Result<W["success"]["Type"], W["error"]["Type"]>>, ActorError, never>;
+    result: Effect.Effect<W["success"]["Type"], ActorError | W["error"]["Type"], never>;
+    interrupt: Effect.Effect<void, ActorError, never>;
+};
+export {};

package/dist/handles/run.js

@@ -0,0 +1,21 @@
+import { Effect, Exit, Option, Schedule } from "effect";
+import { Workflow as EffectWorkflow } from "effect/workflow";
+import { StoredResult } from "../contexts/workflow.js";
+const RESULT_POLL = Schedule.spaced("100 millis");
+/** Builds the run of one execution from its owner's poll and interrupt. */
+export const workflowRun = (options) => {
+    const poll = Effect.gen(function* () {
+        const status = yield* options.poll;
+        if (status === undefined)
+            return Option.none();
+        if (!status.finished || status.result === undefined)
+            return Option.some(EffectWorkflow.Suspended.make({}));
+        const recorded = status.result;
+        const exit = StoredResult.guards.Interrupt(recorded)
+            ? Exit.interrupt()
+            : yield* options.decode(recorded);
+        return Option.some(new EffectWorkflow.Complete({ exit }));
+    });
+    const result = poll.pipe(Effect.map(Option.filter((found) => found instanceof EffectWorkflow.Complete)), Effect.repeat({ until: Option.isSome, schedule: RESULT_POLL }), Effect.flatMap((found) => Option.getOrThrow(found).exit));
+    return { executionId: options.executionId, poll, result, interrupt: options.interrupt };
+};

package/dist/handles/workflow.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+/** The framework command that starts a workflow execution; its payload is a `StartPayload`. */
+export declare const START = "$workflow/start";
+/** The framework command that re-runs an execution's body after a wake, timer, or new event; its payload is an `ExecutionTarget`. */
+export declare const RESUME = "$workflow/resume";
+/** The framework command that durably interrupts an execution; its payload is an `ExecutionTarget`. */
+export declare const INTERRUPT = "$workflow/interrupt";
+/** Names one execution in a resume or interrupt payload. */
+export declare const ExecutionTarget: Schema.fromJsonString<Schema.Struct<{
+    readonly executionId: Schema.String;
+}>>;
+/**
+ * A workflow start staged as an intent. `after` is the owner's event
+ * sequence before the staging turn's emits when the owner staged it, so its
+ * waits see every owner event from that turn on, even ones committed before
+ * the start is delivered.
+ */
+export declare const StartPayload: Schema.fromJsonString<Schema.Struct<{
+    readonly workflow: Schema.String;
+    readonly input: Schema.String;
+    readonly key: Schema.String;
+    readonly after: Schema.NullOr<Schema.String>;
+}>>;
+/** A start's output: the execution id. */
+export declare const ExecutionIdOutput: Schema.fromJsonString<Schema.Struct<{
+    readonly value: Schema.String;
+}>>;

package/dist/handles/workflow.js

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+/** The framework command that starts a workflow execution; its payload is a `StartPayload`. */
+export const START = "$workflow/start";
+/** The framework command that re-runs an execution's body after a wake, timer, or new event; its payload is an `ExecutionTarget`. */
+export const RESUME = "$workflow/resume";
+/** The framework command that durably interrupts an execution; its payload is an `ExecutionTarget`. */
+export const INTERRUPT = "$workflow/interrupt";
+/** Names one execution in a resume or interrupt payload. */
+export const ExecutionTarget = Schema.fromJsonString(Schema.Struct({ executionId: Schema.String }));
+/**
+ * A workflow start staged as an intent. `after` is the owner's event
+ * sequence before the staging turn's emits when the owner staged it, so its
+ * waits see every owner event from that turn on, even ones committed before
+ * the start is delivered.
+ */
+export const StartPayload = Schema.fromJsonString(Schema.Struct({
+    workflow: Schema.String,
+    input: Schema.String,
+    key: Schema.String,
+    after: Schema.NullOr(Schema.String),
+}));
+/** A start's output: the execution id. */
+export const ExecutionIdOutput = Schema.fromJsonString(Schema.Struct({ value: Schema.String }));