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

package/src/WaitFor.ts

@@ -0,0 +1,228 @@
+/**
+ * The system wait point, as an ordinary declared action.
+ *
+ * `docs/concepts/flows-and-actions.md` names wait-for-event the
+ * other half of the timer gap and says how to close it: ship it over the
+ * existing `DurableDeferred`, so an external signal is a visible, keyed plan
+ * node. That is this module. {@link action} is a plain `Action.make`
+ * declaration — catalogable, `.call()`-able, one node in the built plan — and
+ * {@link layer} is the implementation.
+ *
+ * Nothing about resolution is new. The wait is a `DurableDeferred`, so whoever
+ * satisfies it completes it the way every other durable deferred is completed:
+ * a token, and `DurableDeferred.succeed`, `fail`, `failCause`, or `done`.
+ * {@link deferred} is how a resolver names the same wait point the action
+ * awaits. The park is declared through the ordinary waiting vocabulary
+ * ({@link module:WaitingAnnotation.annotateWaiting}) under `event`, carrying
+ * that token as the compare-and-swap material a wake handler matches. Replay is
+ * the deferred's: once a result is recorded, a re-driven round reads it and
+ * runs through instead of parking again.
+ *
+ * @since 0.1.0
+ */
+
+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 { FlowInstance } from "./FlowRuntime/FlowInstance.ts"
+import type { FlowRuntime } from "./FlowRuntime/FlowRuntime.ts"
+import { annotateWaiting } from "./FlowRuntime/WaitingAnnotation.ts"
+
+/**
+ * A wait whose payload does not name exactly one reachable wait point.
+ *
+ * A payload names the wait point by `name`, relative to the running execution,
+ * or by an absolute `token`. Naming both, or neither, leaves nothing to await;
+ * a token that does not parse names nothing either; and a token addressed to a
+ * different flow or a different execution names a wait point this execution
+ * cannot observe, because a durable deferred result is recorded against the
+ * flow and execution that own it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class WaitForRequestInvalid extends Schema.TaggedError<WaitForRequestInvalid>()(
+  "@smthrs/flow/WaitForRequestInvalid",
+  {
+    code: Schema.Literals([
+      "missing_target",
+      "ambiguous_target",
+      "malformed_token",
+      "foreign_execution"
+    ]),
+    message: Schema.String
+  }
+) {}
+
+/**
+ * The tag the wait declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const tag = "system/wait-for"
+
+/**
+ * The durable deferred a named wait point resolves through.
+ *
+ * This is the resolver's half of {@link action}: the value to hand
+ * `DurableDeferred.tokenFromExecutionId` and `DurableDeferred.succeed`, so a
+ * wait that a body declared by name is completed through the existing deferred
+ * completion path rather than a second one.
+ *
+ * ```ts
+ * const gate = WaitFor.deferred("approval")
+ * const token = DurableDeferred.tokenFromExecutionId(gate, { flow, executionId })
+ * yield* DurableDeferred.succeed(gate, { token, value: { approved: true } })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const deferred = (name: string): DurableDeferred.DurableDeferred<typeof Schema.Json> =>
+  DurableDeferred.make(`WaitFor/${name}`, { success: Schema.Json })
+
+/**
+ * The declared wait action: a wait point named by `name` or by `token`.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever a round has to wait for something outside the run —
+ * an approval, a webhook, a human — `WaitFor.action.call({ name: "approval"
+ * })`. The node settles with whatever value resolved the wait, so downstream
+ * steps read it the way they read any other step result.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const action: Action.Declared<
+  typeof tag,
+  Schema.Struct<{
+    readonly token: Schema.optional<Schema.String>
+    readonly name: Schema.optional<Schema.String>
+  }>,
+  typeof Schema.Json,
+  typeof WaitForRequestInvalid,
+  never
+> = Action.makeSystem(tag, {
+  payload: {
+    token: Schema.optional(Schema.String),
+    name: Schema.optional(Schema.String)
+  },
+  success: Schema.Json,
+  error: WaitForRequestInvalid,
+  tier: "sealed"
+})
+
+/**
+ * The deferred name a token addresses, refused when the token does not parse.
+ *
+ * @private
+ */
+const parseToken = (token: string): Effect.Effect<DurableDeferred.TokenParsed, WaitForRequestInvalid> =>
+  Effect.mapError(
+    DurableDeferred.TokenParsed.parse(token),
+    (error) =>
+      new WaitForRequestInvalid({
+        code: "malformed_token",
+        message: `${tag} was called with a token that is not a durable deferred token. ${error.message}`
+      })
+  )
+
+/**
+ * The wait point a payload names, resolved against the running execution.
+ *
+ * DECIDED: a payload names EXACTLY one of `name`
+ * and `token`, and a token must address the execution that is waiting. A
+ * deferred result is recorded against (flow name, execution id, deferred name)
+ * and read back the same way, so awaiting a foreign token would park forever
+ * while the value it names was recorded elsewhere; refusing it names the
+ * mistake instead. BOTH halves of the owning execution's identity are compared:
+ * a token carries its own flow name, so a same-execution token minted for
+ * another flow completes under that flow while this one reads under its own,
+ * which is the same permanent park by a different route.
+ *
+ * DECIDED: a wait point is addressed by the
+ * PAYLOAD, and the per-dispatch identity {@link module:Sleep} derives its clock
+ * from is deliberately NOT applied here. A wait is a rendezvous with something
+ * outside the run, and a resolver has to name the same wait point to complete
+ * it, so the name is the author's and two calls naming one wait point await one
+ * fact — which is the intended reading, not an aliasing bug. A sleep has no
+ * counterpart to agree with, which is why it takes its identity from the node.
+ *
+ * @private
+ */
+const target = (
+  payload: { readonly token?: string | undefined; readonly name?: string | undefined },
+  flowName: string,
+  executionId: string
+): Effect.Effect<DurableDeferred.DurableDeferred<typeof Schema.Json>, WaitForRequestInvalid> => {
+  if (payload.token !== undefined && payload.name !== undefined) {
+    return Effect.fail(
+      new WaitForRequestInvalid({
+        code: "ambiguous_target",
+        message: `${tag} was called with both "token" and "name". A wait names one wait point: ` +
+          "a name relative to this execution, or an absolute token."
+      })
+    )
+  }
+  if (payload.name !== undefined) return Effect.succeed(deferred(payload.name))
+  if (payload.token !== undefined) {
+    return Effect.flatMap(
+      parseToken(payload.token),
+      (parsed) =>
+        parsed.flowName !== flowName || parsed.executionId !== executionId
+          ? Effect.fail(
+            new WaitForRequestInvalid({
+              code: "foreign_execution",
+              message: `${tag} was called with a token addressed to flow "${parsed.flowName}" in execution ` +
+                `"${parsed.executionId}", but it is running as flow "${flowName}" in execution ` +
+                `"${executionId}". A durable deferred result is recorded against the execution that owns it, ` +
+                "so only that execution can await it."
+            })
+          )
+          : Effect.succeed(
+            DurableDeferred.make(parsed.deferredName, { success: Schema.Json })
+          )
+    )
+  }
+  return Effect.fail(
+    new WaitForRequestInvalid({
+      code: "missing_target",
+      message: `${tag} was called with neither "token" nor "name", so there is no wait point to await.`
+    })
+  )
+}
+
+/**
+ * The wait implementation: park under `event` with the wake token, and settle
+ * with the value that resolved the wait.
+ *
+ * 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(WaitFor.layer, Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime> = action.toLayer((payload) =>
+  Effect.gen(function*() {
+    const instance = yield* FlowInstance
+    const waitPoint = yield* target(payload, instance.flow._tag, instance.executionId)
+    const token = DurableDeferred.tokenFromExecutionId(waitPoint, {
+      flow: instance.flow,
+      executionId: instance.executionId
+    })
+    yield* annotateWaiting({ reason: "event", token })
+    return yield* DurableDeferred.await(waitPoint)
+  })
+)

package/src/index.ts

@@ -0,0 +1,125 @@
+// Deep reviewed and polished by a human on 2026-08-10.
+
+/**
+ * @since 0.1.0
+ */
+
+/**
+ * Durable action definitions and combinators.
+ *
+ * @since 0.1.0
+ */
+export * as Action from "./Action/index.ts"
+
+/**
+ * Durable clock and timer services.
+ *
+ * @since 0.1.0
+ */
+export * as Deadline from "./Deadline.ts"
+export * as DurableClock from "./DurableClock.ts"
+
+/**
+ * Durable deferred values.
+ *
+ * @since 0.1.0
+ */
+export * as DurableDeferred from "./DurableDeferred.ts"
+
+/**
+ * Durable queues.
+ *
+ * @since 0.1.0
+ */
+export * as DurableQueue from "./DurableQueue.ts"
+
+/**
+ * Durable flow definitions.
+ *
+ * @since 0.1.0
+ */
+export * as Flow from "./Flow/index.ts"
+
+/**
+ * The execution contract flow authoring APIs are written against.
+ *
+ * @since 0.1.0
+ */
+export * as FlowRuntime from "./FlowRuntime/index.ts"
+
+/**
+ * One typed fault for every failure, and the response table that reads it.
+ *
+ * @since 1.0.0
+ */
+export * as Fault from "./Fault.ts"
+
+/**
+ * External workers observed through durable actions and timers.
+ *
+ * @since 1.0.0
+ */
+export * as ExternalJob from "./ExternalJob.ts"
+
+/**
+ * Plan-time graph building from flow declarations.
+ *
+ * @since 0.1.0
+ */
+export * as Graph from "./Graph.ts"
+
+/**
+ * Asking a person something: typed answers, re-asking, and a deadline.
+ *
+ * @since 0.1.0
+ */
+export * as HumanTask from "./HumanTask.ts"
+
+/**
+ * Execution of a flow body, and the layer that registers it.
+ *
+ * @since 0.1.0
+ */
+export * as Interpreter from "./Interpreter.ts"
+
+/**
+ * The durable poller: attempts as rounds, waits as durable timers.
+ *
+ * @since 0.1.0
+ */
+export * as Poll from "./Poll.ts"
+
+/**
+ * The stall breaker: rounds whose tree, failing checks, or output held still.
+ *
+ * @since 1.0.0
+ */
+export * as Stall from "./Stall.ts"
+
+/**
+ * Retry policy models and constructors.
+ *
+ * @since 0.1.0
+ */
+export * as RetryPolicy from "./RetryPolicy.ts"
+
+/**
+ * The system timer action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as Sleep from "./Sleep.ts"
+
+/**
+ * Stable step identity construction.
+ *
+ * @since 0.1.0
+ */
+export * as StepIdentity from "./Action/StepIdentity.ts"
+
+/**
+ * The system wait-point action and its implementation layer.
+ *
+ * @since 0.1.0
+ */
+export * as WaitFor from "./WaitFor.ts"

