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

package/src/Flow/Outcome.ts

@@ -0,0 +1,179 @@
+/**
+ * Serializable values with which one flow round can settle.
+ *
+ * Engine handoff semantics are intentionally separate. These values contain
+ * only the completed value, the next flow invocation, or the durable waiting
+ * classification described by `docs/concepts/trampoline-rounds.md`.
+ *
+ * @since 0.1.0
+ */
+
+import type { CapabilityPattern } from "@smthrs/capability/Capability"
+import * as Node from "@smthrs/plan/Node"
+import * as Schema from "effect/Schema"
+import { WaitingAnnotation } from "../FlowRuntime/WaitingAnnotation.ts"
+import { OutcomeNodeTypeId, OutcomeValueTypeId } from "../internal/OutcomeMarker.ts"
+
+const outcomeNode = <A extends Outcome>(value: A): Node.Node<Node.Succeed<A>> => {
+  const node = Node.succeed(value)
+  Object.defineProperty(node.ast, OutcomeNodeTypeId, {
+    configurable: false,
+    enumerable: false,
+    value: value._tag,
+    writable: false
+  })
+  return node
+}
+
+/**
+ * A completed trampoline lineage value.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Done<A> {
+  readonly _tag: "Done"
+  /**
+   * The completed value in its author-facing form. The engine encodes it with
+   * the settling flow's success schema at the settlement boundary; callers do
+   * not pre-encode values passed to {@link done}.
+   */
+  readonly value: A
+}
+
+/**
+ * A serializable invocation of the next flow round.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface To<Payload> {
+  readonly _tag: "To"
+  readonly flow: string
+  readonly capabilityCeilings?: ReadonlyArray<ReadonlyArray<CapabilityPattern>>
+  /**
+   * The next round's payload in its author-facing form. The engine encodes it
+   * with the target flow's payload schema at settlement, before persisting the
+   * handoff; callers do not pre-encode values passed to `Flow.to`.
+   */
+  readonly payload: Payload
+}
+
+/**
+ * A request to durably park the current flow round.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Park {
+  readonly _tag: "Park"
+  readonly reason: WaitingAnnotation
+}
+
+/**
+ * The three pure-data settlements a trampoline round can produce.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Outcome<A = unknown, Payload = unknown> = Done<A> | To<Payload> | Park
+
+/**
+ * Schema for completed trampoline lineage values.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Done = Schema.Struct({
+  _tag: Schema.tag("Done"),
+  value: Schema.Unknown
+})
+
+/**
+ * Schema for next-round flow invocations.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const To = Schema.Struct({
+  _tag: Schema.tag("To"),
+  flow: Schema.String,
+  payload: Schema.Unknown
+})
+
+/**
+ * Schema for durable trampoline parking requests.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Park = Schema.Struct({
+  _tag: Schema.tag("Park"),
+  reason: WaitingAnnotation
+})
+
+/**
+ * Schema for every pure-data trampoline settlement.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Outcome = Schema.Union([Done, To, Park])
+
+/**
+ * Constructs a completed trampoline lineage value using Node.succeed's JSON
+ * projection. Pass a planned reference to retain an upstream domain value.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const done = <A>(value: A): Node.Node<Node.Succeed<Done<A>>> => outcomeNode<Done<A>>({ _tag: "Done", value })
+
+/**
+ * Constructs a durable parking request using the runtime waiting vocabulary.
+ *
+ * The two forms describe the same wait. The record is the whole waiting
+ * vocabulary, and is what a park with a deadline needs; the positional form is
+ * the common case — a reason and the token a wake handler matches against —
+ * written the way an author says it out loud, `Flow.park("approval", requestId)`.
+ * A positional call with no token omits the field rather than parking under an
+ * empty one.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const park: {
+  (reason: WaitingAnnotation): Node.Node<Park>
+  (reason: string, token?: string | undefined): Node.Node<Park>
+} = (reason: WaitingAnnotation | string, token?: string | undefined): Node.Node<Park> =>
+  outcomeNode({
+    _tag: "Park",
+    reason: typeof reason !== "string"
+      ? reason
+      : token === undefined
+      ? { reason }
+      : { reason, token }
+  })
+
+/**
+ * Whether a settled body value is one of the three trampoline settlements.
+ *
+ * A body's root node may settle with anything its author wrote; only these
+ * three values authored through {@link done}, a flow's `to` method, or
+ * {@link park} ask the engine for a settlement other than "this value is the
+ * answer". Shape alone is deliberately insufficient: ordinary success data
+ * may legally contain the same `_tag` fields. Graph construction carries a
+ * non-enumerable marker from the explicit authoring node to its hydrated
+ * value, and encoded outcome records remain plain data until decoded by the
+ * runtime surface that owns them.
+ *
+ * @category refinements
+ * @since 0.1.0
+ */
+export const isOutcome = (value: unknown): value is Outcome => {
+  if (typeof value !== "object" || value === null) return false
+  const marker = Object.getOwnPropertyDescriptor(value, OutcomeValueTypeId)
+  if (marker === undefined || !("value" in marker)) return false
+  const tag = Object.getOwnPropertyDescriptor(value, "_tag")
+  return tag !== undefined && "value" in tag && marker.value === tag.value && Schema.is(Outcome)(value)
+}

