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

package/package.json

@@ -1,6 +1,330 @@
 {
   "name": "@smthrs/flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.4",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine"
+  },
+  "description": "The flow authoring model: flows, actions, durable waits, retry policy, and the runtime port they execute against",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/flow"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "flow",
+    "durability"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "flow",
+    "durability"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./Action": {
+      "import": {
+        "types": "./dist/esm/Action/index.d.ts",
+        "default": "./dist/esm/Action/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Action/index.d.ts",
+        "default": "./dist/cjs/Action/index.js"
+      }
+    },
+    "./Action/*": null,
+    "./CacheEnvironment": {
+      "import": {
+        "types": "./dist/esm/Action/CacheEnvironment.d.ts",
+        "default": "./dist/esm/Action/CacheEnvironment.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Action/CacheEnvironment.d.ts",
+        "default": "./dist/cjs/Action/CacheEnvironment.js"
+      }
+    },
+    "./FileBoundary": {
+      "import": {
+        "types": "./dist/esm/Action/FileBoundary.d.ts",
+        "default": "./dist/esm/Action/FileBoundary.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Action/FileBoundary.d.ts",
+        "default": "./dist/cjs/Action/FileBoundary.js"
+      }
+    },
+    "./FileInput": {
+      "import": {
+        "types": "./dist/esm/Action/FileInput.d.ts",
+        "default": "./dist/esm/Action/FileInput.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Action/FileInput.d.ts",
+        "default": "./dist/cjs/Action/FileInput.js"
+      }
+    },
+    "./Flow": {
+      "import": {
+        "types": "./dist/esm/Flow/index.d.ts",
+        "default": "./dist/esm/Flow/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Flow/index.d.ts",
+        "default": "./dist/cjs/Flow/index.js"
+      }
+    },
+    "./Flow/*": null,
+    "./FlowRuntime": {
+      "import": {
+        "types": "./dist/esm/FlowRuntime/index.d.ts",
+        "default": "./dist/esm/FlowRuntime/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/FlowRuntime/index.d.ts",
+        "default": "./dist/cjs/FlowRuntime/index.js"
+      }
+    },
+    "./FlowRuntime/*": null,
+    "./StepIdentity": {
+      "import": {
+        "types": "./dist/esm/Action/StepIdentity.d.ts",
+        "default": "./dist/esm/Action/StepIdentity.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Action/StepIdentity.d.ts",
+        "default": "./dist/cjs/Action/StepIdentity.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./Deadline": {
+      "import": {
+        "types": "./dist/esm/Deadline.d.ts",
+        "default": "./dist/esm/Deadline.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Deadline.d.ts",
+        "default": "./dist/cjs/Deadline.js"
+      }
+    },
+    "./DurableClock": {
+      "import": {
+        "types": "./dist/esm/DurableClock.d.ts",
+        "default": "./dist/esm/DurableClock.js"
+      },
+      "require": {
+        "types": "./dist/cjs/DurableClock.d.ts",
+        "default": "./dist/cjs/DurableClock.js"
+      }
+    },
+    "./DurableDeferred": {
+      "import": {
+        "types": "./dist/esm/DurableDeferred.d.ts",
+        "default": "./dist/esm/DurableDeferred.js"
+      },
+      "require": {
+        "types": "./dist/cjs/DurableDeferred.d.ts",
+        "default": "./dist/cjs/DurableDeferred.js"
+      }
+    },
+    "./DurableQueue": {
+      "import": {
+        "types": "./dist/esm/DurableQueue.d.ts",
+        "default": "./dist/esm/DurableQueue.js"
+      },
+      "require": {
+        "types": "./dist/cjs/DurableQueue.d.ts",
+        "default": "./dist/cjs/DurableQueue.js"
+      }
+    },
+    "./ExternalJob": {
+      "import": {
+        "types": "./dist/esm/ExternalJob.d.ts",
+        "default": "./dist/esm/ExternalJob.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ExternalJob.d.ts",
+        "default": "./dist/cjs/ExternalJob.js"
+      }
+    },
+    "./Fault": {
+      "import": {
+        "types": "./dist/esm/Fault.d.ts",
+        "default": "./dist/esm/Fault.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Fault.d.ts",
+        "default": "./dist/cjs/Fault.js"
+      }
+    },
+    "./Graph": {
+      "import": {
+        "types": "./dist/esm/Graph.d.ts",
+        "default": "./dist/esm/Graph.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Graph.d.ts",
+        "default": "./dist/cjs/Graph.js"
+      }
+    },
+    "./HumanTask": {
+      "import": {
+        "types": "./dist/esm/HumanTask.d.ts",
+        "default": "./dist/esm/HumanTask.js"
+      },
+      "require": {
+        "types": "./dist/cjs/HumanTask.d.ts",
+        "default": "./dist/cjs/HumanTask.js"
+      }
+    },
+    "./Interpreter": {
+      "import": {
+        "types": "./dist/esm/Interpreter.d.ts",
+        "default": "./dist/esm/Interpreter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Interpreter.d.ts",
+        "default": "./dist/cjs/Interpreter.js"
+      }
+    },
+    "./Poll": {
+      "import": {
+        "types": "./dist/esm/Poll.d.ts",
+        "default": "./dist/esm/Poll.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Poll.d.ts",
+        "default": "./dist/cjs/Poll.js"
+      }
+    },
+    "./RetryPolicy": {
+      "import": {
+        "types": "./dist/esm/RetryPolicy.d.ts",
+        "default": "./dist/esm/RetryPolicy.js"
+      },
+      "require": {
+        "types": "./dist/cjs/RetryPolicy.d.ts",
+        "default": "./dist/cjs/RetryPolicy.js"
+      }
+    },
+    "./Sleep": {
+      "import": {
+        "types": "./dist/esm/Sleep.d.ts",
+        "default": "./dist/esm/Sleep.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Sleep.d.ts",
+        "default": "./dist/cjs/Sleep.js"
+      }
+    },
+    "./Stall": {
+      "import": {
+        "types": "./dist/esm/Stall.d.ts",
+        "default": "./dist/esm/Stall.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Stall.d.ts",
+        "default": "./dist/cjs/Stall.js"
+      }
+    },
+    "./WaitFor": {
+      "import": {
+        "types": "./dist/esm/WaitFor.d.ts",
+        "default": "./dist/esm/WaitFor.js"
+      },
+      "require": {
+        "types": "./dist/cjs/WaitFor.d.ts",
+        "default": "./dist/cjs/WaitFor.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/crypto": "1.0.0-rc.4",
+    "@smthrs/keys": "1.0.0-rc.4",
+    "@smthrs/plan": "1.0.0-rc.4",
+    "@smthrs/canonical": "1.0.0-rc.4",
+    "@smthrs/capability": "1.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage --coverage.reportsDirectory=coverage"
+  }
 }

package/src/Action/Action.ts

@@ -0,0 +1,333 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * Defines the schemas and interfaces of a durable action.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effects from "@smthrs/plan/Effects"
+import type * as Node from "@smthrs/plan/Node"
+import type * as Planned from "@smthrs/plan/Planned"
+import type * as Context from "effect/Context"
+import type * as Crypto from "effect/Crypto"
+import type * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type { Scope } from "effect/Scope"
+import type { AnyStructSchema } from "../Flow/Flow.ts"
+import type { FlowInstance, FlowRuntime } from "../FlowRuntime/index.ts"
+import type * as RetryPolicy from "../RetryPolicy.ts"
+import type { FileBoundary } from "./FileBoundary.ts"
+import type { Implementation } from "./Implementations.ts"
+import type { TypeId } from "./TypeId.ts"
+
+/**
+ * The durability and retry semantics of an action.
+ *
+ * The schema is `@smthrs/plan`'s `Effects.Tier`: an action's durability, a
+ * declared envelope's ceiling and `KeyMaterial.kind` are the same three words,
+ * and they are declared once.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Tier = Effects.Tier
+
+/**
+ * The durability and retry semantics of an action.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Tier = Effects.Tier
+
+/**
+ * Schema for caller-declared sealed action identity.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const IdempotencyKey = Schema.Union([
+  Schema.String,
+  Schema.Record(Schema.String, Schema.Json)
+])
+
+/**
+ * Caller-declared sealed action identity.
+ *
+ * A string is namespaced by the action declaration. A JSON object is
+ * caller-owned and remains stable across action renames. Runtime
+ * environment and filesystem facts are always added by the engine. An explicit
+ * implementation version is also separate engine key material; a caller-owned
+ * object cannot mask it with a field of the same name.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type IdempotencyKey = typeof IdempotencyKey.Type
+
+/**
+ * Recursively permits planned references wherever a declared action payload
+ * accepts a concrete value.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type PlannedPayload<T> =
+  | Planned.Planned<T>
+  | ([T] extends [ReadonlyArray<infer Value>] ? ReadonlyArray<PlannedPayload<Value>>
+    : [T] extends [object] ? { readonly [Key in keyof T]: PlannedPayload<T[Key]> }
+    : T)
+
+/**
+ * The requirement one declared action mints for itself, identified by its
+ * tag.
+ *
+ * A declaration is data that travels everywhere and carries no code, so a body
+ * that calls it names an implementation it does not hold. This type is that
+ * "does not hold", stated to the compiler: `Charge.call(...)` produces a node
+ * requiring `Requirement<"payments/Charge">`, `Charge.toLayer(...)` produces a
+ * layer providing it, and `Flow.execute` is where the two have to meet. It is
+ * phantom — nothing reads it, and nothing about planning, keying, or replay
+ * changes with it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Requirement<Tag extends string> {
+  readonly _: unique symbol
+  readonly _tag: Tag
+}
+
+/**
+ * A named action declaration whose implementation is supplied separately
+ * through a layer and whose calls only add nodes to a plan.
+ *
+ * `Requires` is what `.call()` puts in the requirement channel of the node it
+ * records. It is this action's own {@link Requirement} for an ordinary
+ * declaration, and `never` for a system declaration the engine itself
+ * implements ({@link module:make.makeSystem}).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Declared<
+  Tag extends string,
+  Payload extends AnyStructSchema,
+  Success extends Schema.Top,
+  Error extends Schema.Top,
+  Requires = Requirement<Tag>
+> {
+  readonly [TypeId]: typeof TypeId
+  readonly name: Tag
+  /**
+   * Semantic implementation identity. Changing it requires a newly planned
+   * execution; it is not an in-place upgrade of a persisted run. Canonical
+   * composition requires it for sealed actions with an idempotency key.
+   * Invocation-scoped actions may omit it; low-level keyed legacy callers
+   * retain their old handler-reuse contract when it is absent.
+   */
+  readonly implementationVersion: string | undefined
+  readonly payloadSchema: Payload
+  readonly successSchema: Success
+  readonly errorSchema: Error
+  readonly tier: Tier
+  readonly idempotencyKey: IdempotencyKey | ((payload: Payload["Type"]) => IdempotencyKey) | undefined
+  /** Allows multiple legitimate sealed results to race under one cache key. */
+  readonly nondeterministic: true | undefined
+  /** Durable retry policy applied to every implementation invocation. */
+  readonly retryPolicy: RetryPolicy.RetryPolicy | undefined
+  /** Milliseconds one attempt may run before it fails with `AttemptTimedOut`. */
+  readonly attemptTimeoutMs: number | undefined
+  /** Milliseconds one attempt may go without `Action.heartbeat` before it fails. */
+  readonly heartbeatTimeoutMs: number | undefined
+  /** Filesystem declaration, optionally derived from the decoded payload. */
+  readonly fileBoundary: FileBoundary | ((payload: Payload["Type"]) => FileBoundary) | undefined
+  readonly annotations: Context.Context<never>
+  /**
+   * The context key this declaration's implementation is provided under, and
+   * the identity behind {@link Requirement}.
+   *
+   * `toLayer` provides it; a composition that would rather hand the runtime an
+   * implementation directly can provide it itself with `Layer.succeed`. Its
+   * string key is derived from the action tag, so two declarations of one tag
+   * name one slot.
+   */
+  readonly requirement: Context.Service<Requirement<Tag>, Implementation>
+  annotate<I, S>(key: Context.Key<I, S>, value: S): Declared<Tag, Payload, Success, Error, Requires>
+  annotateMerge<I>(annotations: Context.Context<I>): Declared<Tag, Payload, Success, Error, Requires>
+  readonly call: (
+    payload: PlannedPayload<Payload["~type.make.in"]>
+  ) => Node.Node<Success["Type"], Error["Type"], Requires>
+  /**
+   * Attaches the implementation and yields the layer that provides this
+   * declaration's {@link Requirement}. A versioned declaration requires the
+   * same `implementationVersion` here; a mismatch throws
+   * `ImplementationVersionMismatch` before registration. The version must cover
+   * handler semantics and semantic service/configuration changes, not merely a
+   * package publication label. Source text is never inferred as that identity.
+   *
+   * Let inference name the returned layer's requirements. The requirement
+   * channel is what a composition trusts: a layer type that under-declares it
+   * still typechecks at `Effect.provide` and dies at runtime as a missing
+   * service. A concrete hand annotation cannot lie — dropping a service from
+   * it is a compile error — but a GENERIC one can: when the annotated
+   * requirement union keeps a deferred member such as
+   * `Output["DecodingServices"]` (constrained only as `unknown` through
+   * `Schema.Top`), TypeScript lets that member absorb every concrete service
+   * the annotation dropped, and the drop compiles. A wrapper that must
+   * annotate — a public interface naming its layer's type, say — therefore
+   * pins the set at a concrete instantiation, where the check works again:
+   *
+   * ```ts
+   * // Wrapped.layer is the wrapper's hand-annotated toLayer result, held
+   * // here with every schema argument concrete.
+   * type Needed = Layer.Services<typeof Wrapped.layer>
+   * expectTypeOf<Meter extends Needed ? true : false>().toEqualTypeOf<true>()
+   * ```
+   */
+  readonly toLayer: <R>(
+    execute: (payload: Payload["Type"]) => Effect.Effect<Success["Type"], Error["Type"], R>,
+    options?: {
+      readonly override?: boolean
+      /** Must exactly match the declaration, including absence on legacy declarations. */
+      readonly implementationVersion?: string | undefined
+    }
+  ) => Layer.Layer<
+    Requires,
+    never,
+    | FlowRuntime
+    | Exclude<R, FlowRuntime | FlowInstance | Scope>
+    | Payload["DecodingServices"]
+    | Payload["EncodingServices"]
+    | Success["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["DecodingServices"]
+    | Error["EncodingServices"]
+  >
+}
+
+/**
+ * Durable flow action that behaves as an `Effect` and records its name,
+ * result schemas, annotations, and encoded execution form for the flow
+ * engine.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Action<
+  Success extends Schema.Constraint = Schema.Void,
+  Error extends Schema.Constraint = Schema.Never,
+  R = never
+> extends
+  Effect.Effect<
+    Success["Type"],
+    Error["Type"],
+    | Success["DecodingServices"]
+    | Error["DecodingServices"]
+    | R
+    | Crypto.Crypto
+    | FlowRuntime
+    | FlowInstance
+  >
+{
+  readonly [TypeId]: typeof TypeId
+  readonly name: string
+  readonly implementationVersion?: string | undefined
+  readonly successSchema: Success
+  readonly errorSchema: Error
+  readonly exitSchema: Schema.Exit<Success, Error, Schema.Defect>
+  readonly exitSchemaPartial: Schema.Exit<Success, Error, Schema.Unknown>
+  readonly annotations: Context.Context<never>
+  readonly tier: Tier
+  readonly idempotencyKey: IdempotencyKey | undefined
+  /** Allows multiple legitimate sealed results to race under one cache key. */
+  readonly nondeterministic: true | undefined
+  readonly metadata: unknown
+  /** Typed filesystem boundary used by the durable engine. */
+  readonly fileBoundary: FileBoundary | undefined
+  readonly retryPolicy: RetryPolicy.RetryPolicy | undefined
+  /** Milliseconds one attempt may run before it fails with `AttemptTimedOut`. */
+  readonly attemptTimeoutMs: number | undefined
+  /** Milliseconds one attempt may go without `Action.heartbeat` before it fails. */
+  readonly heartbeatTimeoutMs: number | undefined
+  annotate<I, S>(
+    key: Context.Key<I, S>,
+    value: S
+  ): Action<Success, Error, R>
+  annotateMerge<I>(
+    annotations: Context.Context<I>
+  ): Action<Success, Error, R>
+  readonly execute: Effect.Effect<
+    Success["Type"],
+    Error["Type"],
+    | Success["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["DecodingServices"]
+    | Error["EncodingServices"]
+    | R
+    | Crypto.Crypto
+    | Scope
+    | FlowRuntime
+    | FlowInstance
+  >
+  readonly executeEncoded: Effect.Effect<
+    unknown,
+    unknown,
+    | Success["DecodingServices"]
+    | Success["EncodingServices"]
+    | Error["DecodingServices"]
+    | Error["EncodingServices"]
+    | R
+    | Crypto.Crypto
+    | Scope
+    | FlowRuntime
+    | FlowInstance
+  >
+}
+
+/**
+ * Type-erased action shape for APIs that only need the action identity,
+ * name, annotations, and encoded execution.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Any {
+  readonly [TypeId]: typeof TypeId
+  readonly name: string
+  readonly implementationVersion?: string | undefined
+  readonly executeEncoded: Effect.Effect<any, any, any>
+  readonly annotations: Context.Context<never>
+  readonly tier: Tier
+  readonly idempotencyKey: IdempotencyKey | undefined
+  readonly nondeterministic: true | undefined
+  readonly metadata: unknown
+  /** Typed filesystem boundary used by the durable engine. */
+  readonly fileBoundary: FileBoundary | undefined
+  readonly retryPolicy: RetryPolicy.RetryPolicy | undefined
+}
+
+/**
+ * Type-erased action shape that also exposes success and error schemas for
+ * derived flow APIs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AnyWithProps {
+  readonly [TypeId]: typeof TypeId
+  readonly name: string
+  readonly implementationVersion?: string | undefined
+  readonly successSchema: Schema.Top
+  readonly errorSchema: Schema.Top
+  readonly executeEncoded: Effect.Effect<any, any, any>
+  readonly tier: Tier
+  readonly idempotencyKey: IdempotencyKey | undefined
+  readonly nondeterministic: true | undefined
+  readonly metadata: unknown
+  /** Typed filesystem boundary used by the durable engine. */
+  readonly fileBoundary: FileBoundary | undefined
+  readonly retryPolicy: RetryPolicy.RetryPolicy | undefined
+}