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

package/src/Flow/make.ts

@@ -0,0 +1,279 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Constructs executable flow declarations from schema and policy data.
+ *
+ * @since 0.1.0
+ */
+
+import type * as Effects from "@smthrs/plan/Effects"
+import * as Node from "@smthrs/plan/Node"
+import type * as Context from "effect/Context"
+import * as Duration from "effect/Duration"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import type { Declared } from "../Action/Action.ts"
+import * as Action from "../Action/make.ts"
+import { lowerDeclarations } from "../internal/Declarations.ts"
+import * as DeclarationSite from "../internal/DeclarationSite.ts"
+import type * as RetryPolicy from "../RetryPolicy.ts"
+import type { Any, AnyStructSchema, BodySuccess, DeclarationMetadata, Flow, PromptFlow } from "./Flow.ts"
+import { makeProto } from "./internal.ts"
+import { TypeId } from "./TypeId.ts"
+
+/**
+ * The declaration data every flow takes beside its body.
+ *
+ * @private
+ */
+interface MakeOptions<
+  Payload extends Schema.Struct.Fields | AnyStructSchema,
+  Success extends Schema.Top,
+  Error extends Schema.Top
+> extends DeclarationMetadata {
+  readonly payload: Payload
+  /**
+   * Native declaration whose source location this reconstructed flow retains.
+   * A source with no recorded location preserves that absence. This affects
+   * diagnostics only, never identity; the new flow keeps its own body and calls.
+   */
+  readonly declaredFrom?: object | undefined
+  /**
+   * One sentence saying what this flow does, read by a catalog that lists it.
+   */
+  readonly description?: string | undefined
+  /**
+   * The capability ceiling this flow's body runs under, as string literals.
+   *
+   * It is the same ceiling {@link Annotations.Capabilities} carries, and
+   * declaring it here is what makes it READABLE without importing the module:
+   * a catalog projects a discovered flow's authority from the declaration, and
+   * an annotation built at run time is invisible to that projection.
+   */
+  readonly capabilities?: ReadonlyArray<string> | undefined
+  /**
+   * The effect envelope this flow's body runs under, as a literal.
+   *
+   * It is the same declaration {@link Annotations.EffectEnvelope} carries, and
+   * declaring it here is what makes it READABLE without importing the module,
+   * exactly as `capabilities` is: a catalog projects a discovered flow's
+   * authority from the source text of this literal, and an annotation built at
+   * run time is invisible to that projection.
+   *
+   * {@link module:Graph.build} refuses a composition beneath this flow that
+   * reads or writes outside the envelope, loosens `hermetic` to `expected`, or
+   * raises the tier. `reads` and `writes` are normalized to sorted,
+   * duplicate-free arrays, so two spellings of one envelope are one envelope.
+   */
+  readonly effects?: Effects.MakeOptions | undefined
+  /**
+   * Whether a catalog may offer this flow to a model, as a literal. Defaults
+   * to `true`.
+   *
+   * It is the same statement {@link Annotations.ModelInvocable} carries, and
+   * declaring it here is what makes it READABLE without importing the module,
+   * exactly as `capabilities` and `effects` are: a registry projects a
+   * discovered flow's visibility from the source text of this literal onto the
+   * descriptor it lists, and an annotation built at run time is invisible to
+   * that projection.
+   *
+   * Declare `false` when the actions this flow's body calls are implemented by
+   * one host only. The file is discoverable wherever it sits, so a catalog
+   * elsewhere would otherwise teach an agent a call with no implementation to
+   * reach.
+   */
+  readonly modelInvocable?: boolean | undefined
+  readonly idempotencyKey?:
+    | ((
+      payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload>
+        : Payload["Type"]
+    ) => string)
+    | undefined
+  readonly success?: Success
+  readonly error?: Error
+  readonly suspendedRetryPolicy?: RetryPolicy.RetryPolicy | undefined
+  /**
+   * The round budget a trampoline lineage started from this flow runs under.
+   */
+  readonly maxRounds?: number | undefined
+  /**
+   * How long one execution may take, counted from its journaled first start.
+   * A positive finite duration; see {@link Flow.deadline}.
+   */
+  readonly deadline?: Duration.Input | undefined
+  readonly annotations?: Context.Context<never>
+}
+
+/**
+ * The pure plan-time body, typed with the decoded payload.
+ *
+ * @private
+ */
+type Body<
+  Payload extends Schema.Struct.Fields | AnyStructSchema,
+  Success extends Schema.Top,
+  Error extends Schema.Top,
+  Requires
+> = (
+  payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload> : Payload["Type"]
+) => Node.Node<BodySuccess<Success["Type"]>, Error["Type"], Requires>
+
+/**
+ * The payload schema a declaration's `payload` field stands for.
+ *
+ * @private
+ */
+type PayloadSchemaOf<Payload extends Schema.Struct.Fields | AnyStructSchema> = Payload extends Schema.Struct.Fields
+  ? Schema.Struct<Payload>
+  : Payload
+
+/**
+ * Whether a value is a flow this package made.
+ *
+ * The check is the runtime type id, not the shape: a host that loads a module
+ * and finds a default export has to decide whether it holds a flow before it
+ * reads anything off it, and a structural guess would accept a look-alike from
+ * another flow model.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const isFlow = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId)
+
+/**
+ * Creates a durable flow with one plan-time body or a typed prompt renderer.
+ * A prompt lowers to one ordinary action implemented by the host; neither
+ * construction nor planning renders it. Model metadata is interpreted by the
+ * host and adds no execution model to this package.
+ *
+ * Invocation IDs are caller-selected or opt-in deterministic IDs derived
+ * from the flow tag and idempotency key.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make: {
+  <
+    const Tag extends string,
+    Payload extends Schema.Struct.Fields | AnyStructSchema,
+    Success extends Schema.Top = Schema.Void,
+    Error extends Schema.Top = Schema.Never,
+    Requires = never
+  >(
+    tag: Tag,
+    options: MakeOptions<Payload, Success, Error> & {
+      readonly body: Body<Payload, Success, Error, Requires>
+      readonly prompt?: never
+    }
+  ): Flow<Tag, PayloadSchemaOf<Payload>, Success, Error, Requires>
+  <
+    const Tag extends string,
+    Payload extends Schema.Struct.Fields | AnyStructSchema,
+    Success extends Schema.Top = Schema.Void,
+    Error extends Schema.Top = Schema.Never
+  >(
+    tag: Tag,
+    options: MakeOptions<Payload, Success, Error> & {
+      readonly prompt: (payload: PayloadSchemaOf<Payload>["Type"]) => string
+      readonly body?: never
+      readonly implementationVersion?: string | undefined
+    }
+  ): PromptFlow<Tag, PayloadSchemaOf<Payload>, Success, Error>
+} = <
+  const Tag extends string,
+  Payload extends Schema.Struct.Fields | AnyStructSchema,
+  Success extends Schema.Top = Schema.Void,
+  Error extends Schema.Top = Schema.Never,
+  Requires = never
+>(
+  tag: Tag,
+  options: MakeOptions<Payload, Success, Error> & {
+    readonly body?: Body<Payload, Success, Error, Requires> | undefined
+    readonly prompt?: ((payload: PayloadSchemaOf<Payload>["Type"]) => string) | undefined
+    readonly implementationVersion?: string | undefined
+  }
+): any => {
+  if (typeof tag !== "string" || tag.trim().length === 0) {
+    throw new TypeError("Flow.make: tag must be a non-empty string")
+  }
+  if (
+    (options.body === undefined && typeof options.prompt !== "function") ||
+    (options.prompt === undefined && typeof options.body !== "function") ||
+    (options.body !== undefined && options.prompt !== undefined)
+  ) {
+    throw new TypeError(`Flow.make: "${tag}" must declare exactly one function: body or prompt`)
+  }
+  // Invalid static configuration is a programmer error thrown at construction,
+  // the same contract as effect's own `ExecutionPlan.make` (which throws on
+  // `attempts <= 0`); `RangeError` matches effect's range-violation throws.
+  if (
+    options.maxRounds !== undefined &&
+    (!Number.isSafeInteger(options.maxRounds) || options.maxRounds < 1)
+  ) {
+    throw new RangeError(`Flow.make: "${tag}" maxRounds must be a positive safe integer`)
+  }
+  const deadline = options.deadline === undefined
+    ? undefined
+    : Option.getOrUndefined(Duration.fromInput(options.deadline))
+  if (
+    options.deadline !== undefined &&
+    (deadline === undefined || !Duration.isFinite(deadline) || Duration.toMillis(deadline) <= 0)
+  ) {
+    throw new RangeError(`Flow.make: "${tag}" deadline must be a positive finite duration`)
+  }
+  // Captured here, where the stack still names the author's file, and carried
+  // as a non-enumerable property so no digest can see it
+  // (`internal/DeclarationSite.ts`).
+  const site = options.declaredFrom === undefined
+    ? DeclarationSite.capture()
+    : DeclarationSite.declaredAt(options.declaredFrom)
+  const payloadSchema = (Schema.isSchema(options.payload)
+    ? options.payload
+    : Schema.Struct(options.payload as any)) as PayloadSchemaOf<Payload>
+  const successSchema = options.success ?? (Schema.Void as unknown as Success)
+  const errorSchema = options.error ?? (Schema.Never as unknown as Error)
+  const annotations = lowerDeclarations(options)
+  const action = options.prompt === undefined ? undefined : Action.make(`${tag}/prompt`, {
+    payload: payloadSchema,
+    success: successSchema,
+    error: errorSchema,
+    capabilities: options.capabilities,
+    effects: options.effects,
+    annotations,
+    tier: options.effects?.tier ?? "irreversible",
+    implementationVersion: options.implementationVersion,
+    declaredFrom: options.declaredFrom
+  }) as unknown as Declared<`${Tag}/prompt`, PayloadSchemaOf<Payload>, Success, Error>
+  // The adapter only describes one dispatch. Prompt rendering belongs to the
+  // host implementation and its reviewed source/implementation identity.
+  const body = action === undefined ? options.body : Node.capture(
+    { action: action.name, implementationVersion: action.implementationVersion ?? null },
+    (payload: PayloadSchemaOf<Payload>["Type"]) => action.call(payload as never)
+  )
+  return DeclarationSite.annotate(
+    makeProto<Tag, PayloadSchemaOf<Payload>, Success, Error, Requires>({
+      _tag: tag,
+      description: options.description,
+      payloadSchema,
+      successSchema,
+      errorSchema,
+      annotations,
+      model: options.model,
+      effort: options.effort,
+      system: options.system,
+      chat: options.chat,
+      flows: options.flows,
+      prompt: options.prompt,
+      action,
+      body: body as (
+        payload: PayloadSchemaOf<Payload>["Type"]
+      ) => Node.Node<BodySuccess<Success["Type"]>, Error["Type"], Requires>,
+      idempotencyKey: options.idempotencyKey as any,
+      suspendedRetryPolicy: options.suspendedRetryPolicy,
+      maxRounds: options.maxRounds,
+      deadline
+    }),
+    site
+  )
+}

package/src/FlowRuntime/CancelRequestFailed.ts

@@ -0,0 +1,56 @@
+/**
+ * Failure raised when a cancellation request could not be made durable.
+ *
+ * @since 0.1.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * Raised when `interrupt` could not durably record its cancellation request.
+ *
+ * This is a **typed failure**, never a defect, and never swallowed. A durable
+ * runtime records operator intent before it interrupts anything: the record is
+ * what tells the interruption handler that a cancellation happened rather than
+ * a shutdown (issue #26), what survives the requesting process dying, and what
+ * a parked or cross-process run is eventually cancelled by. A durable runtime
+ * records the run and all linked descendants in one transaction. A storage
+ * failure on any write leaves every request unchanged: the run is still
+ * running and still cancellable, so the caller sees this typed failure and can
+ * retry instead of receiving false success.
+ *
+ * A runtime that keeps no durable cancellation record — the in-memory engine —
+ * never raises it, so its `Effect<void>` remains assignable to the widened
+ * contract and no in-memory caller has to handle anything.
+ *
+ * The same error carries the durable engine's refusal of `interruptUnsafe`.
+ * That port promises forced cancellation without cleanup, and the durable
+ * engine has no such path — it has one cancellation path, `interrupt`, which
+ * is durable and cascades to linked children. Answering the unsafe request
+ * with the safe one silently reinterpreted it, so 1.0.0-rc.0 refuses it with
+ * code `unsafe_interrupt_unsupported`. It is the same failure type because it
+ * is the same question — "your cancellation request was not carried out" —
+ * and the code says which of the two reasons applies.
+ *
+ * The error is declared here because it is part of the `interrupt` contract
+ * this package owns; the durable implementation lives in
+ * `@smthrs/engine-store`'s `RunDriver`.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class CancelRequestFailed extends Schema.TaggedError<CancelRequestFailed>()(
+  "@smthrs/flow/CancelRequestFailed",
+  {
+    /**
+     * Stable public error code. `cancel_request_failed` is a storage failure
+     * on a supported request; `unsafe_interrupt_unsupported` is the durable
+     * engine refusing `interruptUnsafe`, which it does not implement.
+     */
+    code: Schema.Literals(["cancel_request_failed", "unsafe_interrupt_unsupported"]),
+    /** The execution whose cancellation could not be recorded. */
+    executionId: Schema.String,
+    /** The storage failure, rendered for an operator. */
+    reason: Schema.String
+  }
+) {}

