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

package/dist/esm/Action/Action.d.ts

@@ -0,0 +1,250 @@
+/**
+ * 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 declare const Tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+/**
+ * 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 declare const IdempotencyKey: Schema.Union<readonly [Schema.String, Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+/**
+ * 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;
+}
+//# sourceMappingURL=Action.d.ts.map

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

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

package/dist/esm/Action/Action.js

@@ -0,0 +1,30 @@
+// 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 * as Schema from "effect/Schema";
+/**
+ * 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;
+/**
+ * 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)
+]);
+//# sourceMappingURL=Action.js.map

package/dist/esm/Action/Action.js.map

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

package/dist/esm/Action/AttemptTimedOut.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defines the defect an action attempt settles with when it outlives its
+ * declared `attemptTimeoutMs` or misses its `heartbeatTimeoutMs`.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+declare const AttemptTimedOut_base: Schema.Class<AttemptTimedOut, Schema.TaggedStruct<"@smthrs/flow/AttemptTimedOut", {
+    readonly code: Schema.withConstructorDefault<Schema.Literal<"attempt_timed_out">>;
+    readonly actionName: Schema.String;
+    readonly attempt: Schema.Number;
+    /** Which bound expired: the whole attempt, or the gap between heartbeats. */
+    readonly bound: Schema.Literals<readonly ["attempt", "heartbeat"]>;
+    readonly timeoutMs: Schema.Number;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * One attempt of an action ran past a declared time bound and was
+ * interrupted.
+ *
+ * It is a defect rather than a typed failure because the bound belongs to the
+ * dispatch, not to the action's declared error channel. The engine's retry
+ * decision point still counts it as a retryable attempt failure under the
+ * action's `retryPolicy`, and a policy can refuse it by listing this tag in
+ * `nonRetryable`.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class AttemptTimedOut extends AttemptTimedOut_base {
+}
+export {};
+//# sourceMappingURL=AttemptTimedOut.d.ts.map

package/dist/esm/Action/AttemptTimedOut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttemptTimedOut.d.ts","sourceRoot":"","sources":["../../../src/Action/AttemptTimedOut.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;IAuBnC,6EAA6E;;;;;AArBjF;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,oBAapC;CAAG"}

package/dist/esm/Action/AttemptTimedOut.js

@@ -0,0 +1,32 @@
+/**
+ * Defines the defect an action attempt settles with when it outlives its
+ * declared `attemptTimeoutMs` or misses its `heartbeatTimeoutMs`.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * One attempt of an action ran past a declared time bound and was
+ * interrupted.
+ *
+ * It is a defect rather than a typed failure because the bound belongs to the
+ * dispatch, not to the action's declared error channel. The engine's retry
+ * decision point still counts it as a retryable attempt failure under the
+ * action's `retryPolicy`, and a policy can refuse it by listing this tag in
+ * `nonRetryable`.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class AttemptTimedOut extends Schema.TaggedError()("@smthrs/flow/AttemptTimedOut", {
+    code: Schema.Literal("attempt_timed_out").pipe(Schema.withConstructorDefault(Effect.succeed("attempt_timed_out"))),
+    actionName: Schema.String,
+    attempt: Schema.Number,
+    /** Which bound expired: the whole attempt, or the gap between heartbeats. */
+    bound: Schema.Literals(["attempt", "heartbeat"]),
+    timeoutMs: Schema.Number,
+    message: Schema.String
+}) {
+}
+//# sourceMappingURL=AttemptTimedOut.js.map

package/dist/esm/Action/AttemptTimedOut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttemptTimedOut.js","sourceRoot":"","sources":["../../../src/Action/AttemptTimedOut.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM,CAAC,WAAW,EAAmB,CACxE,8BAA8B,EAC9B;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAC5C,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CACnE;IACD,UAAU,EAAE,MAAM,CAAC,MAAM;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CACF;CAAG","sourcesContent":["/**\n * Defines the defect an action attempt settles with when it outlives its\n * declared `attemptTimeoutMs` or misses its `heartbeatTimeoutMs`.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * One attempt of an action ran past a declared time bound and was\n * interrupted.\n *\n * It is a defect rather than a typed failure because the bound belongs to the\n * dispatch, not to the action's declared error channel. The engine's retry\n * decision point still counts it as a retryable attempt failure under the\n * action's `retryPolicy`, and a policy can refuse it by listing this tag in\n * `nonRetryable`.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class AttemptTimedOut extends Schema.TaggedError<AttemptTimedOut>()(\n  \"@smthrs/flow/AttemptTimedOut\",\n  {\n    code: Schema.Literal(\"attempt_timed_out\").pipe(\n      Schema.withConstructorDefault(Effect.succeed(\"attempt_timed_out\"))\n    ),\n    actionName: Schema.String,\n    attempt: Schema.Number,\n    /** Which bound expired: the whole attempt, or the gap between heartbeats. */\n    bound: Schema.Literals([\"attempt\", \"heartbeat\"]),\n    timeoutMs: Schema.Number,\n    message: Schema.String\n  }\n) {}\n"]}

