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

package/dist/cjs/Interpreter.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The body interpreter: what a flow does when it runs.
+ *
+ * A `Flow` has no handler to register — its `body` IS the behavior, per
+ * `docs/concepts/flows-and-actions.md` — so something has to turn
+ * the graph that body describes into execution. That is this
+ * module. {@link layer} registers a flow with the runtime, and the
+ * handler it installs builds the graph with {@link module:Graph.build} and
+ * walks it: each node settles once, in dependency order, and the root's value
+ * is the flow's result.
+ *
+ * What each variant does is the run-time half of what the AST recorded. An
+ * `ActionCall` runs its declaration's implementation — looked up by tag in
+ * {@link module:Implementations.Implementations} before the walk starts — as
+ * the ordinary durable action `toLayer` built, so a node driven here takes
+ * the same attempt journal, retry policy, and tier as the same action called
+ * from a handler. Its invocation identity additionally folds this node's
+ * structural address, keeping concurrent graph sites replay-stable. A `Map`
+ * applies its deferred function to the real upstream value. A `Branch`
+ * evaluates its digested predicate on the real
+ * subject and settles ONLY the arm it took: the other arm is topology the plan
+ * shows and the run skipped, and it is reported as such rather than silently
+ * absent. An `All` joins its members by name, a `Succeed` yields its value, and
+ * an inline `FlowCall` was already flattened by graph building, so it settles
+ * with the body spliced beneath it. A `FlowCall` the author wrote as
+ * `.child(payload)` is the one node that is NOT flattened: it opens a real child
+ * execution under a deterministically derived id
+ * ({@link childExecutionId}), which is what gives it its own journal lineage and
+ * makes the parent's interruption and the child's suspension travel between
+ * them.
+ *
+ * Planned references are resolved the way the plan names them: a payload
+ * placeholder carries the `Ref` `{from, path}` its key material recorded, so
+ * `result.files` reads `files` off the settled value of the node that produced
+ * it.
+ *
+ * The walk is demand-driven from the root rather than a sweep over the node
+ * list, because dependency order puts BOTH branch arms before the branch that
+ * chooses between them, and executing an arm to discover it was not taken is
+ * exactly what static topology exists to avoid.
+ *
+ * @since 0.1.0
+ */
+import * as Cause from "effect/Cause";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { Implementations } from "./Action/Implementations.ts";
+import type { AnyStructSchema, Flow } from "./Flow/Flow.ts";
+import { FlowInstance } from "./FlowRuntime/FlowInstance.ts";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+import * as Graph from "./Graph.ts";
+declare const InterpreterError_base: Schema.Class<InterpreterError, Schema.TaggedStruct<"@smthrs/flow/InterpreterError", {
+    readonly code: Schema.Literals<readonly ["incomplete_graph", "duplicate_node_id", "unresolved_action", "implementation_version_mismatch", "missing_implementation_version", "unresolved_reference", "unsupported_call", "missing_operation", "node_record_too_large", "plan_changed", "join_mismatch"]>;
+    readonly flow: Schema.String;
+    readonly node: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * A graph the interpreter will not drive.
+ *
+ * Every code names something the run cannot recover from on its own: a graph
+ * whose topology is incomplete, an action with no implementation wired up, a
+ * call the interpreter does not execute, and a deferred function that did not
+ * survive serialization beside its AST. `missing_implementation_version`
+ * names a content-reusable action that lacks the canonical version contract;
+ * `implementation_version_mismatch` names a declaration and registry that
+ * disagree. Both are preflight failures, before action dispatch.
+ * `join_mismatch` names a race, any, or quorum whose journaled decision this
+ * plan's members can no longer reproduce. `plan_changed` refuses a durable
+ * resume whose rebuilt graph differs from its first recorded plan.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class InterpreterError extends InterpreterError_base {
+}
+/**
+ * What one interpretation produced: the root's value, every node that settled
+ * with the value it settled with, and the nodes the run never reached because
+ * a branch went the other way.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Interpretation {
+    readonly value: unknown;
+    readonly settled: ReadonlyMap<string, unknown>;
+    /** Typed failures observed before a catch recovered them. */
+    readonly failed: ReadonlyMap<string, unknown>;
+    readonly skipped: ReadonlyArray<string>;
+}
+/**
+ * The services a driven node needs: the runtime that executes an action, and
+ * the execution it is part of.
+ *
+ * @private
+ */
+type Services = Crypto.Crypto | FlowRuntime | FlowInstance | Implementations;
+/**
+ * The execution id a `.child()` boundary runs its child under.
+ *
+ * DECIDED: the id is DERIVED from the parent
+ * execution and the child node's structural address, not minted. That is what
+ * makes a boundary at-most-once under replay, exactly as
+ * `docs/concepts/trampoline-rounds.md` requires of a round handoff: a
+ * parent that is re-driven re-derives the same id, so the engine lands on the
+ * child execution that already exists instead of starting a second copy of it.
+ * The canonical tuple includes the callee and a canonical payload digest, so
+ * delimiter splicing and a changed invocation cannot alias an earlier child.
+ * SHA-256 uses the same injected derivation services as the repository's
+ * other durable identities. The versioned key prefix is dropped because the
+ * child-id wire format is the bare digest. `digest` owns the
+ * prefix knowledge, so this package never guesses at a stored-key format.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const childExecutionId: (parentExecutionId: string, nodeId: string, calleeTag: string, payload: unknown) => Effect.Effect<string, never, Crypto.Crypto>;
+/**
+ * The largest encoded page of a recorded plan.
+ *
+ * A journal entry has a byte bound and a projection clips an oversized one, so
+ * a graph is PAGED rather than truncated: whatever does not fit in the plan
+ * record follows as appended subgraph pages. The budget is deliberately well
+ * under the 16 KiB gateway limit on graph events. The runtime measures the
+ * encoded journal envelope; absent that hook, the complete node record is
+ * measured in UTF-8. A node too large for one page is a typed preflight refusal.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const maximumPageBytes = 12000;
+/**
+ * How many distinct step key digests one node's settlement names.
+ *
+ * A journal entry has a byte bound and a digest is 64 characters, so the list
+ * is capped rather than left to grow with whatever a node dispatched. The
+ * cap is far above what any node reaches today — an action node drives one
+ * dispatch and keeps one step key however many times it is retried — and a
+ * node past it names the dispatches it started with rather than none.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const maximumDispatchDigests = 16;
+/**
+ * Interprets a flow body, or a bare node, against real values.
+ *
+ * The graph is built first and in full — planning is a pure function of the
+ * declarations and the payload, so the whole shape of the round is known before
+ * the first action runs — and then driven. The low-level default permits
+ * process-local callbacks; pass `callbackIdentity: "stable"` for reproducible
+ * callback identity. {@link layerWithImplementations} selects that policy by
+ * default.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const interpret: (flowOrNode: Parameters<typeof Graph.build>[0], payload?: unknown, options?: Graph.BuildOptions) => Effect.Effect<Interpretation, unknown, Services>;
+/**
+ * Registers a flow with the runtime, driven by its body.
+ *
+ * This is the only way a flow's behavior reaches the runtime, and the reason a
+ * flow has no `toLayer`: a flow has one behavior and it is the body, so there
+ * is no second, opaque one to attach. An Action is what carries an
+ * implementation, and it attaches that implementation with its own `toLayer`.
+ * Compose this beside the action implementation layers the body calls, over the
+ * {@link module:Implementations.layerImplementations} table they file
+ * themselves in — the table goes UNDER them, because filing happens while an
+ * implementation layer is built:
+ *
+ * ```ts
+ * Layer.mergeAll(Read.toLayer(read), Write.toLayer(write), Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * It accepts a flow whatever its requirement channel says, and requires only
+ * the table. Registering a body is not running one: the handler installed here
+ * resolves each call by tag when the run reaches it, which is the same thing a
+ * driver does for a plan read back out of a journal. `Flow.execute` is where
+ * the requirements are asked for.
+ *
+ * This low-level registration keeps the `process-local` callback policy for
+ * compatibility. Select `callbackIdentity: "stable"`, or use
+ * {@link layerWithImplementations}, to refuse unstable callbacks before
+ * dispatch. Without that selection it makes no reproducible-plan guarantee.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: <Tag extends string, Payload extends AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top>(flow: Flow<Tag, Payload, Success, Error, any>, options?: Graph.BuildOptions) => Layer.Layer<never, never, FlowRuntime | Implementations | Exclude<Payload["DecodingServices"], never> | Exclude<Payload["EncodingServices"], never> | Exclude<Success["DecodingServices"], never> | Exclude<Success["EncodingServices"], never> | Exclude<Error["DecodingServices"], never> | Exclude<Error["EncodingServices"], never>>;
+/**
+ * Composes one flow and its implementation layers around one isolated registry.
+ *
+ * The implementation layer must provide every action requirement carried by the
+ * flow. Callback identity defaults to `stable`: raw callbacks are refused before
+ * dispatch, with a diagnostic naming the callback and `Node.capture`. Captures
+ * must cover semantic configuration and implementation versions, including
+ * behavior reached through imports. Explicit `callbackIdentity: "process-local"`
+ * is available for local experimentation, without a reproducible-plan claim.
+ * Sealed actions with an idempotency key must declare `implementationVersion`
+ * and register that exact version. This rule is independent of callback policy:
+ * those declarations can reuse recorded content even if their code changes.
+ * Keyless sealed actions use invocation identity; compensable and irreversible
+ * actions do not use content-key caching. Their versions remain optional.
+ * Versions must cover semantic handler and service changes; callback stability
+ * cannot establish that declaration's completeness.
+ *
+ * The interpreter validates all named graph actions before dispatching any
+ * of them. Conflicting registrations fail while the layer builds; use an explicit
+ * `toLayer(handler, { override: true })` only for intentional scoped substitution.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWithImplementations: <Tag extends string, Payload extends AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, Requires, Provided, E, R>(flow: Flow<Tag, Payload, Success, Error, Requires>, implementations: Layer.Layer<Provided, E, R> & ([NoInfer<Requires>] extends [Provided] ? unknown : {
+    readonly missingActionImplementations: Exclude<Requires, Provided>;
+}), options?: Graph.BuildOptions) => Layer.Layer<Provided, E, FlowRuntime | Exclude<R, Implementations> | Exclude<Exclude<Payload["DecodingServices"], never>, Implementations> | Exclude<Exclude<Payload["EncodingServices"], never>, Implementations> | Exclude<Exclude<Success["DecodingServices"], never>, Implementations> | Exclude<Exclude<Success["EncodingServices"], never>, Implementations> | Exclude<Exclude<Error["DecodingServices"], never>, Implementations> | Exclude<Exclude<Error["EncodingServices"], never>, Implementations>>;
+export {};
+//# sourceMappingURL=Interpreter.d.ts.map

package/dist/cjs/Interpreter.d.ts.map

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