# workflow-dbos

Lane C implementation of AWP's `DurableWorkflowProvider` over DBOS.

## Boundary

AWP application/domain owns workflow meaning, lifecycle, authorization, IDs and audit/event semantics. This package owns only DBOS execution mechanics and provider mapping.

The provider maps one AWP `OperationId` deterministically to `awp:<operationId>`, uses that explicit DBOS workflow ID as the idempotency key, reconciles ambiguous start outcomes before a retry, supports cancellation/readback, and normalizes DBOS statuses into AWP provider observations.

`DbosSdkRuntime` is a structural bridge to the DBOS TypeScript SDK. The source-fit baseline verified for I0 is `@dbos-inc/dbos-sdk@4.26.10`, using `DBOS.startWorkflow(..., { workflowID, workflowAttributes })`, `DBOS.getWorkflowStatus()` and `DBOS.cancelWorkflow()`. The provider package pins that SDK version directly. The root lockfile is intentionally not edited in this parallel lane; convergence must regenerate the shared lockfile importer for this provider package.

No DBOS SDK type appears in `@awp/application`, `@awp/contracts` or `@awp/domain`.

## External side effects

`runIdempotentSideEffect` provides the provider-mechanics law required for externally visible mutations: durable `started` is recorded before execution; a restarted attempt with an in-flight entry reconciles the provider first; completion is then journaled. The helper does not decide domain transitions.

## Live proof

The executable PostgreSQL/DBOS crash-restart proof is environment-dependent and must be recorded separately. Unit/integration tests in `tests/integration/dbos/**` prove deterministic identity, duplicate suppression, restart reconciliation, cancellation and duplicate-side-effect recovery with a persistent fake runtime/journal; they are not represented as a substitute for the required live PostgreSQL proof.