Multi-SDK verification matrix

Referencedraft
On this page

Relay is tested against applications built with the official DBOS Transact SDKs. This matrix defines the required verification gates across supported SDK runtimes: Python, TypeScript, Go, and Java.

Verification matrix

Cell Python TypeScript Go Java
Sample app connects to Relay over the socket; appears in executors required required required required
Conformance suite + REST endpoint probes required required required required
Data plane read: status, list, steps; payloads preserved byte-equal required required required required
Field parity: same workflow via socket and data plane, byte-equal after normalisation required required required may lag (upstream schema v19 vs v107)
Chaos, real timers: SIGKILL executor, recovery on survivor, workflow completes exactly once required required required required
Data-plane cancel and resume while executor is down; restarted executor honours both required required required may lag (upstream schema v19 vs v107)
Fork via data plane to a live version; executor dequeues and runs it required required required required

Cell definitions and test requirements

1. Socket connection and executor presence

The sample application launches and initiates a WebSocket connection to Relay at /websocket/{appName}/{conductorKey}. Relay registers the executor in its live registry, updates its heartbeat lease, and surfaces the executor in the GET /v2/orgs/{org}/apps/{app}/executors API endpoint.

2. Conductor conformance and REST endpoint probes

The Conductor protocol test batteries and HTTP REST endpoint probes run against the connected executor and application. The executor correctly responds to workflow execution, step listing, and telemetry probes. Note that the upstream CLI client binary is not exercised directly in this test suite.

3. Data plane read and payload preservation

Relay reads workflow status, step lists, and outputs directly from the application system database using the SDK client data plane. Complex outputs (Python pickle/JSON, TypeScript JSON, Go JSON/gob) pass through Relay without mutation, preserving payload bytes verbatim.

4. Field parity between socket and database

The same completed workflow is retrieved twice: once over the WebSocket protocol from a live executor, and once via data-plane fallback against the system database. After normalizing timestamps and ephemeral request identifiers, all attributes and payloads must be byte-equal.

5. Chaos recovery under real timers

A workflow executes across multiple steps. The active executor process is terminated with SIGKILL. Relay detects the heartbeat timeout, marks the executor dead, and dispatches recovery to a surviving executor. The workflow resumes from its last checkpoint and completes exactly once.

6. Offline data-plane cancel and resume

While zero executors are running, administrative cancellation and resume operations are issued through the data plane. When an executor restarts, it inspects the system database and honours the updated workflow status.

7. Data-plane fork and live dequeue

A workflow is forked via data-plane API targeting a specific application version. An executor running that version dequeues the workflow from _dbos_internal_queue, executes the remaining steps, and records the outcome.

Lagging cells policy

Cells marked "may lag" are explicitly permitted to lag by at most one iteration. For Java, Cell 4 (field parity) and Cell 6 (offline cancel and resume) lag because upstream DBOS Java SDK 0.8.0 system databases use migration sequence 19, which lacks schema elements (such as completed_at and application_name) expected by the Go SDK data-plane client (version 107). Under ADR 0004 schema safety, Relay's Go data-plane client refuses connection to older schemas rather than attempting uncoordinated DDL. Lagging tests must never be silently omitted: the test runner explicitly reports them as skipped by name in its execution summary. Any required cell without a passing test causes the test runner to fail.

SDK version ceiling

The sample applications in examples/ are pinned inside the supported SDK range, and tests/verifysdk/sdk_ceiling_test.go enforces it: the test reads the example manifests and fails when a pin has moved past the ceiling. That check reads files only, so it runs offline and fast as part of make test, and a future SDK bump cannot leave the supported window silently. The ceiling itself, and the evidence behind it, lives in Supported SDKs.

Payload parity at the ceiling

Cell 4 compares a workflow's fields from the executor's response with a data-plane read of the same workflow. The Go SDK moved workflow inputs, outputs and errors into the workflow_input and workflow_output tables in v1.4.0 (migration 109), so a Go sample application at v1.6.0 stores payloads out of line exactly as Python and TypeScript already did. The pinned Go SDK client v1.3.0 reads payloads from workflow_status only, so the data-plane read returns no payload while the executor's response still carries it. The cell logs that divergence and continues, comparing the remaining fields byte for byte. The gap and the reasoning for keeping the pin are recorded in ADR 0013.