package/src/FlowRuntime/ExecutionIdentityConflict.ts

@@ -0,0 +1,32 @@
+/** Execution identity refusals shared by authoring and engine layers.
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Fault from "../Fault.ts"
+
+/**
+ * A caller reused an execution id for different persisted run identity.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class ExecutionIdentityConflict extends Schema.TaggedError<ExecutionIdentityConflict>()(
+  "@smthrs/engine/ExecutionIdentityConflict",
+  {
+    code: Schema.Literal("execution_identity_conflict").pipe(
+      Schema.withConstructorDefault(Effect.succeed("execution_identity_conflict"))
+    ),
+    executionId: Schema.String,
+    field: Schema.Literals(["flow", "payload", "capabilities", "lineage", "round", "parent"]),
+    expected: Schema.String,
+    actual: Schema.String,
+    status: Schema.Literals(["pending", "running", "suspended", "completed", "failed", "cancelled", "unknown"]).pipe(
+      Schema.withConstructorDefault(Effect.succeed("unknown"))
+    ),
+    message: Schema.String
+  }
+) {}
+
+Fault.register("@smthrs/engine/ExecutionIdentityConflict", "bug")

package/src/FlowRuntime/FlowCycleDetected.ts

@@ -0,0 +1,41 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Failure raised when executing a flow would close a cycle in the persisted
+ * parent-execution chain.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Raised when executing a flow would close a cycle in the persisted
+ * parent-execution chain, which is a child asking to execute an execution id
+ * that already appears among its own ancestors.
+ *
+ * This is a **typed failure**, never a defect: the caller is expected to be
+ * able to recover from it (see `docs/troubleshooting.md`,
+ * "FlowRuntime.FlowCycleDetected"). Detection itself lives in
+ * `@smthrs/engine-store`'s `DurableEngineState.recordRunParent`, which
+ * inserts the durable parent edge and walks the parent chain in O(depth)
+ * inside one storage transaction, rolling back on a hit; the error is
+ * declared here because it is part of the `execute` contract this package
+ * owns.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class FlowCycleDetected extends Schema.TaggedError<FlowCycleDetected>()(
+  "@smthrs/flow/FlowCycleDetected",
+  {
+    /** Stable public error code. */
+    // This wire shape freezes at 1.0.0-rc.0.
+    code: Schema.Literal("flow_cycle_detected").pipe(
+      Schema.withConstructorDefault(Effect.succeed("flow_cycle_detected"))
+    ),
+    /** Ordered execution ids from the cycle's target back to itself. */
+    path: Schema.Array(Schema.String)
+  }
+) {}

