feat(stdlib): async sequencing combinators + declare Async effect (Refs echidna#62)

Adds stdlib/future.affine and declares `effect Async;` in
stdlib/effects.affine — the async primitive for the
ReScript->AffineScript migration (echidna#62; Client.res's
`promise<result<T, string>>` chains via Promise.then/catch/resolve).

Model (thin combinators over Result + effect; user-chosen approach):
on the Deno-ESM target the compiler emits native JS async/await and
host promises cross as the Thenable extern ABI (#103) — suspension is
at the extern boundary (echidna#61 Http), so the source needs no
promise monad. An async value is its settled `Result<T, String>`
(Client.res's `result<_, string>`), carried by an `/{Async}`-effect
function. future.affine is the value-level half: a 1:1 map of the
ReScript promise chain onto that Result.

No wrapper type by necessity, not just preference: a user-defined
generic `Async<T>` (ADT or alias) is unusable in signatures — the
typechecker raises "Too many arguments for kind"; only prelude's
multi-constructor `Option`/`Result` are sound generic carriers. This
is a real AffineScript compiler limitation (single-constructor /
aliased generic types) — recorded for a follow-up affinescript issue.
`Result<T, String>` is also exactly Client.res's existing shape.

Surface: resolve (Promise.resolve) / reject / then (Promise.then,
async step) / map_ok (then with pure mapper) / recover (Promise.catch)
/ map_err. effects.affine now declares `effect Async;` (the #196 v1
registry already reserved the name; Vscode.affine already used
`/ Async` — this closes the stdlib coherence gap).

Verified: #136 stdlib-wide AOT smoke gate drives the new file +
modified effects.affine through resolve -> typecheck -> borrow ->
Deno-ESM codegen; `dune runtest` green incl. new "AOT future.affine"
case and unchanged "AOT effects.affine". Regression-protected on merge.

echidna#62 stays open as the consumer-side tracker per its protocol
(closes when the Client.res port lands, not here). Independent of
echidna#63/#64 (no code import) — independent PR off main. Next: #61
http.affine (Deno fetch extern -> the /{Async} boundary; where the
String->Json parse bridge lands).

Refs #128, hyperpolymath/echidna#62.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

stdlib/effects.affine

@@ -10,6 +10,13 @@ effect Mut;
 // Exception effect - panics and error handling
 effect Throws;
 
+// Async effect - promise / suspend semantics. The Deno-ESM backend
+// emits native `async`/`await` and the Thenable extern ABI (issue
+// #103); the v1 effect-row registry (#196) already reserves `Async`.
+// Declared here so the stdlib effect-declarations file is coherent
+// with the registry (echidna#62). Tracking-only in v1 (no handler).
+effect Async;
+
 // Built-in IO operations
 extern fn print(s: String) -> Unit / IO;
 extern fn println(s: String) -> Unit / IO;

stdlib/future.affine

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2025 hyperpolymath
+//
+// Future - async sequencing combinators (echidna#62)
+//
+// Backs the ReScript->AffineScript migration's async requirement
+// (echidna `[migration-roadmap.rescript-to-affinescript]`, Client.res):
+// every Client function is `promise<result<T, string>>` and chains
+// through `Promise.then` / `Promise.catch` / `Promise.resolve`.
+//
+// THE ASYNC MODEL (read before using)
+// -----------------------------------
+// On the migration's Deno-ESM target the compiler emits *native* JS
+// `async`/`await` (lib/codegen_deno.ml: all methods are `async`,
+// `await` on a synchronous value is valid JS) and host promises cross
+// the boundary as the `Thenable` extern ABI (issue #103). Suspension
+// therefore happens *at the extern boundary* (echidna#61 `Http` over
+// Deno fetch); the AffineScript source never needs a promise monad.
+//
+// So an "async value" in the migration is just its settled
+// `Result<T, String>` (the `result<T, string>` half of Client.res's
+// `promise<result<T, string>>`), carried by a function in the `Async`
+// effect (declared in effects.affine; `/{Async}`). These combinators
+// are the **value-level** half — a 1:1 map of the ReScript promise
+// chain onto that `Result` — and intentionally add no wrapper type:
+//
+//   * AffineScript user-defined generic types are not usable in
+//     signatures here (compiler kind limitation: a generic `Async<T>`
+//     ADT/alias raises "Too many arguments for kind"; only prelude's
+//     `Option`/`Result` are sound generic carriers). `Result<T,
+//     String>` is therefore the carrier, which is also exactly the
+//     shape Client.res already uses.
+//
+// ReScript -> this module:
+//   Promise.resolve(x)     -> resolve(x)
+//   Promise.reject / fail  -> reject(e)
+//   p->Promise.then(f)     -> then(p, f)        (f : T -> Result<U,String>)
+//   p->Promise.thenResolve -> map_ok(p, f)      (f : T -> U)
+//   p->Promise.catch(h)    -> recover(p, h)     (h : String -> Result<T,String>)
+//   error remapping        -> map_err(p, f)
+
+module future;
+
+use prelude::{ Result, Ok, Err };
+
+/// `Promise.resolve(x)` — a settled-successful async value.
+pub fn resolve<T>(x: T) -> Result<T, String> {
+  Ok(x)
+}
+
+/// A settled-rejected async value (rejection carried as the error
+/// string, matching Client.res's `result<_, string>`).
+pub fn reject<T>(e: String) -> Result<T, String> {
+  Err(e)
+}
+
+/// `Promise.then` over the success channel: run `f` on success,
+/// short-circuit an existing rejection. `f` itself yields an async
+/// `Result` (so `then` chains async steps, like `.then(x => fetch…)`).
+pub fn then<T, U>(a: Result<T, String>, f: T -> Result<U, String>) -> Result<U, String> {
+  match a {
+    Ok(x) => f(x),
+    Err(e) => Err(e)
+  }
+}
+
+/// `Promise.then` with a pure mapper (`.then(x => pureValue)` /
+/// `thenResolve`): transform the success value, keep rejection.
+pub fn map_ok<T, U>(a: Result<T, String>, f: T -> U) -> Result<U, String> {
+  match a {
+    Ok(x) => Ok(f(x)),
+    Err(e) => Err(e)
+  }
+}
+
+/// `Promise.catch` — recover from a rejection. `h` may itself produce
+/// a fresh async `Result` (resolve a fallback, or re-reject).
+pub fn recover<T>(a: Result<T, String>, h: String -> Result<T, String>) -> Result<T, String> {
+  match a {
+    Ok(x) => Ok(x),
+    Err(e) => h(e)
+  }
+}
+
+/// Remap the rejection reason, leaving a success untouched
+/// (e.g. wrap a low-level error string with context).
+pub fn map_err<T>(a: Result<T, String>, f: String -> String) -> Result<T, String> {
+  match a {
+    Ok(x) => Ok(x),
+    Err(e) => Err(f(e))
+  }
+}