[adr] Behavioral contract for the low-level WebDriver BiDi layer

docs/decisions/17786-bidi-low-level-behavioral-contract.md

@@ -0,0 +1,148 @@
+# 17786. Behavioral contract for the low-level WebDriver BiDi layer
+
+- Status: Proposed
+- Discussion: https://github.com/SeleniumHQ/selenium/pull/17786
+
+## Context
+
+The WebDriver BiDi specification is defined in CDDL. Any client implementation has a low-level layer
+that turns typed calls into wire messages and wire messages back into typed objects. It sits above a
+transport (which sends commands and correlates responses by id) and below the orchestration and high-level
+API that build on it. *This record is about the low-level layer.*
+
+These behaviors surface only at the wire boundary, and nothing shared enforces them, so bindings drift
+apart without a common reference.
+
+The transport layer (the connection that carries messages and matches responses to their commands) and
+the orchestration layer (session lifecycle, event subscription and routing, and the high-level API these
+feed) are out of scope, as is any ergonomic sugar over these types that a higher public layer adds.
+
+## Decision
+
+In this record, "the spec" is the declared schema the layer validates against, which must include all
+relevant published WebDriver BiDi specifications and any vendor-defined extensions it supports, and may
+include project-maintained overrides where additional flexibility is needed. The spec fixes the layer's
+baseline: spec strings reach the wire verbatim, an *omitted* field stays distinct from an explicit `null`,
+and a union resolves by the rule the spec declares. What it leaves open,
+this record decides in three parts. The first is the typed **representation** the layer exposes; the other
+two are behavior observable at the wire boundary: what it sends **outbound**, and what it receives
+**inbound**.
+
+### Representation
+
+The layer mirrors the spec's modules in the language: each command becomes a typed call, each event a
+typed payload, and each data type a typed object. A caller creates them to send and reads them on receipt.
+
+1. **Represent payloads as typed objects, not raw maps.** Parameters, results, and event payloads must be
+   typed objects: an enum is the language's closed-vocabulary type, and each variant of a union is a
+   distinct type, though variants with identical fields may share a single type that records which variant a
+   value is. Where the spec marks a type extensible, the object also carries an untyped map for the fields
+   the spec does not declare; a non-extensible type does not. A key the type declares must never appear in
+   that map.
+2. **Mirror the spec's command and field names.** Method and field names must follow the spec command
+   and its wire keys, in the language's idiom.
+3. **Preserve a numeric value's full range and precision.** The native type chosen for a numeric value must
+   cover the full range the spec declares for it, with no narrowing or lossy conversion. BiDi integers exceed
+   a 32-bit integer's range, so a binding must not hold them in one. A field with a narrower declared range
+   may use a narrower native type that still covers it.
+4. **Hold a value strictly to its declared type, with no coercion.** This is a definition, not a behavior of
+   its own: the outbound (decision 5) and inbound (decision 7) decisions are what enforce it. A value must be
+   a valid instance of its declared type; the layer must treat it as invalid when it fails:
+   - **structurally**: a `null` in a non-nullable field, an incorrect primitive type, a cardinality
+     mismatch (a list where a single value is declared, or vice versa), or a non-object where a typed object
+     is expected. A primitive matches by JSON kind, not language representation: `number` admits any JSON
+     number, while `integer` rejects a fractional value (`5.7`) but accepts a whole one written `5` or `5.0`.
+   - **by vocabulary**: an enum value outside its defined set, a nullable constant set to anything other
+     than its literal or `null`, a closed-union discriminator the spec does not declare (such as an unknown
+     `script.RemoteValue` type), or a payload that fails to select any variant (a missing discriminator,
+     insufficient structural fields, or a scalar matching none of a union's literal variants).
+
+### Outbound
+
+An outbound payload is Selenium's responsibility. Unless it strictly conforms to the spec, the layer must
+error instead of sending it (caught at compile time where a binding's types allow, otherwise at runtime).
+
+5. **Reject an invalid or missing value.** An invalid value does not match its declared type (decision 4);
+   a missing one is a required field without a value.
+6. **Send an extra field only on an extensible type.** An extensible type carries it in the map (decision 1)
+   and serializes it; a non-extensible type has no such map, so an extra field cannot be represented.
+
+### Inbound
+
+An inbound payload is the remote end's responsibility; the layer must tolerate what it can faithfully
+represent and reject what it cannot. It tolerates a field the spec does not declare (decision 9), so a
+remote end on a newer spec version does not break the binding; it rejects a malformed value (decision 7) or
+a missing required field (decision 8), neither of which yields a valid typed object.
+
+7. **Reject an invalid value.** A value that is present but not a valid instance (decision 4)
+   cannot yield a valid object, so the layer must raise an error.
+8. **Reject a missing required field.** A required field absent from an inbound payload is an error: the
+   layer must raise rather than substitute a placeholder or represent the field as *omitted*.
+9. **Tolerate an undeclared field.** If the type is declared extensible, the layer must preserve the
+   field in the type's map (decision 1). If it is not, the layer must log a warning that an undeclared field
+   was received, and drop it.
+10. **Preserve received values faithfully.** Fidelity is of the value, not its byte-form: a binding may hold
+    any value it parses, a declared field or a retained extra alike, in an ergonomic native type (a 64-bit
+    integer for a `js-int`, a date object for a date), provided it loses nothing and can reproduce what the
+    wire carried. It must not truncate, round, re-case, or otherwise normalize a value beyond
+    recovery.
+
+An error response (a result the remote returns with an error code) must error for the provided reason, an
+unrecognized error code included, even if that reason would otherwise fail one of the validations above.
+
+## Considered options
+
+- **Mandate generation rather than specify behavior.** Require each binding to generate its
+  (de)serialization from the schema, rather than specify the behavior it must exhibit however built.
+  Rejected: generation does not by itself guarantee any behavior and adds cost where it isn't ergonomic; the
+  behaviors are identical however the code is produced, so the contract is the behavior and generation an
+  optional strategy.
+- **Rely on the type system alone, with no runtime conformance.** Let outbound checks fall out of
+  compilation and inbound objects out of casting, with no runtime rejection. Rejected: a statically-typed
+  deserializer fills a correctly-typed object from malformed input and returns it as valid, so types alone
+  pass inbound corruption through, and the contract has to fire at runtime.
+- **Raw dicts rather than typed objects** (decision 1); the spec permits it. Rejected: raw maps structurally
+  cannot do union dispatch, validated field access, or closed-vocabulary enums.
+- **Free naming rather than mirroring the spec** (decision 2). Rejected: divergent surface names let the
+  bindings drift out of step with the spec and one another, defeating the cross-binding coherence that is the
+  point of one contract across many languages.
+- **Defer outbound validation to the server** (decision 5). Send the command and let the remote end return
+  the error the spec defines. Rejected: a local error is clearer and cheaper than a round-trip, and a static
+  binding gets it for free.
+- **Tolerate malformed values, not only absence** (decision 7). Best-effort a wrong-typed or unmappable
+  value rather than erroring. Rejected: unlike a missing field, a present-but-invalid value cannot yield a
+  valid typed object, and tolerating it means a placeholder or a broken object, the failure this layer
+  exists to prevent.
+- **Tolerate an unknown `RemoteValue` variant instead of erroring** (decision 7). Surface an unknown-value
+  carrier that keeps the raw discriminator rather than erroring. Rejected: the trigger is rare (the
+  value-type set is near-complete), and the carrier is a permanent cost, an unknown branch every exhaustive
+  match must handle. Its one merit is recoverability: a consumer can re-derive "throw on unknown" on top of
+  a carrier, but not the reverse. That does not outweigh the cost, and a binding that wants a carrier can
+  still layer one on top. This covers only a carrier for a discriminator the spec does not declare; a shared
+  carrier for a declared variant a binding has not modeled distinctly is the decision-1 representation
+  choice, not this behavior.
+- **Tolerate a missing required field inbound** (decision 8). Represent it as *omitted* and warn instead of
+  erroring, so a lagging remote end does not cost the caller the message. Rejected: an absent required field
+  is then null at runtime, corrupting the typed contract in every statically-typed binding — held null under
+  a non-null type, or widened to nullable so every consumer must check a field the spec guarantees. Only
+  untyped dynamic bindings tolerate freely. Erroring keeps the guarantee and one behavior across bindings; a
+  lagging field is relaxed in the schema (a project override) instead.
+- **Surface message-level extras in this layer** (decision 9) rather than leaving them to the transport.
+  Rejected: the envelope is the transport's; this layer governs per-type extensibility only.
+- **Retain extras only where they can be sent back** (decision 9), narrower than every extensible type.
+  Rejected: "can be sent back" has no schema-defined mapping (a `network.Cookie` round-trips through the
+  differently-typed `storage.PartialCookie`), so the scope would differ across bindings. The spec's
+  `Extensible` marker sanctions the extra fields themselves; retaining them on every extensible type is
+  Selenium's own choice, at the cost of only a few kept fields on types nothing sends back.
+
+## Consequences
+
+- Conformance is checkable independently of how the layer is built, in any language and whether generated
+  or hand-written, so long as the runtime behavior matches.
+- Outbound validity differs in cost by binding: a static binding gets it from construction, while a
+  dynamic binding must enforce it with an explicit runtime check. The contract requires the behavior from
+  both; where a dynamic binding does not yet check, that is a gap to close, not an exemption.
+- Required-ness is symmetric (decisions 5 and 8): a required field is validated, not represented as absent,
+  so it is never null at runtime and no binding widens it to nullable. The cost is backward compatibility —
+  a remote end omitting a newly-required field errors the whole message until that field is relaxed in the
+  schema (a project override), a reactive fix (notice, override, ship) during which the message fails.