package/src/FlowRuntime/FlowExecutionNotFound.ts

@@ -0,0 +1,46 @@
+/**
+ * Failure raised when `poll` addresses an execution the runtime has no record
+ * of.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Raised when `poll` is asked about an execution id the runtime never
+ * recorded.
+ *
+ * This is a **typed failure**, never a defect, and never folded into the
+ * success channel: `poll` answers `Option.none` for a known execution that has
+ * not settled yet, so answering it for an unknown id as well would leave the
+ * caller unable to distinguish "still running" from "no such execution". A
+ * caller holding a stored execution id needs that distinction — a run that is
+ * still in flight is waited on, one the runtime has no record of is a wiring
+ * or retention problem to surface.
+ *
+ * The error is declared here because it is part of the `poll` contract this
+ * package owns; every runtime — the in-memory engine and the durable
+ * `@smthrs/engine-store` driver alike — raises it for an unknown id.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class FlowExecutionNotFound extends Schema.TaggedError<FlowExecutionNotFound>()(
+  "@smthrs/flow/FlowExecutionNotFound",
+  {
+    /** Stable public error code. */
+    // This wire shape freezes at 1.0.0-rc.0.
+    code: Schema.Literal("execution_not_found").pipe(
+      Schema.withConstructorDefault(Effect.succeed("execution_not_found"))
+    ),
+    /** The execution id the runtime has no record of. */
+    executionId: Schema.String
+  }
+) {
+  /** @since 0.1.0 */
+  override get message(): string {
+    return `No flow execution is recorded under id "${this.executionId}"`
+  }
+}

