Integrate callable coroutine types with runtime fixtures

docs/guide/runtimes/http.md

@@ -49,6 +49,11 @@ setRuntimeBridge(
 payloads. You must provide a compatible server endpoint. Each call is an
 independent POST request because the protocol is stateless.
 
+Generated async callables have typed results when their return annotations have
+supported value conversions. The in-repo Node and Pyodide bridges await Python
+coroutines. For `HttpBridge`, your server must await coroutines before it sends
+the result. `HttpBridge` cannot verify a remote server's coroutine support.
+
 tywrap does not include an HTTP server. See the [API reference](/reference/api/)
 for the expected request and response format.
 

docs/maintainers/callable-contracts.md

@@ -0,0 +1,114 @@
+# Callable compilation contracts
+
+`tywrap_ir` emits IR 0.4. `validateIrContract()` checks required fields in
+unknown JSON. Each diagnostic has a JSON path. Validation stops after 100,000
+array entries.
+
+`compileContract()` is an internal pure step. It accepts validated IR,
+exported-name selection, value conversions, capabilities, and a generator. It
+maps callable types from the validated IR. The selection input cannot change
+those types. It returns the resolved module, callable records, diagnostics, and
+TypeScript and declaration content.
+
+The compiler does not read files. It does not start Python. It does not read a
+cache. It does not write files. It does not access a runtime registry.
+
+`generate()` owns Python discovery, cache reads, output comparison, and writes.
+It validates IR and maps annotations, then calls `compileContract()` before
+emission. Offline contract files omit extractor metadata for stable bytes. The
+reader restores an empty metadata object.
+
+## Resolved callable data
+
+The compiler records each parameter and result, including overloads. Each record
+has a Python type, direction, source path, and conversion result. One resolved
+module model serves declarations, call wrappers, and return validators.
+
+Each value conversion uses revision 2 of
+[value-contracts.v2.json](value-contracts.v2.json). Do not infer a wire rule
+from the TypeScript type.
+
+| Case                  | Result                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `int`                 | JSON number, JavaScript number, safe-integer constraint                               |
+| `bytes`               | Existing base64 envelope, decoded as `Uint8Array`                                     |
+| nested `dict[str, T]` | JSON record with the child conversion at every value path                             |
+| `str \| int`          | Selected union alternative with one child contract per option                         |
+| `tuple[int, str]`     | Exact JSON array with a contract for each index                                       |
+| float16 ndarray       | Existing Arrow or JSON-fallback envelope, decoded as a numeric scalar or nested array |
+| float16 Torch tensor  | Outer `torch.float16` envelope with a nested `float16` ndarray                        |
+
+The compiler requires an explicit float16 dtype. An untyped ndarray or Torch
+tensor stays unresolved.
+
+For an evaluated PyTorch annotation, use `torch.HalfTensor`. The compiler
+accepts this exact class and leaves other Torch tensor classes unresolved.
+
+NumPy can spell `NDArray[np.float16]` as
+`numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float16]]`. The compiler reads
+the dtype argument, not the shape wildcard. Only a supported scientific result
+clears its matching external-annotation IR warning. Other external annotations
+remain warnings.
+
+The codec records scalar ndarray dtype and rank for one call. A generated return
+validator accepts a scalar only with matching proof. Nested proof follows its
+parent and array index or record key. Array index `0` and `"0"` refer to the
+same child. Equal numbers from separate calls do not share proof. Array and
+tensor objects keep their identity-based marker proof.
+
+The compiler keeps Arrow int64 behavior outside this prototype. Existing Arrow
+int64 values can decode as `bigint`.
+
+Selected local non-generic `TypedDict` classes use revision-2 record contracts
+when every field has a supported conversion. Nested records and selected simple
+aliases compose through the same resolver. Foreign and recursive names remain
+unresolved.
+
+## Diagnostics and fallback
+
+Known unsupported cases create error diagnostics. The compiler changes the
+affected generated type to `unknown`. `generate()` returns each diagnostic as a
+warning, so `--fail-on-warn` rejects strict builds.
+
+- The default compiler capability covers coroutine execution in the in-repo Node
+  and Pyodide bridges. A caller can mark this capability unavailable when it
+  uses an older or custom bridge. The compiler then emits `unknown` and an error
+  diagnostic for async results.
+- Dataclasses require an adapter owned by #339. The default capability stays
+  unavailable. An explicit output record conversion can use the adapter
+  capability when enabled.
+- Non-string record keys require an explicit conversion.
+
+Unresolved annotations create warning diagnostics. Their result type is
+`unknown`, including an output that contains `object` or a type variable. Python
+`object` can hold a primitive value. A type variable has no validated conversion
+to the decoded result. Neither annotation justifies a precise TypeScript return.
+
+The compiler keeps an existing best-effort return check when it widens a
+declaration. For example, an unresolved `list[object]` still rejects a non-array
+result, and a `DataFrame` annotation still requires a decoded marker.
+
+`Literal` returns keep their exact-value validator, but stay `unknown` until a
+literal value contract exists. Unresolved literal overloads cannot select a
+precise return at runtime.
+
+IR overload signatures stay separate from the implementation signature. The
+extractor collects type variables from overload annotations. Generated
+declarations retain each input-to-result relation. The hidden TypeScript
+implementation accepts `unknown` values so it can cover every declared overload.
+
+At runtime, the wrapper selects the first supported overload that matches bound
+arguments. This follows TypeScript declaration order. The compiler warns when
+overload inputs may overlap, including an omitted optional argument. Python 3.10
+cannot expose registered overloads through `typing.get_overloads`; it keeps the
+implementation signature and emits an IR warning.
+
+## Deferred work
+
+Revision 2 does not describe references or recursive aliases. The compiler
+reports these cases as unresolved. A later value-contract revision can give them
+a supported conversion.
+
+The client-binding work may consume the resolved callable model later. It must
+remain opt-in. It must not add files to default generation or mutate the global
+runtime registry.

docs/maintainers/value-contract-fixtures.v2.json

@@ -10,6 +10,20 @@
     { "decimal": "9223372036854775807", "outcome": "reject" },
     { "decimal": "265252859812191058636308480000000", "outcome": "reject" }
   ],
+  "bytesCases": [
+    {
+      "logicalHex": "00ff80",
+      "requestEnvelope": { "__tywrap_bytes__": true, "b64": "AP+A" },
+      "responseEnvelope": { "__type__": "bytes", "encoding": "base64", "data": "AP+A" },
+      "decodedAs": "Uint8Array[0,255,128]"
+    },
+    {
+      "logicalHex": "",
+      "requestEnvelope": { "__tywrap_bytes__": true, "b64": "" },
+      "responseEnvelope": { "__type__": "bytes", "encoding": "base64", "data": "" },
+      "decodedAs": "Uint8Array[]"
+    }
+  ],
   "binary16Cases": [
     { "wordHex": "0000", "outcome": "0" },
     { "wordHex": "8000", "outcome": "-0" },