package/src/Flow/Result.ts

@@ -0,0 +1,284 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Serializable completion and suspension states returned by flow executions.
+ *
+ * @since 0.1.0
+ */
+
+import { CapabilityPattern } from "@smthrs/capability/Capability"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import type * as Exit from "effect/Exit"
+import * as Schema from "effect/Schema"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as SchemaParser from "effect/SchemaParser"
+import * as Transformation from "effect/SchemaTransformation"
+import type { ExitEncoded } from "effect/unstable/rpc/RpcMessage"
+
+const ResultTypeId = "@smthrs/flow/Flow/Result"
+
+/**
+ * Returns `true` when a value is a flow `Result`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const isResult = <A = unknown, E = unknown>(
+  u: unknown
+): u is Result<A, E> => {
+  if (u !== Object(u)) return false
+  const marker = Object.getOwnPropertyDescriptor(u, ResultTypeId)
+  if (marker === undefined || !("value" in marker) || marker.value !== ResultTypeId) return false
+  const tag = Object.getOwnPropertyDescriptor(u, "_tag")
+  return tag !== undefined && "value" in tag &&
+    (tag.value === "Complete" || tag.value === "Suspended" || tag.value === "Handoff")
+}
+
+/**
+ * Result of a flow execution: a completed exit, a suspended flow state, or a
+ * handoff to the next round of a trampoline lineage.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export type Result<A, E> = Complete<A, E> | Suspended | Handoff
+
+/**
+ * Encoded representation of a flow `Result`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export type ResultEncoded<A, E> =
+  | CompleteEncoded<A, E>
+  | typeof Suspended.Encoded
+  | typeof Handoff.Encoded
+
+/**
+ * Encoded representation of a completed flow result containing an encoded
+ * `Exit`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export interface CompleteEncoded<A, E> {
+  readonly _tag: "Complete"
+  readonly exit: ExitEncoded<A, E>
+}
+
+/**
+ * Schema constructor for `Complete` flow results using the supplied
+ * success and error schemas.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export interface CompleteSchema<
+  Success extends Schema.Constraint,
+  Error extends Schema.Constraint
+> extends
+  Schema.declareConstructor<
+    Complete<Success["Type"], Error["Type"]>,
+    Complete<Success["Encoded"], Error["Encoded"]>,
+    readonly [Schema.Exit<Success, Error, Schema.Defect>]
+  >
+{
+  readonly success: Success
+  readonly error: Error
+}
+
+/**
+ * Represents a completed flow execution with its success or failure `Exit`.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Complete<A, E> extends Data.TaggedClass("Complete")<{
+  readonly exit: Exit.Exit<A, E>
+}> {
+  /**
+   * Marks this value as a flow result for runtime guards.
+   *
+   * @since 0.1.0
+   */
+  readonly [ResultTypeId] = ResultTypeId
+
+  /**
+   * Builds the schema for completed flow results from success and error schemas.
+   *
+   * @since 0.1.0
+   */
+  static Schema<Success extends Schema.Constraint, Error extends Schema.Constraint>(options: {
+    readonly success: Success
+    readonly error: Error
+  }): CompleteSchema<Success, Error> {
+    // The declaration stays inline because it closes over this constructor's schemas.
+    const schema = Schema.declareConstructor<
+      Complete<Success["Type"], Error["Type"]>,
+      Complete<Success["Encoded"], Error["Encoded"]>
+    >()(
+      [Schema.Exit(options.success, options.error, Schema.Defect())],
+      ([exit]) => (input, ast, options) => {
+        if (!(isResult(input) && input._tag === "Complete")) {
+          return Effect.fail(new SchemaIssue.InvalidType(ast, input, options))
+        }
+        return Effect.mapBothEager(
+          SchemaParser.decodeEffect(exit)(input.exit, options),
+          {
+            onSuccess: (exit) => new Complete({ exit }),
+            onFailure: (issue) =>
+              new SchemaIssue.Composite(
+                ast,
+                [
+                  new SchemaIssue.Pointer(["exit"], issue)
+                ],
+                input,
+                options
+              )
+          }
+        )
+      },
+      {
+        expected: "Flow.Complete",
+        toCodecJson: ([exit]) =>
+          Schema.link<Complete<Success["Encoded"], Error["Encoded"]>>()(
+            Schema.Struct({
+              _tag: Schema.tag("Complete"),
+              exit
+            }),
+            Transformation.transform({
+              decode: (encoded) => new Complete({ exit: encoded.exit }),
+              encode: (result) => (({
+                _tag: "Complete",
+                exit: result.exit
+              }) as const)
+            })
+          )
+      }
+    )
+    return Schema.make(schema.ast, {
+      success: options.success,
+      error: options.error
+    })
+  }
+}
+
+/**
+ * Represents a suspended flow execution, optionally carrying the cause that
+ * triggered suspension.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Suspended extends Schema.Class<Suspended>(
+  "@smthrs/flow/Flow/Suspended"
+)({
+  _tag: Schema.tag("Suspended"),
+  cause: Schema.optional(Schema.Cause(Schema.Never, Schema.Defect()))
+}) {
+  /**
+   * Marks this value as a flow result for runtime guards.
+   *
+   * @since 0.1.0
+   */
+  readonly [ResultTypeId] = ResultTypeId
+}
+
+/**
+ * The deadline a trampoline lineage's rounds share: the journaled first start
+ * of its originating round and the bound in milliseconds, so every round
+ * expires at `startedAtMs + deadlineMs`.
+ *
+ * @category results
+ * @since 1.0.0
+ */
+export const LineageDeadline = Schema.Struct({
+  startedAtMs: Schema.Number,
+  deadlineMs: Schema.Number
+})
+
+/**
+ * The deadline a trampoline lineage's rounds share.
+ *
+ * @category results
+ * @since 1.0.0
+ */
+export type LineageDeadline = typeof LineageDeadline.Type
+
+/**
+ * Represents a flow round that ended by handing off to the next round of its
+ * trampoline lineage.
+ *
+ * A round settles this way when its body's root value is a `to` invocation
+ * (`docs/concepts/trampoline-rounds.md`): the round produced no answer of
+ * its own, it produced the NEXT flow to run. `flow` is the target's tag, so the
+ * value survives the journal and the run row unchanged.
+ *
+ * DECIDED: `payload` is the target's payload in
+ * ENCODED form. The target's `to` method accepts its ordinary constructor
+ * shape so authoring stays aligned with `call` and `execute`; the body
+ * interpreter resolves planned references and encodes the invocation through
+ * the target declaration before constructing `Handoff`. The receiving round
+ * decodes those bytes through the same schema.
+ *
+ * It is a third settlement rather than a `Complete` carrying a magic value
+ * because the engine has to tell "this run answered" from "this run continues
+ * elsewhere" without decoding against a success schema the handoff never
+ * satisfies.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export class Handoff extends Schema.Class<Handoff>(
+  "@smthrs/flow/Flow/Handoff"
+)({
+  _tag: Schema.tag("Handoff"),
+  flow: Schema.NonEmptyString,
+  capabilityCeilings: Schema.optionalKey(Schema.Array(Schema.Array(CapabilityPattern))),
+  payload: Schema.Unknown,
+  /**
+   * The lineage deadline the next round runs under, stamped by the round
+   * that handed off when its lineage is bounded (`Deadline.bound`).
+   */
+  deadline: Schema.optionalKey(LineageDeadline)
+}) {
+  /**
+   * Marks this value as a flow result for runtime guards.
+   *
+   * @since 0.1.0
+   */
+  readonly [ResultTypeId] = ResultTypeId
+}
+
+/**
+ * Creates a schema for flow results using the supplied success and error
+ * schemas.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const Result = <
+  Success extends Schema.Constraint,
+  Error extends Schema.Constraint
+>(options: {
+  readonly success: Success
+  readonly error: Error
+}) => Schema.Union([Complete.Schema(options), Suspended, Handoff])
+
+const AnyOrVoid = Schema.Union([Schema.Any, Schema.Void])
+
+/**
+ * Schema for encoded flow results with generic success and error payloads.
+ *
+ * @category results
+ * @since 0.1.0
+ */
+export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEncoded(
+  Schema.toCodecJson(
+    Result({
+      success: AnyOrVoid,
+      error: AnyOrVoid
+    })
+  )
+) as any