@smthrs/flow 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Flow/Flow.d.ts

@@ -0,0 +1,422 @@
+/**
+ * Defines typed durable flow declarations.
+ *
+ * A `Flow` has a stable tag, schemas for payload, success, and failure, a
+ * REQUIRED pure `body`, and an optional idempotency key used to derive
+ * execution ids when the caller does not provide one. Flow definitions can be
+ * executed, discarded, polled, interrupted, and resumed.
+ *
+ * The two nouns of `docs/concepts/flows-and-actions.md` divide the
+ * surface here: an Action carries an implementation, attached separately as a
+ * Layer; a Flow carries a body, and never opaque executable code. There is
+ * therefore no handler to attach to a flow, and no `toLayer` on one to attach
+ * it with.
+ *
+ * @since 0.1.0
+ */
+import type * as Node from "@smthrs/plan/Node";
+import type * as Planned from "@smthrs/plan/Planned";
+import type * as Cause from "effect/Cause";
+import type * as Context from "effect/Context";
+import type * as Crypto from "effect/Crypto";
+import type * as Duration from "effect/Duration";
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+import type { Declared, PlannedPayload, Requirement } from "../Action/Action.ts";
+import type { CancelRequestFailed } from "../FlowRuntime/CancelRequestFailed.ts";
+import type { ExecutionIdentityConflict } from "../FlowRuntime/ExecutionIdentityConflict.ts";
+import type { FlowCycleDetected } from "../FlowRuntime/FlowCycleDetected.ts";
+import type { FlowExecutionNotFound } from "../FlowRuntime/FlowExecutionNotFound.ts";
+import type { FlowInstance, FlowRuntime } from "../FlowRuntime/index.ts";
+import type * as RetryPolicy from "../RetryPolicy.ts";
+import type { Outcome, To } from "./Outcome.ts";
+import type { Result } from "./Result.ts";
+import type { TypeId } from "./TypeId.ts";
+/**
+ * Values with which a flow body may settle one round.
+ *
+ * A plain decoded success completes the flow. A planned success is a symbolic
+ * reference the graph resolves before settlement. An outcome either completes
+ * explicitly, hands off to another round, or parks durably.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type BodySuccess<A> = A | Planned.Planned<A> | Outcome<A | Planned.Planned<A>, unknown>;
+/**
+ * A primary model seat with optional ordered fallback seats.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type ModelSelection = string | readonly [string, ...Array<string>];
+/**
+ * Literal metadata a catalog can read without executing the declaration.
+ * Model selection and system teaching are interpreted by the host.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface DeclarationMetadata {
+    readonly model?: ModelSelection | undefined;
+    readonly effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    readonly system?: ReadonlyArray<string> | undefined;
+    readonly chat?: boolean | undefined;
+    readonly flows?: ReadonlyArray<string> | undefined;
+}
+/**
+ * A typed prompt declaration lowered to an ordinary declared action.
+ * The host supplies that action's implementation; planning never renders it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface PromptFlow<Tag extends string, Payload extends AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top> extends Flow<Tag, Payload, Success, Error, Requirement<`${Tag}/prompt`>> {
+    readonly prompt: (payload: Payload["Type"]) => string;
+    readonly action: Declared<`${Tag}/prompt`, Payload, Success, Error>;
+    annotate<I, S>(tag: Context.Key<I, S>, value: S): PromptFlow<Tag, Payload, Success, Error>;
+    annotateMerge<I>(context: Context.Context<I>): PromptFlow<Tag, Payload, Success, Error>;
+}
+/**
+ * Durable flow definition with typed payload, success, and error schemas
+ * plus operations for execution, polling, interruption, resumption, and
+ * registration.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Flow<Tag extends string, Payload extends AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, Requires = never> extends DeclarationMetadata {
+    new (_: never): {};
+    readonly [TypeId]: typeof TypeId;
+    readonly _tag: Tag;
+    /**
+     * One sentence saying what this flow does, for a catalog that lists it.
+     *
+     * It is a plain literal rather than an annotation because a discovered
+     * `flows/<name>/flow.ts` is read WITHOUT being imported: `@smthrs/registry`
+     * tokenizes the declaration and takes the description from it, so a flow that
+     * states one only in an annotation is listed with nothing to read.
+     */
+    readonly description?: string | undefined;
+    readonly payloadSchema: Payload;
+    readonly successSchema: Success;
+    readonly errorSchema: Error;
+    readonly annotations: Context.Context<never>;
+    /** The renderer a prompt declaration supplies to its host. */
+    readonly prompt?: ((payload: Payload["Type"]) => string) | undefined;
+    /** The ordinary action a prompt declaration asks its host to implement. */
+    readonly action?: Declared<any, Payload, Success, Error, any> | undefined;
+    /**
+     * The pure plan-time body that IS this flow's behavior.
+     *
+     * The payload is decoded real data and the returned node only describes
+     * topology. It is a FIELD rather than an injectable layer because there is
+     * exactly one of it, it is pure, and its digest enters the flow's content
+     * identity, so a flow cannot plan one way under one wiring and another way
+     * under another. Purity includes closure capture: the body must not read
+     * mutable module state, clocks, random values, services, or environment
+     * values captured outside `payload`; source-digest identity cannot observe
+     * those aliases changing. Work that genuinely wants opaque code is an
+     * Action.
+     *
+     * `Requires` is read off this node. A body that names an action names an
+     * implementation it does not carry, and that obligation travels with the flow
+     * until something executes it.
+     */
+    readonly body: (payload: Payload["Type"]) => Node.Node<BodySuccess<Success["Type"]>, Error["Type"], Requires>;
+    /**
+     * Declares the stable key used when a caller supplies no execution id.
+     *
+     * The flow tag and returned key are JSON-tuple framed, then hashed as their
+     * exact UTF-8 strings. No Unicode normalization is applied, and this preimage
+     * encoding freezes at rc.0.
+     */
+    readonly idempotencyKey?: ((payload: Payload["Type"]) => string) | undefined;
+    /**
+     * How long ONE CALLER keeps polling a suspended execution of this flow.
+     *
+     * It is a per-caller wall-clock budget, not a bound on the run. `execute`
+     * re-drives a parked execution on this schedule and gives up when the
+     * schedule is spent; the execution stays parked, and the next caller — a
+     * second process, a sweep, a resume — starts a budget of its own. Nothing
+     * about it is durable, and a spent budget cancels nothing.
+     *
+     * What bounds work durably is an action's own `RetryPolicy`: the engine
+     * restores `maxAttempts` from the persisted attempt sequence and the
+     * `expirationMs` origin from the first attempt's start time, so those
+     * survive park, resume, and process death.
+     */
+    readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined;
+    /**
+     * How many rounds one trampoline lineage started from this flow may open.
+     *
+     * The bound is a BUDGET, not loop detection: identical consecutive rounds
+     * are legal, so `docs/concepts/trampoline-rounds.md` stops a runaway
+     * lineage by counting rounds instead of comparing them. Absent means
+     * unbounded, which is the right default for a lineage whose exit condition
+     * is its own branch. Exceeding it terminates the lineage with a
+     * {@link module:MaxRoundsExceeded.MaxRoundsExceeded} defect recorded in the
+     * execution result; it is not a typed `execute` failure.
+     */
+    readonly maxRounds?: number | undefined;
+    /**
+     * How long one execution of this flow may take, counted from its first
+     * start.
+     *
+     * The start is journaled, so the bound survives park, resume and process
+     * death: a restarted engine honors the original deadline. On expiry the
+     * execution settles with a {@link module:DeadlineExceeded.DeadlineExceeded}
+     * defect whether it was running or parked, and its attached children are
+     * cancelled with it. Absent means unbounded.
+     */
+    readonly deadline?: Duration.Duration | undefined;
+    /**
+     * Describes an inline call to this flow without executing it.
+     *
+     * The callee's steps join the caller's plan, so the callee's requirements are
+     * the caller's: `Requires` propagates.
+     */
+    readonly call: (payload: PlannedPayload<Payload["~type.make.in"]>) => Node.Node<Success["Type"], Error["Type"], Requires>;
+    /**
+     * Describes an explicit child boundary: ONE node in the caller's plan, and a
+     * real child execution when that node is driven.
+     *
+     * `.call()` splices this flow's body into the caller's plan, so every inner
+     * step is visible and individually keyed. `.child()` is the other choice
+     * `docs/concepts/flows-and-actions.md` gives: the callee keeps its
+     * own execution, journal lineage, retry policy, and placement, and the caller
+     * sees one leaf. It is also the way out of the two build refusals inline
+     * expansion raises — a recursive `.call()` and a placement the caller cannot
+     * satisfy.
+     *
+     * It is an execution boundary for requirements too, so `Requires` is DROPPED
+     * rather than propagated: the child runs under its own driver, which provides
+     * its own context, and the caller's plan holds one leaf naming it.
+     */
+    readonly child: (payload: PlannedPayload<Payload["~type.make.in"]>) => Node.Node<Success["Type"], Error["Type"]>;
+    /**
+     * Describes a serializable invocation for the next trampoline round.
+     *
+     * A handoff ends this execution and names the next one, so `Requires` is
+     * DROPPED here as well. That is also what keeps a self-loop's type finite: a
+     * body that hands off to its own flow would otherwise have to name its own
+     * requirements inside them.
+     */
+    readonly to: (payload: PlannedPayload<Payload["~type.make.in"]>) => Node.Node<To<Payload["Type"]>>;
+    /**
+     * Add an annotation to the flow.
+     */
+    annotate<I, S>(key: Context.Key<I, S>, value: S): Flow<Tag, Payload, Success, Error, Requires>;
+    /**
+     * Merge multiple annotations into the flow.
+     */
+    annotateMerge<I>(annotations: Context.Context<I>): Flow<Tag, Payload, Success, Error, Requires>;
+    /**
+     * Execute the flow with the given payload.
+     *
+     * This is where `Requires` is collected. Planning is requirement-free by
+     * design, so a body that names an action nobody implemented is a legal plan
+     * right up to here; asking to RUN it is what makes the missing layer a
+     * compile error rather than a run that dies partway through.
+     *
+     * Identity comes from the first source that has one: the `executionId`
+     * option, the flow's declared `idempotencyKey`, then the ambient
+     * `CurrentExecutionIds` source, whose default mints a fresh UUID. Equal
+     * unkeyed payloads start independent executions. Retain the execution id or
+     * opt into a derived source to reattach after a crash.
+     *
+     * A payload that fails the flow's own schema is a typed
+     * `Schema.SchemaError` failure carrying the offending field path — caller
+     * input is data, not programmer wiring, so it fails rather than dies.
+     */
+    readonly execute: <const Discard extends boolean = false>(payload: Payload["~type.make.in"], options?: {
+        readonly discard?: Discard;
+        readonly executionId?: string | undefined;
+    }) => Effect.Effect<Discard extends true ? string : Success["Type"], Schema.SchemaError | FlowCycleDetected | ExecutionIdentityConflict | (Discard extends true ? never : Error["Type"]), FlowRuntime | Crypto.Crypto | Requires | Payload["EncodingServices"] | Success["DecodingServices"] | Error["DecodingServices"]>;
+    /**
+     * Starts a fresh execution and returns its id. Equal payloads start independent
+     * executions; declared and ambient idempotency policies are intentionally bypassed.
+     * Observe the execution with `poll`, or await it using `execute` with this id.
+     */
+    readonly start: (payload: Payload["~type.make.in"]) => Effect.Effect<string, Schema.SchemaError | FlowCycleDetected, FlowRuntime | Crypto.Crypto | Requires | Payload["EncodingServices"] | Success["DecodingServices"] | Error["DecodingServices"]>;
+    /**
+     * Starts or joins the execution identified by this flow tag and an explicit
+     * caller key, returning its id. Reusing a key is an explicit retry/reattachment
+     * decision. Existing persisted key encodings remain unchanged.
+     */
+    readonly ensure: (payload: Payload["~type.make.in"], options: {
+        readonly key: string;
+    }) => ReturnType<Flow<Tag, Payload, Success, Error, Requires>["start"]>;
+    /**
+     * Poll the current status of a flow execution.
+     *
+     * `Option.none` means the execution is known and has not settled;
+     * {@link FlowExecutionNotFound} means the runtime has no record of the
+     * execution id at all.
+     */
+    readonly poll: (executionId: string) => Effect.Effect<Option.Option<Result<Success["Type"], Error["Type"]>>, FlowExecutionNotFound, FlowRuntime | Success["DecodingServices"] | Error["DecodingServices"]>;
+    /**
+     * Requests cancellation of the execution.
+     *
+     * This is not a pause operation. The engine interrupts active work while
+     * preserving its normal cleanup, compensation, and child-flow semantics.
+     * Calling `resume` does not undo the cancellation request.
+     *
+     * A durable engine records the cancellation request before it interrupts
+     * anything, and reports {@link CancelRequestFailed} when that record could
+     * not be written — the execution is then still running, so the caller sees
+     * the storage failure instead of a false success. An in-memory engine has
+     * nothing to record and never raises it.
+     */
+    readonly interrupt: (executionId: string) => Effect.Effect<void, CancelRequestFailed, FlowRuntime>;
+    /**
+     * Re-drives an execution that returned `Suspended` so it can replay its
+     * durable history and continue after its awaited condition becomes ready.
+     *
+     * This does not resume an execution cancelled by `interrupt`, and it is not
+     * needed for an execution that is already running or complete.
+     *
+     * It does NOT collect `Requires`, even though it re-drives the body. The
+     * runtime captures the context a flow was REGISTERED under and merges it
+     * beneath whatever a run supplies, so the implementations that made the first
+     * round possible are the ones a re-driven round reaches; a resumer holding an
+     * execution id is not the party that has them. `execute` remains the one
+     * place a plan's requirements are asked for.
+     */
+    readonly resume: (executionId: string) => Effect.Effect<void, never, FlowRuntime>;
+    /**
+     * For the given payload, compute the execution ID `execute` would run under
+     * when the caller names none.
+     *
+     * That is the flow's `idempotencyKey` when it declares one, and the ambient
+     * `CurrentExecutionIds` source otherwise. It dies with `ExecutionIdRequired`
+     * when the opt-in `derived` source cannot canonicalize the payload. The default
+     * source mints a fresh UUID on each call; pass the returned id explicitly to
+     * `execute` to select that invocation.
+     *
+     * A payload this flow's own schema refuses also dies as a defect here. This
+     * differs from `execute`, which fails with a typed `Schema.SchemaError` for
+     * the same caller input. A caller precomputing an id should validate the
+     * payload first.
+     */
+    readonly executionId: (payload: Payload["~type.make.in"]) => Effect.Effect<string, never, Crypto.Crypto | Payload["EncodingServices"]>;
+    /**
+     * Runs an effect and registers how to undo its successful result if the
+     * current round later exits unsuccessfully.
+     *
+     * If the effect itself fails, no rollback is registered. If both the effect
+     * and the round succeed, the rollback is discarded. Otherwise the rollback
+     * receives the effect's successful value and the round's failure cause when
+     * the round's scope closes. Suspension keeps that scope open.
+     *
+     * A handoff completes the round successfully and discards its `withRollback` registrations.
+     * A later round's failure cannot invoke those rollbacks. The engine does not
+     * provide lineage-scoped compensation.
+     *
+     * This applies only to effects run directly inside the flow execution. It
+     * does not attach rollback behavior to nested actions.
+     */
+    readonly withRollback: {
+        <A, R2>(rollback: (value: A, cause: Cause.Cause<Error["Type"]>) => Effect.Effect<void, never, R2>): <E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope>;
+        <A, E, R, R2>(effect: Effect.Effect<A, E, R>, rollback: (value: A, cause: Cause.Cause<Error["Type"]>) => Effect.Effect<void, never, R2>): Effect.Effect<A, E, R | R2 | FlowInstance | Scope.Scope>;
+    };
+}
+/**
+ * Schema constraint for flow payload schemas that expose struct fields.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export interface AnyStructSchema extends Schema.Top {
+    readonly fields: Schema.Struct.Fields;
+}
+/**
+ * Type-level marker for services associated with a specific flow
+ * execution tag.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Execution<Tag extends string> {
+    readonly _: unique symbol;
+    readonly _tag: Tag;
+}
+/**
+ * Type-erased flow shape for APIs that operate on flows without
+ * preserving their specific payload, success, or error types.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Any extends DeclarationMetadata {
+    new (_: never): {};
+    readonly [TypeId]: typeof TypeId;
+    readonly _tag: string;
+    readonly description?: string | undefined;
+    readonly executionId: (payload: any) => Effect.Effect<string, never, any>;
+    readonly payloadSchema: AnyStructSchema;
+    readonly successSchema: Schema.Top;
+    readonly errorSchema: Schema.Top;
+    readonly annotations: Context.Context<never>;
+    readonly prompt?: ((payload: any) => string) | undefined;
+    readonly action?: Pick<Declared<string, AnyStructSchema, Schema.Top, Schema.Top, any>, "name" | "payloadSchema" | "successSchema" | "errorSchema" | "implementationVersion" | "annotations"> | undefined;
+    readonly body: (payload: any) => Node.Node<unknown, unknown, any>;
+    readonly idempotencyKey?: ((payload: any) => string) | undefined;
+    readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined;
+    readonly maxRounds?: number | undefined;
+    readonly deadline?: Duration.Duration | undefined;
+}
+/**
+ * Type-erased flow shape that also exposes executable operations needed by
+ * flow proxy and engine helpers.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AnyWithProps extends Any {
+    readonly payloadSchema: AnyStructSchema;
+    readonly successSchema: Schema.Top;
+    readonly errorSchema: Schema.Top;
+    readonly execute: (payload: any, options?: {
+        readonly discard?: boolean;
+        readonly executionId?: string | undefined;
+    }) => Effect.Effect<any, any, any>;
+    /**
+     * Re-drives a durably suspended execution; it does not undo cancellation.
+     */
+    readonly resume: (executionId: string) => Effect.Effect<void, never, FlowRuntime>;
+}
+/**
+ * Extracts the payload schema from a `Flow`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type PayloadSchema<W> = W extends Flow<infer _Name, infer _Payload, infer _Success, infer _Error, infer _Requires> ? _Payload : never;
+/**
+ * Extracts the requirement channel of a `Flow`: the action implementations
+ * its body names and does not carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Requirements<W> = W extends Flow<infer _Name, infer _Payload, infer _Success, infer _Error, infer _Requires> ? _Requires : never;
+/**
+ * Computes the schema services required by clients that execute or poll
+ * flows.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RequirementsClient<Flows extends Any> = Flows extends Flow<infer _Name, infer _Payload, infer _Success, infer _Error, infer _Requires> ? _Payload["EncodingServices"] | _Success["DecodingServices"] | _Error["DecodingServices"] : never;
+/**
+ * Computes the schema services required by handlers that decode flow
+ * payloads and encode flow results.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RequirementsHandler<Flows extends Any> = Flows extends Flow<infer _Name, infer _Payload, infer _Success, infer _Error, infer _Requires> ? _Payload["DecodingServices"] | _Payload["EncodingServices"] | _Success["DecodingServices"] | _Success["EncodingServices"] | _Error["DecodingServices"] | _Error["EncodingServices"] : never;
+//# sourceMappingURL=Flow.d.ts.map

package/dist/esm/Flow/Flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Flow.d.ts","sourceRoot":"","sources":["../../../src/Flow/Flow.ts"],"names":[],"mappings":"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"}

package/dist/esm/Flow/Flow.js

@@ -0,0 +1,3 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+export {};
+//# sourceMappingURL=Flow.js.map

package/dist/esm/Flow/Flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Flow.js","sourceRoot":"","sources":["../../../src/Flow/Flow.ts"],"names":[],"mappings":"AAAA,uDAAuD","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Defines typed durable flow declarations.\n *\n * A `Flow` has a stable tag, schemas for payload, success, and failure, a\n * REQUIRED pure `body`, and an optional idempotency key used to derive\n * execution ids when the caller does not provide one. Flow definitions can be\n * executed, discarded, polled, interrupted, and resumed.\n *\n * The two nouns of `docs/concepts/flows-and-actions.md` divide the\n * surface here: an Action carries an implementation, attached separately as a\n * Layer; a Flow carries a body, and never opaque executable code. There is\n * therefore no handler to attach to a flow, and no `toLayer` on one to attach\n * it with.\n *\n * @since 0.1.0\n */\n\nimport type * as Node from \"@smthrs/plan/Node\"\nimport type * as Planned from \"@smthrs/plan/Planned\"\nimport type * as Cause from \"effect/Cause\"\nimport type * as Context from \"effect/Context\"\nimport type * as Crypto from \"effect/Crypto\"\nimport type * as Duration from \"effect/Duration\"\nimport type * as Effect from \"effect/Effect\"\nimport type * as Option from \"effect/Option\"\nimport type * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport type { Declared, PlannedPayload, Requirement } from \"../Action/Action.ts\"\nimport type { CancelRequestFailed } from \"../FlowRuntime/CancelRequestFailed.ts\"\nimport type { ExecutionIdentityConflict } from \"../FlowRuntime/ExecutionIdentityConflict.ts\"\nimport type { FlowCycleDetected } from \"../FlowRuntime/FlowCycleDetected.ts\"\nimport type { FlowExecutionNotFound } from \"../FlowRuntime/FlowExecutionNotFound.ts\"\nimport type { FlowInstance, FlowRuntime } from \"../FlowRuntime/index.ts\"\nimport type * as RetryPolicy from \"../RetryPolicy.ts\"\nimport type { Outcome, To } from \"./Outcome.ts\"\nimport type { Result } from \"./Result.ts\"\nimport type { TypeId } from \"./TypeId.ts\"\n\n/**\n * Values with which a flow body may settle one round.\n *\n * A plain decoded success completes the flow. A planned success is a symbolic\n * reference the graph resolves before settlement. An outcome either completes\n * explicitly, hands off to another round, or parks durably.\n *\n * @category models\n * @since 0.1.0\n */\nexport type BodySuccess<A> = A | Planned.Planned<A> | Outcome<A | Planned.Planned<A>, unknown>\n\n/**\n * A primary model seat with optional ordered fallback seats.\n *\n * @category models\n * @since 1.0.0\n */\nexport type ModelSelection = string | readonly [string, ...Array<string>]\n\n/**\n * Literal metadata a catalog can read without executing the declaration.\n * Model selection and system teaching are interpreted by the host.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface DeclarationMetadata {\n  readonly model?: ModelSelection | undefined\n  readonly effort?: \"none\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\" | undefined\n  readonly system?: ReadonlyArray<string> | undefined\n  readonly chat?: boolean | undefined\n  readonly flows?: ReadonlyArray<string> | undefined\n}\n\n/**\n * A typed prompt declaration lowered to an ordinary declared action.\n * The host supplies that action's implementation; planning never renders it.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface PromptFlow<\n  Tag extends string,\n  Payload extends AnyStructSchema,\n  Success extends Schema.Top,\n  Error extends Schema.Top\n> extends Flow<Tag, Payload, Success, Error, Requirement<`${Tag}/prompt`>> {\n  readonly prompt: (payload: Payload[\"Type\"]) => string\n  readonly action: Declared<`${Tag}/prompt`, Payload, Success, Error>\n  annotate<I, S>(tag: Context.Key<I, S>, value: S): PromptFlow<Tag, Payload, Success, Error>\n  annotateMerge<I>(context: Context.Context<I>): PromptFlow<Tag, Payload, Success, Error>\n}\n\n/**\n * Durable flow definition with typed payload, success, and error schemas\n * plus operations for execution, polling, interruption, resumption, and\n * registration.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Flow<\n  Tag extends string,\n  Payload extends AnyStructSchema,\n  Success extends Schema.Top,\n  Error extends Schema.Top,\n  Requires = never\n> extends DeclarationMetadata {\n  new(_: never): {}\n\n  readonly [TypeId]: typeof TypeId\n  readonly _tag: Tag\n  /**\n   * One sentence saying what this flow does, for a catalog that lists it.\n   *\n   * It is a plain literal rather than an annotation because a discovered\n   * `flows/<name>/flow.ts` is read WITHOUT being imported: `@smthrs/registry`\n   * tokenizes the declaration and takes the description from it, so a flow that\n   * states one only in an annotation is listed with nothing to read.\n   */\n  readonly description?: string | undefined\n  readonly payloadSchema: Payload\n  readonly successSchema: Success\n  readonly errorSchema: Error\n  readonly annotations: Context.Context<never>\n  /** The renderer a prompt declaration supplies to its host. */\n  readonly prompt?: ((payload: Payload[\"Type\"]) => string) | undefined\n  /** The ordinary action a prompt declaration asks its host to implement. */\n  readonly action?: Declared<any, Payload, Success, Error, any> | undefined\n  /**\n   * The pure plan-time body that IS this flow's behavior.\n   *\n   * The payload is decoded real data and the returned node only describes\n   * topology. It is a FIELD rather than an injectable layer because there is\n   * exactly one of it, it is pure, and its digest enters the flow's content\n   * identity, so a flow cannot plan one way under one wiring and another way\n   * under another. Purity includes closure capture: the body must not read\n   * mutable module state, clocks, random values, services, or environment\n   * values captured outside `payload`; source-digest identity cannot observe\n   * those aliases changing. Work that genuinely wants opaque code is an\n   * Action.\n   *\n   * `Requires` is read off this node. A body that names an action names an\n   * implementation it does not carry, and that obligation travels with the flow\n   * until something executes it.\n   */\n  readonly body: (payload: Payload[\"Type\"]) => Node.Node<BodySuccess<Success[\"Type\"]>, Error[\"Type\"], Requires>\n  /**\n   * Declares the stable key used when a caller supplies no execution id.\n   *\n   * The flow tag and returned key are JSON-tuple framed, then hashed as their\n   * exact UTF-8 strings. No Unicode normalization is applied, and this preimage\n   * encoding freezes at rc.0.\n   */\n  readonly idempotencyKey?: ((payload: Payload[\"Type\"]) => string) | undefined\n  /**\n   * How long ONE CALLER keeps polling a suspended execution of this flow.\n   *\n   * It is a per-caller wall-clock budget, not a bound on the run. `execute`\n   * re-drives a parked execution on this schedule and gives up when the\n   * schedule is spent; the execution stays parked, and the next caller — a\n   * second process, a sweep, a resume — starts a budget of its own. Nothing\n   * about it is durable, and a spent budget cancels nothing.\n   *\n   * What bounds work durably is an action's own `RetryPolicy`: the engine\n   * restores `maxAttempts` from the persisted attempt sequence and the\n   * `expirationMs` origin from the first attempt's start time, so those\n   * survive park, resume, and process death.\n   */\n  readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined\n  /**\n   * How many rounds one trampoline lineage started from this flow may open.\n   *\n   * The bound is a BUDGET, not loop detection: identical consecutive rounds\n   * are legal, so `docs/concepts/trampoline-rounds.md` stops a runaway\n   * lineage by counting rounds instead of comparing them. Absent means\n   * unbounded, which is the right default for a lineage whose exit condition\n   * is its own branch. Exceeding it terminates the lineage with a\n   * {@link module:MaxRoundsExceeded.MaxRoundsExceeded} defect recorded in the\n   * execution result; it is not a typed `execute` failure.\n   */\n  readonly maxRounds?: number | undefined\n  /**\n   * How long one execution of this flow may take, counted from its first\n   * start.\n   *\n   * The start is journaled, so the bound survives park, resume and process\n   * death: a restarted engine honors the original deadline. On expiry the\n   * execution settles with a {@link module:DeadlineExceeded.DeadlineExceeded}\n   * defect whether it was running or parked, and its attached children are\n   * cancelled with it. Absent means unbounded.\n   */\n  readonly deadline?: Duration.Duration | undefined\n\n  /**\n   * Describes an inline call to this flow without executing it.\n   *\n   * The callee's steps join the caller's plan, so the callee's requirements are\n   * the caller's: `Requires` propagates.\n   */\n  readonly call: (\n    payload: PlannedPayload<Payload[\"~type.make.in\"]>\n  ) => Node.Node<Success[\"Type\"], Error[\"Type\"], Requires>\n\n  /**\n   * Describes an explicit child boundary: ONE node in the caller's plan, and a\n   * real child execution when that node is driven.\n   *\n   * `.call()` splices this flow's body into the caller's plan, so every inner\n   * step is visible and individually keyed. `.child()` is the other choice\n   * `docs/concepts/flows-and-actions.md` gives: the callee keeps its\n   * own execution, journal lineage, retry policy, and placement, and the caller\n   * sees one leaf. It is also the way out of the two build refusals inline\n   * expansion raises — a recursive `.call()` and a placement the caller cannot\n   * satisfy.\n   *\n   * It is an execution boundary for requirements too, so `Requires` is DROPPED\n   * rather than propagated: the child runs under its own driver, which provides\n   * its own context, and the caller's plan holds one leaf naming it.\n   */\n  readonly child: (\n    payload: PlannedPayload<Payload[\"~type.make.in\"]>\n  ) => Node.Node<Success[\"Type\"], Error[\"Type\"]>\n\n  /**\n   * Describes a serializable invocation for the next trampoline round.\n   *\n   * A handoff ends this execution and names the next one, so `Requires` is\n   * DROPPED here as well. That is also what keeps a self-loop's type finite: a\n   * body that hands off to its own flow would otherwise have to name its own\n   * requirements inside them.\n   */\n  readonly to: (\n    payload: PlannedPayload<Payload[\"~type.make.in\"]>\n  ) => Node.Node<To<Payload[\"Type\"]>>\n\n  /**\n   * Add an annotation to the flow.\n   */\n  annotate<I, S>(\n    key: Context.Key<I, S>,\n    value: S\n  ): Flow<Tag, Payload, Success, Error, Requires>\n\n  /**\n   * Merge multiple annotations into the flow.\n   */\n  annotateMerge<I>(\n    annotations: Context.Context<I>\n  ): Flow<Tag, Payload, Success, Error, Requires>\n\n  /**\n   * Execute the flow with the given payload.\n   *\n   * This is where `Requires` is collected. Planning is requirement-free by\n   * design, so a body that names an action nobody implemented is a legal plan\n   * right up to here; asking to RUN it is what makes the missing layer a\n   * compile error rather than a run that dies partway through.\n   *\n   * Identity comes from the first source that has one: the `executionId`\n   * option, the flow's declared `idempotencyKey`, then the ambient\n   * `CurrentExecutionIds` source, whose default mints a fresh UUID. Equal\n   * unkeyed payloads start independent executions. Retain the execution id or\n   * opt into a derived source to reattach after a crash.\n   *\n   * A payload that fails the flow's own schema is a typed\n   * `Schema.SchemaError` failure carrying the offending field path — caller\n   * input is data, not programmer wiring, so it fails rather than dies.\n   */\n  readonly execute: <const Discard extends boolean = false>(\n    payload: Payload[\"~type.make.in\"],\n    options?: {\n      readonly discard?: Discard\n      readonly executionId?: string | undefined\n    }\n  ) => Effect.Effect<\n    Discard extends true ? string : Success[\"Type\"],\n    Schema.SchemaError | FlowCycleDetected | ExecutionIdentityConflict | (Discard extends true ? never : Error[\"Type\"]),\n    | FlowRuntime\n    | Crypto.Crypto\n    | Requires\n    | Payload[\"EncodingServices\"]\n    | Success[\"DecodingServices\"]\n    | Error[\"DecodingServices\"]\n  >\n\n  /**\n   * Starts a fresh execution and returns its id. Equal payloads start independent\n   * executions; declared and ambient idempotency policies are intentionally bypassed.\n   * Observe the execution with `poll`, or await it using `execute` with this id.\n   */\n  readonly start: (payload: Payload[\"~type.make.in\"]) => Effect.Effect<\n    string,\n    Schema.SchemaError | FlowCycleDetected,\n    | FlowRuntime\n    | Crypto.Crypto\n    | Requires\n    | Payload[\"EncodingServices\"]\n    | Success[\"DecodingServices\"]\n    | Error[\"DecodingServices\"]\n  >\n\n  /**\n   * Starts or joins the execution identified by this flow tag and an explicit\n   * caller key, returning its id. Reusing a key is an explicit retry/reattachment\n   * decision. Existing persisted key encodings remain unchanged.\n   */\n  readonly ensure: (\n    payload: Payload[\"~type.make.in\"],\n    options: { readonly key: string }\n  ) => ReturnType<Flow<Tag, Payload, Success, Error, Requires>[\"start\"]>\n\n  /**\n   * Poll the current status of a flow execution.\n   *\n   * `Option.none` means the execution is known and has not settled;\n   * {@link FlowExecutionNotFound} means the runtime has no record of the\n   * execution id at all.\n   */\n  readonly poll: (\n    executionId: string\n  ) => Effect.Effect<\n    Option.Option<Result<Success[\"Type\"], Error[\"Type\"]>>,\n    FlowExecutionNotFound,\n    FlowRuntime | Success[\"DecodingServices\"] | Error[\"DecodingServices\"]\n  >\n\n  /**\n   * Requests cancellation of the execution.\n   *\n   * This is not a pause operation. The engine interrupts active work while\n   * preserving its normal cleanup, compensation, and child-flow semantics.\n   * Calling `resume` does not undo the cancellation request.\n   *\n   * A durable engine records the cancellation request before it interrupts\n   * anything, and reports {@link CancelRequestFailed} when that record could\n   * not be written — the execution is then still running, so the caller sees\n   * the storage failure instead of a false success. An in-memory engine has\n   * nothing to record and never raises it.\n   */\n  readonly interrupt: (\n    executionId: string\n  ) => Effect.Effect<void, CancelRequestFailed, FlowRuntime>\n\n  /**\n   * Re-drives an execution that returned `Suspended` so it can replay its\n   * durable history and continue after its awaited condition becomes ready.\n   *\n   * This does not resume an execution cancelled by `interrupt`, and it is not\n   * needed for an execution that is already running or complete.\n   *\n   * It does NOT collect `Requires`, even though it re-drives the body. The\n   * runtime captures the context a flow was REGISTERED under and merges it\n   * beneath whatever a run supplies, so the implementations that made the first\n   * round possible are the ones a re-driven round reaches; a resumer holding an\n   * execution id is not the party that has them. `execute` remains the one\n   * place a plan's requirements are asked for.\n   */\n  readonly resume: (\n    executionId: string\n  ) => Effect.Effect<void, never, FlowRuntime>\n\n  /**\n   * For the given payload, compute the execution ID `execute` would run under\n   * when the caller names none.\n   *\n   * That is the flow's `idempotencyKey` when it declares one, and the ambient\n   * `CurrentExecutionIds` source otherwise. It dies with `ExecutionIdRequired`\n   * when the opt-in `derived` source cannot canonicalize the payload. The default\n   * source mints a fresh UUID on each call; pass the returned id explicitly to\n   * `execute` to select that invocation.\n   *\n   * A payload this flow's own schema refuses also dies as a defect here. This\n   * differs from `execute`, which fails with a typed `Schema.SchemaError` for\n   * the same caller input. A caller precomputing an id should validate the\n   * payload first.\n   */\n  readonly executionId: (\n    payload: Payload[\"~type.make.in\"]\n  ) => Effect.Effect<string, never, Crypto.Crypto | Payload[\"EncodingServices\"]>\n\n  /**\n   * Runs an effect and registers how to undo its successful result if the\n   * current round later exits unsuccessfully.\n   *\n   * If the effect itself fails, no rollback is registered. If both the effect\n   * and the round succeed, the rollback is discarded. Otherwise the rollback\n   * receives the effect's successful value and the round's failure cause when\n   * the round's scope closes. Suspension keeps that scope open.\n   *\n   * A handoff completes the round successfully and discards its `withRollback` registrations.\n   * A later round's failure cannot invoke those rollbacks. The engine does not\n   * provide lineage-scoped compensation.\n   *\n   * This applies only to effects run directly inside the flow execution. It\n   * does not attach rollback behavior to nested actions.\n   */\n  readonly withRollback: {\n    <A, R2>(\n      rollback: (\n        value: A,\n        cause: Cause.Cause<Error[\"Type\"]>\n      ) => Effect.Effect<void, never, R2>\n    ): <E, R>(\n      effect: Effect.Effect<A, E, R>\n    ) => Effect.Effect<\n      A,\n      E,\n      R | R2 | FlowInstance | Scope.Scope\n    >\n    <A, E, R, R2>(\n      effect: Effect.Effect<A, E, R>,\n      rollback: (\n        value: A,\n        cause: Cause.Cause<Error[\"Type\"]>\n      ) => Effect.Effect<void, never, R2>\n    ): Effect.Effect<\n      A,\n      E,\n      R | R2 | FlowInstance | Scope.Scope\n    >\n  }\n}\n\n/**\n * Schema constraint for flow payload schemas that expose struct fields.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport interface AnyStructSchema extends Schema.Top {\n  readonly fields: Schema.Struct.Fields\n}\n\n/**\n * Type-level marker for services associated with a specific flow\n * execution tag.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Execution<Tag extends string> {\n  readonly _: unique symbol\n  readonly _tag: Tag\n}\n\n/**\n * Type-erased flow shape for APIs that operate on flows without\n * preserving their specific payload, success, or error types.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Any extends DeclarationMetadata {\n  new(_: never): {}\n\n  readonly [TypeId]: typeof TypeId\n  readonly _tag: string\n  readonly description?: string | undefined\n  readonly executionId: (payload: any) => Effect.Effect<string, never, any>\n  readonly payloadSchema: AnyStructSchema\n  readonly successSchema: Schema.Top\n  readonly errorSchema: Schema.Top\n  readonly annotations: Context.Context<never>\n  readonly prompt?: ((payload: any) => string) | undefined\n  readonly action?:\n    | Pick<\n      Declared<string, AnyStructSchema, Schema.Top, Schema.Top, any>,\n      \"name\" | \"payloadSchema\" | \"successSchema\" | \"errorSchema\" | \"implementationVersion\" | \"annotations\"\n    >\n    | undefined\n  readonly body: (payload: any) => Node.Node<unknown, unknown, any>\n  readonly idempotencyKey?: ((payload: any) => string) | undefined\n  readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined\n  readonly maxRounds?: number | undefined\n  readonly deadline?: Duration.Duration | undefined\n}\n\n/**\n * Type-erased flow shape that also exposes executable operations needed by\n * flow proxy and engine helpers.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface AnyWithProps extends Any {\n  readonly payloadSchema: AnyStructSchema\n  readonly successSchema: Schema.Top\n  readonly errorSchema: Schema.Top\n  readonly execute: (\n    payload: any,\n    options?: {\n      readonly discard?: boolean\n      readonly executionId?: string | undefined\n    }\n  ) => Effect.Effect<any, any, any>\n  /**\n   * Re-drives a durably suspended execution; it does not undo cancellation.\n   */\n  readonly resume: (\n    executionId: string\n  ) => Effect.Effect<void, never, FlowRuntime>\n}\n\n/**\n * Extracts the payload schema from a `Flow`.\n *\n * @category models\n * @since 0.1.0\n */\nexport type PayloadSchema<W> = W extends Flow<\n  infer _Name,\n  infer _Payload,\n  infer _Success,\n  infer _Error,\n  infer _Requires\n> ? _Payload\n  : never\n\n/**\n * Extracts the requirement channel of a `Flow`: the action implementations\n * its body names and does not carry.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Requirements<W> = W extends Flow<\n  infer _Name,\n  infer _Payload,\n  infer _Success,\n  infer _Error,\n  infer _Requires\n> ? _Requires\n  : never\n\n/**\n * Computes the schema services required by clients that execute or poll\n * flows.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RequirementsClient<Flows extends Any> = Flows extends Flow<\n  infer _Name,\n  infer _Payload,\n  infer _Success,\n  infer _Error,\n  infer _Requires\n> ?\n    | _Payload[\"EncodingServices\"]\n    | _Success[\"DecodingServices\"]\n    | _Error[\"DecodingServices\"]\n  : never\n\n/**\n * Computes the schema services required by handlers that decode flow\n * payloads and encode flow results.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RequirementsHandler<Flows extends Any> = Flows extends Flow<\n  infer _Name,\n  infer _Payload,\n  infer _Success,\n  infer _Error,\n  infer _Requires\n> ?\n    | _Payload[\"DecodingServices\"]\n    | _Payload[\"EncodingServices\"]\n    | _Success[\"DecodingServices\"]\n    | _Success[\"EncodingServices\"]\n    | _Error[\"DecodingServices\"]\n    | _Error[\"EncodingServices\"]\n  : never\n"]}

