> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DBOS workflows

> Resources, examples, configuration and evidence for DBOS workflows.

Use the `@bijection/connectors/dbos` entrypoint to declare DBOS workflows resources.

## Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. [Source build and package availability](https://docs.bijection.com/client/sdk-distribution.md).

## Resources and modes

| Resource | Mode | Description |
| - | - | - |
| Workflow | `observed` | observed |

Declare a resource in application code, then bind deployment-specific settings and credentials. See [typed resources](https://docs.bijection.com/integrations/resources.md), [connections](https://docs.bijection.com/integrations/connections.md) and [source inspection](https://docs.bijection.com/integrations/cli.md).

## Workflow

### observed: observed

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { dbos } from "@bijection/connectors/dbos";
import { makeFunctionReference } from "bijection/server";

export const fulfillment = dbos.workflow.observed({
  contract: {
    digest: "2f39298b20b753ce2f10ec54439c4eefb228c8ad7e4776286bf39e57b3a9fc27",
    contract: {
      protocol: "bijection.dbos.v1",
      name: "fulfillment",
      start: {
        workflow: "fulfillment",
        input: {
          type: "object",
          properties: {
            tenant_id: { type: "string" },
            order_id: { type: "string" },
            process_id: { type: "string" },
            terms_hash: { type: "string" },
          },
          required: ["tenant_id", "order_id", "process_id", "terms_hash"],
          additionalProperties: false,
        },
        output: {
          type: "object",
          properties: {
            phase: { type: "string" },
            shipment_id: { type: "string" },
          },
          required: ["phase", "shipment_id"],
          additionalProperties: false,
        },
      },
      commands: {
        decide: {
          workflow: "recordFulfillmentDecision",
          input: {
            type: "object",
            properties: {
              expected_revision: { type: "integer" },
              terms_hash: { type: "string" },
              decision: { type: "string", enum: ["approve", "reject"] },
              actor_id: { type: "string" },
            },
            required: [
              "expected_revision",
              "terms_hash",
              "decision",
              "actor_id",
            ],
            additionalProperties: false,
          },
          output: {
            type: "object",
            properties: {
              status: { type: "string", enum: ["recorded", "rejected"] },
              receipt_id: { type: "string" },
              revision: { type: "integer" },
              decision: { type: "string", enum: ["approve", "reject"] },
              reason: { type: "string" },
            },
            required: [
              "status",
              "receipt_id",
              "revision",
              "decision",
              "reason",
            ],
            additionalProperties: false,
          },
          refusal_field: "status",
          refusal_value: "rejected",
        },
      },
      messages: {
        comment: {
          topic: "comments",
          input: {
            type: "object",
            properties: { text: { type: "string" } },
            required: ["text"],
            additionalProperties: false,
          },
        },
      },
      progress: {
        type: "object",
        properties: {
          tenant_id: { type: "string" },
          order_id: { type: "string" },
          process_id: { type: "string" },
          terms_hash: { type: "string" },
          phase: { type: "string" },
          decision_call_id: { type: "string" },
          shipment_id: { type: "string" },
          execution_id: { type: "string" },
          revision: { type: "integer" },
        },
        required: [
          "tenant_id",
          "order_id",
          "process_id",
          "terms_hash",
          "phase",
          "decision_call_id",
          "shipment_id",
          "execution_id",
          "revision",
        ],
        additionalProperties: false,
      },
      progress_revision_field: "revision",
      allow_cancel: true,
      minimum_evidence_retention_seconds: 604800,
      recovery: "observe_original_only",
      payload_bytes: 16384,
    },
  },
  release: {
    digest: "bb8ea253608c96252e5fda9cbddafbd89d59851a72faf4bbc5dac15c490261a3",
    release: {
      environment_id: "orders_staging_01",
      application: "orders",
      schema: "dbos",
      queue: "fulfillment",
      command_queue: "fulfillment_commands",
      app_version: "orders-dbos-v1",
      build_id: "orders-example-v1",
      contract_digest:
        "2f39298b20b753ce2f10ec54439c4eefb228c8ad7e4776286bf39e57b3a9fc27",
      sdk_version: "5.3.0",
      generator: "bijection.dbos.codegen.v1",
      epoch: "ea3ba8dba53de56f629b126181f84a80529bb8773473c3f7263d1d8b772042ca",
      evidence_retention_seconds: 604800,
      administrative_policy: "no_delete_rewind_or_id_reuse",
      retained: [],
    },
  },
  access: {
    read: makeFunctionReference<"query", any, [null]>("permissions:workflow"),
    reads: [],
  },
  governingRules: {
    start: makeFunctionReference<"query", any, [null]>("permissions:workflow"),
    decide: makeFunctionReference<"query", any, [null]>("permissions:workflow"),
    requestCancellation: makeFunctionReference<"query", any, [null]>(
      "permissions:workflow",
    ),
    comment: makeFunctionReference<"query", any, [null]>(
      "permissions:workflow",
    ),
  },
});
```

> **Inferred record types**
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "key": string;
>   "service_key": string;
>   "execution_id": string;
>   "input": { readonly tenant_id: string; readonly order_id: string; readonly process_id: string; readonly terms_hash: string; } & {};
>   "start_request_id": string;
>   "snapshot": ({ readonly tenant_id: string; readonly order_id: string; readonly process_id: string; readonly terms_hash: string; readonly phase: string; readonly decision_call_id: string; readonly shipment_id: string; readonly execution_id: string; readonly revision: number; } & {}) | null;
>   "result": { kind: "unavailable"; } | { kind: "available"; value: { readonly phase: string; readonly shipment_id: string; } & {}; };
>   "runtime_status": string;
>   "runtime_observed_at": number;
>   "snapshot_revision": number;
>   "observation_id": string;
>   "contract_digest": string;
>   "observed_at": number;
> }
> ```

The function references identify application policy queries. Implement those policies in your application; the references alone grant no authority.

#### Configuration: standard

Case: `dbos/workflow/observed/standard`.

Connection and resource configuration are declared by this exact case.

Credential kind: `http`. Keep credential material in the private credential inventory.

| Setting | Type | Required | Owner |
| - | - | - | - |
| `endpoint` | string | Yes | Shared connection |
| `environment_id` | string | Yes | Shared connection |

> **Complete configuration contract**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {
>       "records": {
>         "read": {
>           "query": "permissions:workflow"
>         },
>         "reads": []
>       }
>     },
>     "defaults": {},
>     "connector": "http",
>     "output": {
>       "kind": "single",
>       "collection": "records"
>     },
>     "credential_kind": "http",
>     "connection_fields": [
>       "endpoint",
>       "environment_id"
>     ],
>     "address": {
>       "kind": "setup",
>       "field": "endpoint"
>     }
>   },
>   "connection_setup": {
>     "type": "object",
>     "value": {
>       "endpoint": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "environment_id": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       }
>     }
>   },
>   "execution": null
> }
> ```

Native admission analysis is available for this exact declaration.

**Collection: records**

| Contract | Meaning |
| - | - |
| Initial | Enumeration of observed records |
| Changes | Repeated observations of current records |
| Deletions | Deletion detection unsupported |
| Resume | Opaque cursor |
| Gap | Explicit repair required after a gap |
| Retention | Unspecified |

> **Complete native profile**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "movement": {
>     "exchanges": {
>       "records": {
>         "200": {
>           "placement": "retained_bytes",
>           "interpretation": "json",
>           "projectsBeforeRetention": false,
>           "retainedBodyLimitBytes": "524288",
>           "fileLimitBytes": null
>         }
>       }
>     },
>     "nativeInputLimitBytes": null,
>     "steps": [
>       {
>         "id": "acquire.1",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "exchange records",
>           "limitBytes": null
>         }
>       },
>       {
>         "id": "retain.1",
>         "inputs": [
>           "acquire.1"
>         ],
>         "action": {
>           "operation": "retain",
>           "subject": "acquisition evidence",
>           "reason": "recovery",
>           "release": "acquisition_custody"
>         }
>       },
>       {
>         "id": "interpret.1",
>         "inputs": [
>           "retain.1"
>         ],
>         "action": {
>           "operation": "interpret",
>           "subject": "acquired input",
>           "produces": "records"
>         }
>       },
>       {
>         "id": "materialize.1",
>         "inputs": [
>           "interpret.1"
>         ],
>         "action": {
>           "operation": "materialize",
>           "subject": "source rows",
>           "reason": "serving",
>           "release": "replacement"
>         }
>       },
>       {
>         "id": "publish.1",
>         "inputs": [
>           "materialize.1"
>         ],
>         "action": {
>           "operation": "publish",
>           "subject": "source rows",
>           "visibility": "with_acquisition"
>         }
>       }
>     ]
>   },
>   "initial": "enumeration",
>   "changes": "observations",
>   "deletions": "unsupported",
>   "resume": "opaque_cursor",
>   "retentionMs": null,
>   "gap": "explicit_repair",
>   "limits": {
>     "http_response_bytes": "524288"
>   },
>   "restrictions": [],
>   "commands": {
>     "comment": {
>       "target": "records",
>       "delivery": "single_attempt",
>       "condition": "unconditional",
>       "replayWindowMs": null,
>       "maxDeliveryHours": "1",
>       "providerEnforcedExpiry": false
>     },
>     "decide": {
>       "target": "records",
>       "delivery": "single_attempt",
>       "condition": "unconditional",
>       "replayWindowMs": null,
>       "maxDeliveryHours": "1",
>       "providerEnforcedExpiry": false
>     },
>     "requestCancellation": {
>       "target": "records",
>       "delivery": "single_attempt",
>       "condition": "unconditional",
>       "replayWindowMs": null,
>       "maxDeliveryHours": "1",
>       "providerEnforcedExpiry": false
>     },
>     "start": {
>       "target": "records",
>       "delivery": "single_attempt",
>       "condition": "unconditional",
>       "replayWindowMs": null,
>       "maxDeliveryHours": "1",
>       "providerEnforcedExpiry": false
>     }
>   }
> }
> ```

