Duolith docs

0151. The effect bridge has one typed contract, generated for Kotlin and Swift and checked in debug builds

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-15
  • Decided by: wave 5 follow-up agent, pending Mik
  • Planning item: wave 5 handoff, typed effect bridge

Context

The effects reach the phone through one bridge: the TypeScript clients in packages/effects/src/native/ call call(effect, method, args), later(...) and on(effect, event), and Bridge.kt and Bridge.swift route each call to a Kotlin or a Swift route. Every argument and answer crossed as untyped JSON. The names were already checked by reading the sources (bridge-contract.test.ts), but a shape was not: a route reading argument 1 as a number where the client sent text, or an answer missing a field, failed only on a phone, and the browser tests ran against stand-in shells written by hand that could drift the same way. Mik asked for every statically knowable error to fail the build loudly.

Decision

  • One contract. spec/effects/bridge.ts declares BridgeContract: for each of the 30 effects on the bridge, its now calls, its later calls and its on events, with each argument and answer typed by the effect's own spec types. void means no answer.
  • Generated for every side. pnpm generate resolves the contract with the TypeScript checker (tools/generate/effects-bridge/) and writes: A type the generator cannot express (a function, an intersection, a generic) stops the generator rather than becoming Any, and check-generated fails a change to bridge.ts that was not regenerated.
    • native/android/effects/generated/BridgeContract.kt: Kotlin data classes, enums and sealed unions with read(value, at), and BridgeContract.checkCall, checkAnswer and checkEvent;
    • native/ios/effects/generated/BridgeContract.swift: Codable structs, String enums and enum unions, and the same three checks;
    • packages/effects/test/support/generated/bridge-contract.ts: the contract as data, for the tests.
  • Typed clients. client(bridge, effect) is typed by the contract: a method the effect does not have, an argument of another shape, or an answer read as another type fails tsc. A now answer may also be null, because Lynx's first draw answers null before the shell's module is there.
  • Checked at run time in debug builds. With checksContract on (BuildConfig.DEBUG on Android, #if DEBUG on iOS), the bridge checks each call's arguments before routing it and each answer before sending it; one that breaks the contract answers E0433 naming the method and the field (share.copy's argument 1 is the number 7, not a string). An event that breaks it stops the debug build with the same message. Release builds check nothing, so they pay nothing.
  • Checked in the tests.
    • The TypeScript tests wrap their fake bridges with checked(), which applies the same checks, so a fake that answers off the contract fails the test.
    • bridge-contract.test.ts checks that the contract has exactly the names the clients use, that Kotlin and Swift answer and emit every one, and that each argument a Kotlin or Swift case arm reads on its own line is read as the shape the contract sends.
    • BridgeContractTest.kt and BridgeContractTests.swift check the native checks and messages; DeviceRoutesTest.kt checks each route's answers against the contract.

Alternatives considered

OptionWhy not
JSON Schema as the sourceA second language for shapes the effect specs already state in TypeScript; the two would drift.
Protocol Buffers or another IDL with its own codegenA build dependency on every side, and the Lynx bridge carries JSON anyway.
Check in release builds tooEach call would pay for a check whose failures the debug builds and tests already catch.
Hand-written Kotlin and Swift typesThey are what drifted; generating them is what makes a mismatch a compile error.

Consequences

  • A change to a bridge call starts in spec/effects/bridge.ts; after pnpm generate, tsc, the Kotlin compile, the Swift compile and the tests say what else must change.
  • E0433 joins the effects' error codes (spec/effects/common.ts). An app never sees it from a release build.
  • The routes still read their arguments by index; the generated types are there for routes to decode with as they are touched. The readers check covers case arms whose reading sits on the arm's own line; the rest are covered by the debug-build check and the native tests.