package/dist/esm/Flow/MaxRoundsExceeded.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Defect recorded when a trampoline lineage runs past its declared round budget.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+declare const MaxRoundsExceeded_base: Schema.Class<MaxRoundsExceeded, Schema.TaggedStruct<"@smthrs/flow/MaxRoundsExceeded", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"max_rounds_exceeded">>;
+    readonly flowName: Schema.String;
+    readonly lineageId: Schema.String;
+    readonly maxRounds: Schema.Number;
+    readonly roundOrdinal: Schema.Number;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A lineage asked for one more round than its flow's `maxRounds` allows.
+ *
+ * `docs/concepts/trampoline-rounds.md` chooses a budget over loop
+ * detection: identical consecutive rounds are legal (a poller is exactly
+ * that), so the only honest stop condition is a declared bound on how many
+ * rounds one lineage may open. Exceeding it is terminal for the lineage — the
+ * round that asked for the handoff is settled with this defect rather than
+ * handed off — because a lineage that has run out of budget has nowhere left
+ * to continue, and letting it keep going would make the bound advisory.
+ *
+ * `roundOrdinal` is the zero-based ordinal of the round that was refused, so
+ * it always equals `maxRounds` when the refusal is raised.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class MaxRoundsExceeded extends MaxRoundsExceeded_base {
+}
+export {};
+//# sourceMappingURL=MaxRoundsExceeded.d.ts.map