package/src/internal/BoundedJson.ts

@@ -0,0 +1,109 @@
+/**
+ * Human-task diagnostics over the shared inert JSON boundary.
+ * @since 1.0.0
+ */
+
+import * as BoundedJson from "@smthrs/canonical/BoundedJson"
+
+/** Resource limits for one human-task value.
+ * @private
+ * @since 1.0.0
+ */
+export type Limits = Required<Omit<BoundedJson.Limits, "maxTotalMembers">>
+
+/** Encoded JSON bytes, without allocating an encoded copy.
+ * @private
+ * @since 1.0.0
+ */
+export const encodedStringBytes = BoundedJson.encodedStringBytes
+
+/** Whether text is well-formed and fits its encoded byte budget.
+ * @private
+ * @since 1.0.0
+ */
+export const textFits = (value: string, maximum: number): boolean => encodedStringBytes(value, maximum) !== undefined
+
+/** Admits a detached snapshot and gives failures a bounded field path.
+ * @private
+ * @since 1.0.0
+ */
+export const admit = (input: unknown, limits: Limits) => {
+  const result = BoundedJson.admit(input, limits)
+  if (result.ok) return { ok: true as const, value: result.value }
+  const at = result.path.length === 0
+    ? "the value"
+    : `"${result.path.map((segment) => scalarPrefix(segment, 64)).join(".")}"`
+  const complaint = result.code === "string"
+    ? `is not well-formed text within ${limits.maxStringBytes} encoded bytes`
+    : result.code === "nodes"
+    ? `makes the value too large to check: it contains more than ${limits.maxNodes} JSON values`
+    : result.complaint
+  return { ok: false as const, complaint: `${at} ${complaint}.` }
+}
+
+/**
+ * Returns a Unicode-scalar-safe bounded prefix.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export function scalarPrefix(value: string, maximumCodeUnits: number): string {
+  let output = ""
+  for (let index = 0; index < value.length;) {
+    const unit = value.charCodeAt(index)
+    let next: string
+    let width = 1
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const low = value.charCodeAt(index + 1)
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        next = value.slice(index, index + 2)
+        width = 2
+      } else {
+        next = "\ufffd"
+      }
+    } else if (unit >= 0xdc00 && unit <= 0xdfff) {
+      next = "\ufffd"
+    } else {
+      next = value[index]!
+    }
+    if (output.length + next.length > maximumCodeUnits) break
+    output += next
+    index += width
+  }
+  return output
+}
+
+/**
+ * Renders an untrusted value without invoking its code or allocating from its full size.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const render = (value: unknown, maximumCodeUnits: number): string => {
+  if (typeof value === "string") {
+    const prefix = scalarPrefix(value, Math.max(0, maximumCodeUnits - 2))
+    const quoted = JSON.stringify(prefix)
+    return prefix.length < value.length
+      ? `${quoted} [${value.length - prefix.length} characters dropped]`
+      : quoted
+  }
+  if (typeof value === "bigint") return scalarPrefix(`${value}n`, maximumCodeUnits)
+  if (typeof value === "symbol") return "[symbol]"
+  if (typeof value === "function") return "[function]"
+  if (value === undefined) return "[undefined]"
+
+  const admitted = admit(value, {
+    maxNodes: 64,
+    maxDepth: 6,
+    maxBytes: Math.max(64, maximumCodeUnits * 4),
+    maxStringBytes: Math.max(64, maximumCodeUnits * 4),
+    maxKeyBytes: Math.max(32, maximumCodeUnits * 2),
+    maxMembers: 32
+  })
+  if (!admitted.ok) return scalarPrefix(`[${admitted.complaint}]`, maximumCodeUnits)
+  const rendered = JSON.stringify(admitted.value)
+  const prefix = scalarPrefix(rendered, maximumCodeUnits)
+  return prefix.length < rendered.length
+    ? `${prefix} [${rendered.length - prefix.length} characters dropped]`
+    : prefix
+}

package/src/internal/DeclarationSite.ts

@@ -0,0 +1,214 @@
+/**
+ * Where a declaration was written: the author's file and the line it starts
+ * on.
+ *
+ * A digest says what a step IS; it cannot say where to read it. A monitor that
+ * offers to show the code behind a node needs the file and line the
+ * declaration was authored at, so the declaration carries it from the moment
+ * it is made — captured from an `Error` stack, which is the only place a
+ * JavaScript runtime keeps it.
+ *
+ * Two properties make this safe to carry. It is stored as a NON-ENUMERABLE
+ * own property, so canonical serialization — which walks enumerable keys —
+ * cannot see it, and a declaration's key material is byte-identical with and
+ * without it. And every parse is defensive: an engine whose stack format this
+ * module does not recognize yields `undefined`, never a throw and never a
+ * guessed location.
+ *
+ * Frames inside the framework are skipped, because the frame that matters is
+ * the AUTHOR's: `Action.make` is called from this package, and the interesting
+ * line is the one that called it.
+ *
+ * @since 1.0.0
+ */
+
+/** The own property a declaration carries its source position on. @private */
+const TypeId = "~@smthrs/flow/DeclaredAt"
+
+/**
+ * The file and line a declaration was written at.
+ *
+ * `path` is the path the runtime reported, which is absolute in every engine
+ * this repository runs on. A journal writer makes it repo-relative before it
+ * records it, and omits it when it cannot: an absolute home directory is not
+ * a fact a durable record may carry.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface DeclaredAt {
+  readonly path: string
+  readonly line: number
+}
+
+/**
+ * Whether a frame belongs to the framework or the runtime rather than to an
+ * author.
+ *
+ * Three shapes are not an author's. Anything under a `node_modules` directory,
+ * which is how a published `@smthrs/*` package is loaded. Anything under a
+ * `packages/smithers/**\/src` directory, which is how this repository loads the
+ * same code from source. And anything that does not name a file at all: a
+ * declaration made inside the framework is reached through the module loader,
+ * so the first frame under it is a runtime internal such as
+ * `node:internal/process/task_queues`, which is a real frame and a false
+ * author. A test, an example, and a workspace's own flow file are absolute
+ * paths under none of those, so they are what a capture reports.
+ *
+ * Windows spells those same two directories with backslashes, so separators
+ * are read as one before matching: a framework frame taken for an author's
+ * would name this package's own `make.js` as the site every node of that run
+ * was declared at.
+ *
+ * @since 1.0.0
+ * @category predicates
+ */
+export const isFrameworkPath = (path: string): boolean => {
+  if (!isFilePath(path)) return true
+  const separated = path.replaceAll("\\", "/")
+  return separated.includes("/node_modules/") || /\/packages\/smithers\/.*\/src\//.test(separated)
+}
+
+/** Whether a frame path names a file on disk rather than a runtime module. @private */
+const isFilePath = (path: string): boolean => path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path)
+
+/** The `path:line:column` text of one stack frame, in either engine's spelling. @private */
+const location = (frame: string): string | undefined => {
+  const parenthesized = /\(([^()]*)\)\s*$/.exec(frame)
+  if (parenthesized !== null) return parenthesized[1]
+  const trimmed = frame.trim()
+  const at = trimmed.lastIndexOf("@")
+  if (at >= 0) return trimmed.slice(at + 1)
+  return trimmed.startsWith("at ") ? trimmed.slice(3) : undefined
+}
+
+/** A `file://` url reported as a frame path, as an ordinary path. @private */
+const normalize = (path: string): string =>
+  path.startsWith("file://") ? decodeURIComponent(path.slice("file://".length)) : path
+
+/**
+ * Where bytes a host evaluated from one file were read from. @private
+ *
+ * Keyed by the file that was evaluated, which a loader makes unique per load.
+ */
+const sourcesKey = Symbol.for("@smthrs/flow/DeclaredAt/sources/v1")
+const globals = globalThis as typeof globalThis & { [sourcesKey]?: Map<string, string> }
+const sources = globals[sourcesKey] ??= new Map<string, string>()
+
+/**
+ * States that a file this runtime is about to evaluate holds bytes read from
+ * another, so declarations inside it report the file an author can open.
+ *
+ * A host that verifies a flow's source has to evaluate THE BYTES IT MEASURED,
+ * and the only way to evaluate bytes in this runtime is to write them
+ * somewhere and import that path. `@smthrs/registry` `Executable` writes them
+ * as a scratch sibling of the entry and removes it as soon as the load is
+ * over, so without this every declaration in an agent-authored flow reports a
+ * path nothing holds — a Code tab that can never be opened (D-068).
+ *
+ * The loader states this BEFORE the import, because a declaration's site is
+ * captured while the module is evaluated and is never rewritten afterwards.
+ * One entry is kept per load: a scratch path is unique and gone, so no later
+ * file can take a stale entry's name.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const evaluatedFrom = (evaluated: string, entry: string): void => {
+  sources.set(normalize(evaluated), normalize(entry))
+}
+
+/**
+ * The position one stack frame names, in the V8 and JavaScriptCore spellings.
+ *
+ * V8 writes `    at name (/path/file.ts:12:5)` and, for a top-level frame,
+ * `    at /path/file.ts:12:5`. JavaScriptCore — Bun and Safari — writes
+ * `name@/path/file.ts:12:5` and `@/path/file.ts:12:5`. Anything else is
+ * unparseable and reports nothing.
+ *
+ * @since 1.0.0
+ * @category parsers
+ */
+export const parseFrame = (frame: string): DeclaredAt | undefined => {
+  const text = location(frame)
+  if (text === undefined) return undefined
+  const position = /^(.*):(\d+):(\d+)$/.exec(text)
+  if (position === null) return undefined
+  const line = Number(position[2])
+  // A frame naming a file a host evaluated measured bytes into reports the
+  // entry those bytes were read from; every other frame reports itself.
+  const path = normalize(position[1]!)
+  return { path: sources.get(path) ?? path, line }
+}
+
+/**
+ * The first author frame of a captured stack.
+ *
+ * The header line every V8 stack starts with parses as nothing, so it needs no
+ * special case. A decoding failure inside a frame path — a malformed percent
+ * escape in a `file://` url — is an unparseable stack rather than a throw,
+ * which is the whole contract of this module: provenance is a nicety, and a
+ * nicety may never take a declaration down with it.
+ *
+ * @since 1.0.0
+ * @category parsers
+ */
+export const parseStack = (stack: string | undefined): DeclaredAt | undefined => {
+  if (stack === undefined) return undefined
+  try {
+    for (const frame of stack.split("\n")) {
+      const parsed = parseFrame(frame)
+      if (parsed !== undefined && !isFrameworkPath(parsed.path)) return parsed
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Where the caller of the function calling this was written.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const capture = (): DeclaredAt | undefined => parseStack(new Error().stack)
+
+/**
+ * Carries a source position on a declaration without adding a field to it.
+ *
+ * The property is non-enumerable and non-writable, so it cannot reach a
+ * canonical serialization, a digest, or a structural clone, and a later caller
+ * cannot rewrite one declaration's provenance to another's.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const annotate = <A extends object>(value: A, site: DeclaredAt | undefined): A => {
+  // A declaration annotated twice keeps the FIRST site. The property is
+  // non-configurable, so a second `defineProperty` would throw rather than
+  // overwrite, and a copy that carries its own site has already recorded it.
+  if (site === undefined || Object.getOwnPropertyDescriptor(value, TypeId) !== undefined) return value
+  Object.defineProperty(value, TypeId, {
+    configurable: false,
+    enumerable: false,
+    value: site,
+    writable: false
+  })
+  return value
+}
+
+/**
+ * The source position a value carries, when it carries one.
+ *
+ * Read through an own data descriptor, so neither a prototype nor an accessor
+ * on a foreign value can answer for it.
+ *
+ * @since 1.0.0
+ * @category accessors
+ */
+export const declaredAt = (value: unknown): DeclaredAt | undefined => {
+  if (Object(value) !== value) return undefined
+  const descriptor = Object.getOwnPropertyDescriptor(value, TypeId)
+  return descriptor === undefined ? undefined : descriptor.value as DeclaredAt | undefined
+}