**Commands**

| Command | Target | Condition | Delivery |
| - | - | - | - |
| `comment` | records | Unconditional | Single dispatch attempt |
| `decide` | records | Unconditional | Single dispatch attempt |
| `requestCancellation` | records | Unconditional | Single dispatch attempt |
| `start` | records | Unconditional | Single dispatch attempt |

> **Commands, occurrences and artifacts**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "records": {
>     "records": {
>       "protocol": "record_observation",
>       "coverage": "records",
>       "consistency": "observations",
>       "atomicity": "record",
>       "history": "observations",
>       "recordRefresh": false,
>       "reconciliation": false,
>       "notifications": false,
>       "snapshotMaxRows": null,
>       "profile": {
>         "movement": {
>           "exchanges": {
>             "records": {
>               "200": {
>                 "placement": "retained_bytes",
>                 "interpretation": "json",
>                 "projectsBeforeRetention": false,
>                 "retainedBodyLimitBytes": "524288",
>                 "fileLimitBytes": null
>               }
>             }
>           },
>           "nativeInputLimitBytes": null,
>           "steps": [
>             {
>               "id": "acquire.1",
>               "inputs": [],
>               "action": {
>                 "operation": "acquire",
>                 "subject": "exchange records",
>                 "limitBytes": null
>               }
>             },
>             {
>               "id": "retain.1",
>               "inputs": [
>                 "acquire.1"
>               ],
>               "action": {
>                 "operation": "retain",
>                 "subject": "acquisition evidence",
>                 "reason": "recovery",
>                 "release": "acquisition_custody"
>               }
>             },
>             {
>               "id": "interpret.1",
>               "inputs": [
>                 "retain.1"
>               ],
>               "action": {
>                 "operation": "interpret",
>                 "subject": "acquired input",
>                 "produces": "records"
>               }
>             },
>             {
>               "id": "materialize.1",
>               "inputs": [
>                 "interpret.1"
>               ],
>               "action": {
>                 "operation": "materialize",
>                 "subject": "source rows",
>                 "reason": "serving",
>                 "release": "replacement"
>               }
>             },
>             {
>               "id": "publish.1",
>               "inputs": [
>                 "materialize.1"
>               ],
>               "action": {
>                 "operation": "publish",
>                 "subject": "source rows",
>                 "visibility": "with_acquisition"
>               }
>             }
>           ]
>         },
>         "initial": "enumeration",
>         "changes": "observations",
>         "deletions": "unsupported",
>         "resume": "opaque_cursor",
>         "retentionMs": null,
>         "gap": "explicit_repair",
>         "limits": {
>           "http_response_bytes": "524288"
>         },
>         "restrictions": [],
>         "commands": {
>           "comment": {
>             "target": "records",
>             "delivery": "single_attempt",
>             "condition": "unconditional",
>             "replayWindowMs": null,
>             "maxDeliveryHours": "1",
>             "providerEnforcedExpiry": false
>           },
>           "decide": {
>             "target": "records",
>             "delivery": "single_attempt",
>             "condition": "unconditional",
>             "replayWindowMs": null,
>             "maxDeliveryHours": "1",
>             "providerEnforcedExpiry": false
>           },
>           "requestCancellation": {
>             "target": "records",
>             "delivery": "single_attempt",
>             "condition": "unconditional",
>             "replayWindowMs": null,
>             "maxDeliveryHours": "1",
>             "providerEnforcedExpiry": false
>           },
>           "start": {
>             "target": "records",
>             "delivery": "single_attempt",
>             "condition": "unconditional",
>             "replayWindowMs": null,
>             "maxDeliveryHours": "1",
>             "providerEnforcedExpiry": false
>           }
>         }
>       }
>     }
>   },
>   "occurrences": null,
>   "artifacts": {
>     "raw_archive": false,
>     "native_file_transfer_limit_bytes": null,
>     "external_versions": false,
>     "files": {}
>   },
>   "commands": {
>     "comment": {
>       "target": "records",
>       "condition": {
>         "kind": "unconditional"
>       },
>       "delivery": {
>         "kind": "single_attempt",
>         "retention": {
>           "kind": "unknown"
>         },
>         "max_delivery_hours": 1
>       }
>     },
>     "decide": {
>       "target": "records",
>       "condition": {
>         "kind": "unconditional"
>       },
>       "delivery": {
>         "kind": "single_attempt",
>         "retention": {
>           "kind": "unknown"
>         },
>         "max_delivery_hours": 1
>       }
>     },
>     "requestCancellation": {
>       "target": "records",
>       "condition": {
>         "kind": "unconditional"
>       },
>       "delivery": {
>         "kind": "single_attempt",
>         "retention": {
>           "kind": "unknown"
>         },
>         "max_delivery_hours": 1
>       }
>     },
>     "start": {
>       "target": "records",
>       "condition": {
>         "kind": "unconditional"
>       },
>       "delivery": {
>         "kind": "single_attempt",
>         "retention": {
>           "kind": "unknown"
>         },
>         "max_delivery_hours": 1
>       }
>     }
>   }
> }
> ```

**Recorded checks**

| Requirement | Scope | Evidence | Result |
| - | - | - | - |
| page-publication-recovery | \{"kind":"collection","name":"records"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| stated-cursor-empty-page-advances | \{"kind":"collection","name":"records"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| stated-cursor-repeat-refused | \{"kind":"collection","name":"records"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"comment"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"decide"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"requestCancellation"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"start"} | SDK protocol tests and portable checks are separate from native hosted DBOS qualification, which has not been run. | Execution result unavailable |
| identity-account | \{"kind":"connection"} | Fixture: ./src/connectors/dbos/fixtures/identity.json | passed (2026-10-24T21:36:12.668Z) |

Hosted qualification: **unestablished for this catalog configuration**. Installed connections report their own identity, authority and current status.

## Provider guidance

`dbos.workflow.observed` declares a customer-owned DBOS application through the
native HTTP connection, source observation and command owners. Capture an explicit
`dbos.contract` project, generate its application descriptor and worker helpers,
and pin the release. The optional `dbos/worker` and `dbos/adapter` entrypoints use
DBOS SDK 5.3.0; application descriptors import neither the SDK nor PostgreSQL.

Starts confirm the exact persisted execution envelope. Business commands run as
separate DBOS workflows and confirm only a successful, matching output envelope.
A declared refusal field maps a business refusal to a refused native command.
Messages run through generated command workflows: their receipt proves durable
message delivery, not processing or a business decision. Cancellation similarly
confirms a runtime cancellation request; it establishes neither compensation nor
business completion. Customer domain transactions own consequential decisions.

The customer-hosted adapter uses the official `DBOSClient` in the customer network.
It owns no journal, schema migrations, queue provisioning or worker process.
`serveAdapter` binds loopback; terminate authenticated HTTPS in front of it. Its
private PostgreSQL pool has statement, connection and transaction deadlines.
Secret files must be bounded owner-only regular files. Give the adapter only the
runtime privileges needed for the declared DBOS interactions, and provision its
system schema, queues and application versions separately.

Identity checks read application versions and queue ownership for current and
retained releases. They perform no business probes. Generated handler/build
manifests and retention policies are customer attestations; read-only checks do
not establish worker liveness, mutation privileges or handler behavior. Deployment
candidate checks issue the same confined identity GET before activation. Ordinary
installation checks remain in place after activation.

Recovery reads the original command's stored input, workflow name, queue,
application, version, creation identity and output envelope. It never enqueues.
Missing history remains unknown. Execution references retain the original creation
identity and command envelope digest. Observation keys include immutable business
positions; runtime status remains separate. Paging is bounded by count and bytes,
visits explicitly tracked originals first and advances over unrelated entries.

The application epoch requires no deletion, rewind or ID reuse for attached
executions during retention. DBOS rewind can preserve an ID; available SDK evidence
cannot prove continuity across arbitrary administrator rewrites. Change epoch and
explicitly reassociate work after such intervention. Preserve old adapter
endpoints, contract artifacts, worker versions and credentials while accepted
calls depend on them. Retained deployments in one release share its contract;
contract changes require separately retained declarations and bindings.

The approval example in Bijection demonstrates transactional decision receipts,
notification repair, frozen review terms, current authorization, typed result
reads and runtime cancellation. Shared `workflows` helpers only present values
already read through authorized native owners. No result helper grants access
based on a call identifier.

Source implementation and portable tests exist. Hosted DBOS qualification has not
been established; it must be explicitly requested through Atlas with customer
resource isolation, exact serving identities, assertions and cleanup ownership.

Executions remain observable before their first progress event: the source retains
the typed original input and runtime status, with a null business snapshot and
revision -1. Applications must not derive approval terms from that absence. The
example authorizes those rows by the original input tenant and displays startup
failures separately from reviewable business observations.

## Application helpers

All workflow adapters share one application vocabulary. Object-typed inputs are
named command arguments, optional fields included: adding an optional field
never wraps or renames existing arguments. Other values travel as `input`.
Bijection-owned members are camelCase (`start`, `requestCancellation`); names a
contract declares keep their spelling. Serialized routes, capability keys and
records keep their snake\_case wire names.

`<adapter>.commands(contract)` returns each command's target and argument
validators for `commandPolicy` from `bijection/server`, so a policy module types
its inputs without importing the schema that installs the resource.
`<adapter>.policies(contract, "permissions", { reads })` references one exported
policy per command name (`permissions:decideShipment`, ...). Names follow the
contract; a missing export fails deployment analysis.

`<adapter>.observations.select(rows, { bound })` interprets acquired execution
rows the application read through its own indexed queries. It returns
`current`, `missing`, `conflict` (with its reason) or `exceeded`; it never
invents ordering or infers deletion from absence. The application still decides
business association, actor permission and acceptable freshness.
`<adapter>.trace(...)` resolves a retained call's interaction from the generated
`capabilities` and composes it with an authorized observation.

## Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

## Source and evidence

[Canonical connector source](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/src/connectors/dbos/README.md), [native analysis](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/contract-analysis.json) and [check receipts](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/evidence.json).

Connector artifact: `905888ea276a2a28e36981a79e8142b2547ea451c3e63162cb6915ad4a7d1305`.

The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.