package/dist/esm/Flow/MaxRoundsExceeded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaxRoundsExceeded.d.ts","sourceRoot":"","sources":["../../../src/Flow/MaxRoundsExceeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;;;;;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAkB,SAAQ,sBAYtC;CAAG"}

package/dist/esm/Flow/MaxRoundsExceeded.js

@@ -0,0 +1,34 @@
+/**
+ * Defect recorded when a trampoline lineage runs past its declared round budget.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * A lineage asked for one more round than its flow's `maxRounds` allows.
+ *
+ * `docs/concepts/trampoline-rounds.md` chooses a budget over loop
+ * detection: identical consecutive rounds are legal (a poller is exactly
+ * that), so the only honest stop condition is a declared bound on how many
+ * rounds one lineage may open. Exceeding it is terminal for the lineage — the
+ * round that asked for the handoff is settled with this defect rather than
+ * handed off — because a lineage that has run out of budget has nowhere left
+ * to continue, and letting it keep going would make the bound advisory.
+ *
+ * `roundOrdinal` is the zero-based ordinal of the round that was refused, so
+ * it always equals `maxRounds` when the refusal is raised.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class MaxRoundsExceeded extends Schema.TaggedError()("@smthrs/flow/MaxRoundsExceeded", {
+    code: Schema.Literal("max_rounds_exceeded").pipe(Schema.withConstructorDefault(Effect.succeed("max_rounds_exceeded"))),
+    flowName: Schema.String,
+    lineageId: Schema.String,
+    maxRounds: Schema.Number,
+    roundOrdinal: Schema.Number,
+    message: Schema.String
+}) {
+}
+//# sourceMappingURL=MaxRoundsExceeded.js.map

package/dist/esm/Flow/MaxRoundsExceeded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaxRoundsExceeded.js","sourceRoot":"","sources":["../../../src/Flow/MaxRoundsExceeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,MAAM,CAAC,WAAW,EAAqB,CAC5E,gCAAgC,EAChC;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAC9C,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,CACrE;IACD,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CACF;CAAG","sourcesContent":["/**\n * Defect recorded when a trampoline lineage runs past its declared round budget.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * A lineage asked for one more round than its flow's `maxRounds` allows.\n *\n * `docs/concepts/trampoline-rounds.md` chooses a budget over loop\n * detection: identical consecutive rounds are legal (a poller is exactly\n * that), so the only honest stop condition is a declared bound on how many\n * rounds one lineage may open. Exceeding it is terminal for the lineage — the\n * round that asked for the handoff is settled with this defect rather than\n * handed off — because a lineage that has run out of budget has nowhere left\n * to continue, and letting it keep going would make the bound advisory.\n *\n * `roundOrdinal` is the zero-based ordinal of the round that was refused, so\n * it always equals `maxRounds` when the refusal is raised.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class MaxRoundsExceeded extends Schema.TaggedError<MaxRoundsExceeded>()(\n  \"@smthrs/flow/MaxRoundsExceeded\",\n  {\n    code: Schema.Literal(\"max_rounds_exceeded\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"max_rounds_exceeded\"))\n    ),\n    flowName: Schema.String,\n    lineageId: Schema.String,\n    maxRounds: Schema.Number,\n    roundOrdinal: Schema.Number,\n    message: Schema.String\n  }\n) {}\n"]}