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

package/dist/cjs/HumanTask.d.ts

@@ -0,0 +1,442 @@
+/**
+ * Asking a person something, as an ordinary declared action.
+ *
+ * {@link module:WaitFor.action} is the general rendezvous: it parks until
+ * something outside the run resolves it, and settles with whatever arrived.
+ * That is the right primitive and the wrong affordance for a human, because a
+ * human answers in prose, in a hurry, and sometimes wrongly. Smithers 0.x had
+ * the affordance — a `HumanTask` with a kind, a prompt, an output schema, an
+ * attempt budget, and a deadline — and this module is that affordance rebuilt
+ * on the primitives this package already has.
+ *
+ * Four things are added to a bare wait:
+ *
+ * - a **kind**, so the four shapes a person is asked for (`ask`, `confirm`,
+ *   `select`, `json`) are stated rather than reconstructed from a schema;
+ * - **validation**, so an answer that does not fit is refused where it arrives
+ *   instead of failing three steps later as a decode error;
+ * - **re-asking**, so a refused answer parks again on a NEW wait point rather
+ *   than ending the run, until the attempt budget is spent;
+ * - a **deadline**, so a question nobody answers settles instead of parking
+ *   forever.
+ *
+ * All four are built from what is already durable. Each attempt is its own wait
+ * point in {@link module:WaitFor}'s namespace — `WaitFor/<name>#<attempt>` — so
+ * an answer is recorded exactly as any other durable deferred completion is, a
+ * refused answer stays recorded under the attempt that refused it, and a
+ * re-driven round replays every answer it already has before parking on the
+ * first attempt that has none. The reason an answer was refused is recorded
+ * too, as a sealed step named `HumanTask/<name>#<attempt>/rejected`, so the
+ * judgment the run made sits in the journal beside the answer it judged rather
+ * than in a log stream nobody replays. The park is declared through the ordinary
+ * waiting vocabulary under `approval`, carrying the current attempt's token, so
+ * whoever collects answers always sees the one wait point that is open. The
+ * deadline is a {@link module:DurableClock} armed once per task and raced
+ * against every attempt, which makes it a deadline for the QUESTION rather than
+ * for one attempt at answering it.
+ *
+ * @since 0.1.0
+ */
+import * as Node from "@smthrs/plan/Node";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.ts";
+import * as DurableDeferred from "./DurableDeferred.ts";
+import { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts";
+/**
+ * The shape a person is asked for.
+ *
+ * `ask` wants prose, `confirm` wants yes or no, `select` wants one of the
+ * options the task names, and `json` wants a value the task's JSON Schema
+ * accepts. The kind is what an interface renders and what {@link validate}
+ * checks; it is stated rather than inferred, because a text box and a two-
+ * button confirmation are different questions even when both answers happen to
+ * be strings.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Kind = "ask" | "confirm" | "select" | "json";
+/**
+ * The schema the `kind` payload field is declared with.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Kind: Schema.Literals<readonly ["ask", "confirm", "select", "json"]>;
+declare const HumanTaskFailed_base: Schema.Class<HumanTaskFailed, Schema.TaggedStruct<"@smthrs/flow/HumanTaskFailed", {
+    readonly code: Schema.Literals<readonly ["request_invalid", "rejected", "timeout"]>;
+    readonly task: Schema.String;
+    readonly attempts: Schema.Number;
+    readonly rejections: Schema.$Array<Schema.String>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A question that ended without an answer the task could accept.
+ *
+ * `request_invalid` is the author's mistake — a `select` with no options, an
+ * attempt budget below one, a deadline that is not a length of time, a JSON
+ * Schema outside the supported subset — and is refused before anyone is asked
+ * anything. `rejected` means every attempt was
+ * spent on answers the task refused, and `timeout` means the deadline passed
+ * with the question still open. All three are typed failures rather than
+ * defects, so a body recovers from them with `Node.catch` like any other
+ * declared failure — which is the point, because "the reviewer never answered"
+ * is an ordinary outcome of asking a reviewer.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class HumanTaskFailed extends HumanTaskFailed_base {
+}
+declare const HumanAnswerInvalid_base: Schema.Class<HumanAnswerInvalid, Schema.TaggedStruct<"@smthrs/flow/HumanAnswerInvalid", {
+    readonly code: Schema.withConstructorDefault<Schema.Literals<readonly ["answer_invalid", "answer_not_open"]>>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An answer refused before it could consume durable storage.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class HumanAnswerInvalid extends HumanAnswerInvalid_base {
+}
+/**
+ * The tag the human-task declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const tag = "system/human-task";
+/**
+ * The attempt budget a task that names none is asked under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const defaultMaxAttempts = 10;
+/**
+ * The deepest supported JSON Schema path, counting the root as depth zero.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxSchemaDepth = 32;
+/**
+ * The most schema objects one human-task request may contain.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxSchemaNodes = 512;
+/**
+ * The most JSON values embedded across schema keywords such as `enum`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxSchemaValueNodes = 10000;
+/**
+ * The deepest JSON value embedded in a schema, including enum members.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxSchemaValueDepth = 64;
+/**
+ * The most JSON values one answer validation may visit.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxAnswerNodes = 10000;
+/**
+ * The largest encoded JSON answer that can enter the durable store.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxAnswerBytes: number;
+/**
+ * The largest encoded JSON Schema carried by one question.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxSchemaBytes: number;
+/**
+ * The deepest admitted answer tree.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxAnswerDepth = 64;
+/**
+ * The largest encoded string value admitted in a request or answer.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxJsonStringBytes: number;
+/**
+ * The largest encoded object key admitted in a request or answer.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxJsonKeyBytes: number;
+/**
+ * The most members admitted in one JSON array or object.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxJsonMembers = 10000;
+/**
+ * The largest encoded task name.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxTaskNameBytes = 1024;
+/**
+ * The largest encoded prompt.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxPromptBytes: number;
+/**
+ * The largest option list on one select question.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxOptions = 256;
+/**
+ * The largest encoded select option.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const maxOptionBytes: number;
+/**
+ * The largest attempt budget one human task may declare.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxAttemptBudget = 1000;
+/**
+ * The most caller-supplied characters retained in one rendered diagnostic.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxDiagnosticChars = 512;
+/**
+ * The most characters retained across a terminal failure's rejection list.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const maxRetainedRejectionChars = 8192;
+/**
+ * The durable deferred one attempt at answering resolves through.
+ *
+ * Attempts are separate wait points on purpose. A durable deferred records the
+ * FIRST completion and replays it forever, so re-asking on the same wait point
+ * would read the refused answer again on every round; a new point per attempt
+ * makes "answer again" expressible without a second completion mechanism, and
+ * leaves the refused answers in place as the record of what was asked and what
+ * came back.
+ *
+ * The name lives in {@link module:WaitFor}'s namespace because an answer is
+ * completed through exactly the {@link module:WaitFor} path: a token, and
+ * `DurableDeferred.succeed`. {@link answer} is that call with the token parsed
+ * for you.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const deferred: (name: string, attempt: number) => DurableDeferred.DurableDeferred<typeof Schema.Json>;
+/**
+ * What {@link validate} checks an answer against.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Request {
+    readonly kind: Kind;
+    /** Ignored for `json`: an option list alone constrains no JSON value. */
+    readonly options?: ReadonlyArray<string> | undefined;
+    readonly schema?: unknown;
+}
+/**
+ * Checks that a JSON Schema stays inside the bounded subset, at every depth.
+ *
+ * This is a different question from {@link validate}, which asks whether an
+ * ANSWER fits a schema. A question is worth refusing before anyone is asked it:
+ * a constraint the subset cannot enforce would otherwise be silently dropped,
+ * and the person would be told their answer was fine when half of what was
+ * asked for went unchecked.
+ *
+ * The subset is `type` (`object`, `array`, `string`, `number`, `integer`,
+ * `boolean`, `null`), `enum`, `properties`, `required`, `items`, and
+ * `nullable`; it lives in `internal/JsonSchemaSubset`.
+ *
+ * Returns the first reason the schema is out of bounds, or `undefined` when the
+ * whole tree is inside it.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const validateSchema: (schema: unknown, path?: ReadonlyArray<string>) => string | undefined;
+/**
+ * Checks one answer against the question that was asked.
+ *
+ * Returns the reason the answer was refused, or `undefined` when it fits. It is
+ * exported because it is the same check an interface should run BEFORE it
+ * records an answer: refusing a typo in the text box the person is looking at
+ * is worth more than refusing it one durable round later.
+ *
+ * ```ts
+ * const rejection = HumanTask.validate(value, { kind: "select", options })
+ * if (rejection !== undefined) return showTheReviewer(rejection)
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const validate: (value: unknown, request: Request) => string | undefined;
+declare const payloadFields: {
+    name: Schema.String;
+    kind: Schema.Literals<readonly ["ask", "confirm", "select", "json"]>;
+    prompt: Schema.String;
+    options: Schema.optional<Schema.$Array<Schema.String>>;
+    schema: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    timeoutMs: Schema.optional<Schema.Number>;
+    maxAttempts: Schema.optional<Schema.Number>;
+};
+/**
+ * The declared human-task action.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever the next step depends on a person: a release that
+ * needs sign-off, a plan that needs a choice, a field the run cannot compute.
+ * The node settles with the answer, so downstream steps read it the way they
+ * read any other step result, and {@link decode} gives that answer the caller's
+ * own type.
+ *
+ * ```ts
+ * HumanTask.action.call({
+ *   name: "release",
+ *   kind: "select",
+ *   prompt: "Which build should ship?",
+ *   options: ["canary", "stable"],
+ *   timeoutMs: 6 * 60 * 60 * 1000
+ * })
+ * ```
+ *
+ * `name` addresses the question, so two calls naming one question in one
+ * execution await one answer — the same reading {@link module:WaitFor} takes,
+ * for the same reason: a person has to be able to name what they are answering.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const action: Action.Declared<typeof tag, Schema.Struct<typeof payloadFields>, typeof Schema.Json, typeof HumanTaskFailed, never>;
+/**
+ * The human-task implementation: park, validate, re-ask, settle.
+ *
+ * Provide it beside the other action implementation layers a body calls, over
+ * the {@link module:Implementations.layerImplementations} table they file
+ * themselves in:
+ *
+ * ```ts
+ * Layer.mergeAll(HumanTask.layer, Interpreter.layer(Release)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime>;
+/**
+ * Records one answer to a human task.
+ *
+ * `token` is the value the run parked with — the `token` of the waiting
+ * annotation, which is the wait point the current attempt is open on. The
+ * runtime checks that exact approval wait and records the completion as one
+ * mutation, so guessed, unopened, or stale attempt tokens cannot pre-answer a
+ * run. An admitted answer then resumes the run through the ordinary durable
+ * deferred path.
+ *
+ * The token is not a credential: anyone who knows or derives the address of
+ * the open attempt can answer it. The host decides who may answer, and must
+ * authorize the caller before calling `answer`.
+ *
+ * ```ts
+ * if (waiting.token !== null) {
+ *   yield* HumanTask.answer({ token: waiting.token, value: { decision: "ship" } })
+ * }
+ * ```
+ *
+ * The durable JSON boundary is validated here: the value must be inert,
+ * detached, and within the exported depth, node, member, string, key, and byte
+ * limits. Whether that JSON fits the question is the task's own judgment, made
+ * where its kind and schema are known; a semantically refused answer stays
+ * recorded so the record shows what was actually said. Call {@link validate}
+ * first when the interface can refuse it while the person is still looking at
+ * it.
+ *
+ * The TOKEN is checked. This entry point completes an arbitrary caller-supplied
+ * address under `Schema.Json`, so it accepts only a token whose deferred name
+ * {@link deferred} could have written. A token for a `DurableQueue` item, a
+ * plain {@link module:WaitFor} gate, or an unrelated flow's deferred fails with
+ * `TokenInvalid` carrying `deferred_mismatch` rather than writing a JSON exit
+ * into a row another schema will decode.
+ *
+ * A syntactically valid HumanTask token can still fail with
+ * `HumanAnswerInvalid` carrying `answer_not_open` when the addressed run is not
+ * currently parked on that exact approval token.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const answer: (options: {
+    readonly token: string;
+    readonly value: typeof Schema.Json.Type;
+}) => Effect.Effect<void, DurableDeferred.TokenInvalid | HumanAnswerInvalid, FlowRuntime>;
+/**
+ * Gives an answer the caller's own type.
+ *
+ * The action's success schema is `Schema.Json`, because what a person may
+ * answer is described by the task's payload rather than by a TypeScript type.
+ * `decode` is the other half: the author states the schema they were really
+ * asking for, and the node downstream of the question carries that type.
+ *
+ * ```ts
+ * const Decision = Schema.Struct({ decision: Schema.Literals(["ship", "hold"]) })
+ *
+ * HumanTask.action.call({ name: "release", kind: "json", prompt, schema }).pipe(
+ *   HumanTask.decode(Decision)
+ * )
+ * ```
+ *
+ * The two descriptions must agree. The answer already passed the task's own
+ * JSON Schema before it reached here, so a value this schema rejects means the
+ * payload's schema and the author's schema describe different answers — an
+ * authoring mistake, not a human one — and it surfaces as a defect naming the
+ * offending path rather than as a failure a body could sensibly catch.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const decode: <S extends Schema.ConstraintDecoder<unknown>>(schema: S) => <E, R>(self: Node.Node<typeof Schema.Json.Type, E, R>) => Node.Node<S["Type"], E, R>;
+export {};
+//# sourceMappingURL=HumanTask.d.ts.map

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

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