package/src/FlowRuntime/FlowInstance.ts

@@ -0,0 +1,128 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * The per-execution state contract flow authoring APIs read and update.
+ *
+ * @since 0.1.0
+ */
+
+import type * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
+import type * as Latch from "effect/Latch"
+import type * as Scope from "effect/Scope"
+import type * as Flow from "../Flow/index.ts"
+import type { WaitingAnnotation } from "./WaitingAnnotation.ts"
+
+/**
+ * Service that contains flow runtime state for one execution.
+ *
+ * **When to use**
+ *
+ * Use to read or update flow execution, suspension, interruption,
+ * lifetime, failure, and action coordination state inside flow authoring
+ * combinators and runtime implementations.
+ *
+ * **Details**
+ *
+ * The service stores the execution ID, flow definition, long-lived scope,
+ * suspension and interruption flags, the stored failure cause, and action
+ * coordination state for a single flow run. `@smthrs/flow` declares the
+ * contract; a runtime — `@smthrs/engine` — constructs the value.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class FlowInstance extends Context.Service<
+  FlowInstance,
+  {
+    /**
+     * The flow execution ID.
+     */
+    readonly executionId: string
+
+    /**
+     * The journal lineage this execution's records address themselves to.
+     *
+     * `docs/concepts/the-runtime-port.md` makes a frame the journal position
+     * `(lineageId, seq)`, and `docs/guides/run-a-child-flow.md` defines the
+     * lineage id as the run id followed by the node-id path from the run root.
+     * A runtime mints it; every durable record this execution writes carries it
+     * as `meta.lineageId`, which is what lets `TimeTravel.inspect` fold an
+     * ordinary engine journal at all.
+     */
+    readonly lineageId: string
+
+    /**
+     * The flow definition.
+     */
+    readonly flow: Flow.Any
+
+    /**
+     * A scope that represents the lifetime of the flow.
+     *
+     * It is only closed when the flow is completed.
+     */
+    readonly scope: Scope.Closeable
+
+    /**
+     * Whether the flow has requested to be suspended.
+     */
+    suspended: boolean
+
+    /**
+     * Whether the flow has requested to be interrupted.
+     */
+    interrupted: boolean
+
+    /**
+     * The waiting classification the flow declared for its next suspension
+     * via `annotateWaiting`. Durable drivers read it when parking the
+     * run so approval and quota waits (and their wake token) are
+     * representable; when absent the driver derives `timer`/`event` from
+     * durable state.
+     */
+    waiting: WaitingAnnotation | undefined
+
+    /**
+     * The next-round invocation this round settled with, when its body's root
+     * value was a `to` rather than a `done`.
+     *
+     * A handoff is a settlement, not a failure and not a suspension, so it
+     * cannot travel out through the effect's exit; `Flow.intoResult` reads the
+     * slot and answers `Flow.Handoff` instead of `Flow.Complete`. The engine
+     * then opens the next round under the same lineage
+     * (`docs/concepts/trampoline-rounds.md`).
+     */
+    handoff: Flow.Handoff | undefined
+
+    /**
+     * The lineage deadline this round inherited from the round that handed
+     * off to it, when its lineage is bounded. `Deadline.bound` runs the round
+     * under it instead of starting a deadline of its own.
+     */
+    readonly lineageDeadline?: Flow.LineageDeadline | undefined
+
+    /**
+     * When SuspendOnFailure is triggered, the cause of the failure is stored
+     * here.
+     */
+    cause: Cause.Cause<never> | undefined
+
+    readonly actionState: {
+      count: number
+      readonly latch: Latch.Latch
+      readonly nextOrdinal: (scope: string) => number
+      readonly snapshots: Map<string, unknown>
+      /**
+       * Allocation scopes with a keyless dispatch currently in flight
+       * (issue #111). Indistinguishable invocations of one declaration are
+       * allocation-ordered, so two in flight at once would take their
+       * ordinals from the fiber schedule and a replay could swap their
+       * recorded outcomes undetected; the engine refuses the second dispatch
+       * instead. Distinct interpreter graph sites refine the scope and do not
+       * contend here.
+       */
+      readonly keylessInFlight: Set<string>
+    }
+  }
+>()("@smthrs/flow/FlowRuntime/FlowInstance") {}