package/dist/esm/Action/BoundaryMode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Defines filesystem boundary enforcement modes.
+ *
+ * The schema itself is `@smthrs/plan`'s `FileSet.BoundaryMode`, because the
+ * same two words are what a plan node's `effects.boundaryMode` carries. This
+ * module is the name an action reaches for; there is one declaration behind
+ * both.
+ *
+ * @since 0.1.0
+ */
+import * as FileSet from "@smthrs/plan/FileSet";
+/**
+ * Schema for how strictly an action's filesystem boundary is enforced.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const BoundaryMode: import("effect/Schema").Literals<readonly ["hard", "expected"]>;
+/**
+ * How strictly an action's filesystem boundary is enforced.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type BoundaryMode = FileSet.BoundaryMode;
+//# sourceMappingURL=BoundaryMode.d.ts.map

package/dist/esm/Action/BoundaryMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundaryMode.d.ts","sourceRoot":"","sources":["../../../src/Action/BoundaryMode.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,iEAAuB,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAA"}

package/dist/esm/Action/BoundaryMode.js

@@ -0,0 +1,23 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+/**
+ * Defines filesystem boundary enforcement modes.
+ *
+ * The schema itself is `@smthrs/plan`'s `FileSet.BoundaryMode`, because the
+ * same two words are what a plan node's `effects.boundaryMode` carries. This
+ * module is the name an action reaches for; there is one declaration behind
+ * both.
+ *
+ * @since 0.1.0
+ */
+import * as FileSet from "@smthrs/plan/FileSet";
+/**
+ * Schema for how strictly an action's filesystem boundary is enforced.
+ *
+ * `hard` rejects undeclared access. `expected` records access for validation
+ * after execution without requiring the sandbox to reject it immediately.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const BoundaryMode = FileSet.BoundaryMode;
+//# sourceMappingURL=BoundaryMode.js.map

package/dist/esm/Action/BoundaryMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundaryMode.js","sourceRoot":"","sources":["../../../src/Action/BoundaryMode.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;;;;;;GASG;AAEH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAA","sourcesContent":["// Deep reviewed and polished by a human on 2026-08-10.\n\n/**\n * Defines filesystem boundary enforcement modes.\n *\n * The schema itself is `@smthrs/plan`'s `FileSet.BoundaryMode`, because the\n * same two words are what a plan node's `effects.boundaryMode` carries. This\n * module is the name an action reaches for; there is one declaration behind\n * both.\n *\n * @since 0.1.0\n */\n\nimport * as FileSet from \"@smthrs/plan/FileSet\"\n\n/**\n * Schema for how strictly an action's filesystem boundary is enforced.\n *\n * `hard` rejects undeclared access. `expected` records access for validation\n * after execution without requiring the sandbox to reject it immediately.\n *\n * @category models\n * @since 0.1.0\n */\nexport const BoundaryMode = FileSet.BoundaryMode\n\n/**\n * How strictly an action's filesystem boundary is enforced.\n *\n * @category models\n * @since 0.1.0\n */\nexport type BoundaryMode = FileSet.BoundaryMode\n"]}

package/dist/esm/Action/CacheEnvironment.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The environment description folded into every cross-run cache key.
+ *
+ * A cached result is only reusable on a host that would have produced the same
+ * bytes, so the key has to name the environment as well as the inputs — the
+ * platform, the toolchain, and the capability groups in force. Bazel's action
+ * key does the same thing for the same reason.
+ *
+ * It is a *complete* value on purpose: an environment a composition cannot
+ * fully describe is one whose cache hits cannot be justified, and the engine
+ * executes rather than guessing at the missing part.
+ *
+ * @since 0.1.0
+ */
+import * as PlanCachePolicy from "@smthrs/plan/CachePolicy";
+import * as Schema from "effect/Schema";
+/**
+ * Complete runtime environment included in every cross-run cache key.
+ *
+ * If a composition cannot provide this complete value, the engine executes
+ * normally but does not derive a cross-run cache key.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CacheEnvironment = typeof CacheEnvironment.Type;
+/**
+ * Schema for the complete runtime environment included in cache keys.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const CacheEnvironment: Schema.Struct<{
+    /** Ordered semantic runtime layers, including versions and configuration. */
+    readonly layers: Schema.$Array<Schema.NonEmptyString>;
+    /** Complete effective capability groups. */
+    readonly capabilities: Schema.$Record<Schema.String, Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * How far a recorded sealed result may travel.
+ *
+ * `shared` is the content-addressed default: the key names the inputs and the
+ * environment, so any run on any host that would have produced the same bytes
+ * may reuse the row. `run` and `flow` narrow that on purpose — a step whose
+ * result is only meaningful inside one execution, or inside one flow, folds
+ * that identity into its key so a sibling never reads it.
+ *
+ * This is `@smthrs/plan`'s `CachePolicy.CacheScope`, the one scope vocabulary
+ * `@smthrs/patterns` also declares its policy with.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const CacheScope: Schema.Literals<readonly ["run", "flow", "shared"]>;
+/**
+ * How far a recorded sealed result may travel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CacheScope = PlanCachePolicy.CacheScope;
+/**
+ * The caller's declaration about the decay and the reach of a sealed action's
+ * recorded result.
+ *
+ * `ttlMs` bounds the age of a row the engine may serve: past it the dispatch
+ * executes again and journals `cache-expired`, so the refusal is durable
+ * evidence a replay reads rather than a fresh clock reading. `scope` decides
+ * what the key names besides the inputs.
+ *
+ * This is `@smthrs/plan`'s `CachePolicy.CachePolicy`, the one policy schema.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const CachePolicy: Schema.Struct<{
+    readonly ttlMs: Schema.optionalKey<Schema.Int>;
+    readonly scope: Schema.optionalKey<Schema.Literals<readonly ["run", "flow", "shared"]>>;
+}>;
+/**
+ * The caller's declaration about the decay and the reach of a sealed action's
+ * recorded result.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CachePolicy = PlanCachePolicy.CachePolicy;
+/**
+ * Annotation key carrying a declaration's {@link CachePolicy}.
+ *
+ * It is an annotation, not a field on the action, for the same reason
+ * placement and effects are: the policy is data that travels with the
+ * declaration and is read by whoever executes it, and adding it changes no
+ * existing call site.
+ *
+ * It is `@smthrs/plan`'s `CachePolicy.CachePolicyAnnotation` itself, the same
+ * object `@smthrs/patterns` annotates a flow with, identified by
+ * `"@smthrs/flow/Action/CachePolicy"`.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const CachePolicyAnnotation: import("effect/Context").Service<{
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}, {
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}>;
+/**
+ * Reads the cache policy an annotation bag carries, or `undefined` when it
+ * carries none.
+ *
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const cachePolicyOf: (annotations: import("effect/Context").Context<never>) => PlanCachePolicy.CachePolicy | undefined;
+/**
+ * Declares a cache policy on an action.
+ *
+ * This is the form the engine honors today: `@smthrs/engine-store` reads
+ * {@link CachePolicyAnnotation} off the dispatched action, bounds the age of
+ * the row it may serve by `ttlMs`, and narrows the address that row is stored
+ * under from `scope`. `@smthrs/patterns`' `WithCache` declares the same policy
+ * over a `@smthrs/core` flow under the same annotation key, for the
+ * declaration surface, so a policy written by either is read by the engine.
+ *
+ * The action is not mutated. `annotate` returns a new declaration carrying the
+ * policy, which is what a plan captures.
+ *
+ * It is `@smthrs/plan`'s `CachePolicy.annotate` under this package's name for
+ * it.
+ *
+ * @example
+ * ```ts
+ * import { Action } from "@smthrs/flow"
+ * import * as CacheEnvironment from "@smthrs/flow/CacheEnvironment"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ *
+ * const compile = CacheEnvironment.withCache(
+ *   Action.make({
+ *     name: "build/compile",
+ *     success: Schema.String,
+ *     tier: "sealed",
+ *     execute: Effect.succeed("dist/server.js")
+ *   }),
+ *   { ttlMs: 60_000, scope: "shared" }
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const withCache: <A extends {
+    annotate: (key: typeof PlanCachePolicy.CachePolicyAnnotation, value: PlanCachePolicy.CachePolicy) => A;
+}>(declaration: A, policy: PlanCachePolicy.CachePolicy) => A;
+//# sourceMappingURL=CacheEnvironment.d.ts.map

package/dist/esm/Action/CacheEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheEnvironment.d.ts","sourceRoot":"","sources":["../../../src/Action/CacheEnvironment.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,eAAe,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAcvC;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B,6EAA6E;;IAE7E,4CAA4C;;EAE5C,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,qDAA6B,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,CAAA;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;EAA8B,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB;;;;;;EAAwC,CAAA;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,mGAAgC,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,SAAS;;4DAA2B,CAAA"}