API consistency and improvements

[devhawk]

• DBOS.registerWorkflows -> registerProxy
• added public DBOS.registerWorkflow method
• static DBOS hasWorkflows, getWorkflowName, getWorkflowClassName helpers
• DBOS.startWorkflow overloads accept null StartWorkflowOptions
• DBOS.startWorkflow for registered workflows -> startRegisteredWorkflow
• DBOS.getWorkflowStatus returns Optional
• DBOS.recv & getEvent return generic Optional
• DBOSClient.getEvent return generic Optional
• added DBOS.getRegisteredWorkflow method
• changed DBOSClient.EnqueueOptions ctor param order for consistency
• WorkflowStatus.status string -> WorkflowState
• Update SysDB w/ dbRetry (SqlRunnable) to reduce boilerplate for void return methods
• simplify delegate invocation / use method references where possible

[Copilot]

Pull request overview

This PR standardizes and modernizes the DBOS Java/Kotlin APIs (proxy/workflow registration, workflow status typing, and event/recv return types), and propagates those changes through executor/DB internals and the test suite.

Changes:

• Renames workflow registration to DBOS.registerProxy(...) and introduces/updates helpers for registered workflow lookup and invocation (startRegisteredWorkflow, getRegisteredWorkflows, etc.).
• Changes workflow status typing from string-based status/name to WorkflowState and workflowName, updating DB mappings and protocol outputs.
• Makes getWorkflowStatus, recv, and getEvent return Optional (with generics for recv/getEvent), updating client/server APIs and tests accordingly.

Reviewed changes

Copilot reviewed 67 out of 67 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
transact/src/test/kotlin/dev/dbos/transact/KotlinExtensionsTest.kt	Updates tests to use registerProxy.
transact/src/test/java/dev/dbos/transact/workflow/WorkflowMgmtTest.java	Updates registration and WorkflowState assertions.
transact/src/test/java/dev/dbos/transact/workflow/UnifiedProxyTest.java	Uses registerProxy and typed WorkflowState checks.
transact/src/test/java/dev/dbos/transact/workflow/TimeoutTest.java	Uses registerProxy, Optional, and WorkflowState enum comparisons.
transact/src/test/java/dev/dbos/transact/workflow/SyncWorkflowTest.java	Renames name() usage to workflowName() and updates status assertions.
transact/src/test/java/dev/dbos/transact/workflow/SimpleService.java	Adapts to getWorkflowStatus() returning Optional and enum status.
transact/src/test/java/dev/dbos/transact/workflow/QueueChildWorkflowTest.java	Updates registerProxy and WorkflowState assertions.
transact/src/test/java/dev/dbos/transact/workflow/MgmtService.java	Adjusts recv to Optional return.
transact/src/test/java/dev/dbos/transact/workflow/ListWorkflowsTest.java	Updates filters/assertions for workflowName() and WorkflowState.
transact/src/test/java/dev/dbos/transact/workflow/GarbageCollectionTest.java	Updates registerProxy and status comparisons.
transact/src/test/java/dev/dbos/transact/workflow/ForkTest.java	Updates getEvent usage to Optional<T> and enum statuses.
transact/src/test/java/dev/dbos/transact/workflow/AsyncWorkflowTest.java	Updates registration and status/name assertions.
transact/src/test/java/dev/dbos/transact/utils/WorkflowStatusRow.java	Renames name field to workflowName in test utilities.
transact/src/test/java/dev/dbos/transact/utils/WorkflowStatusBuilder.java	Updates builder to store WorkflowState and workflowName.
transact/src/test/java/dev/dbos/transact/step/StepsTest.java	Updates registration and adds a no-op workflow to satisfy new proxy constraints.
transact/src/test/java/dev/dbos/transact/scheduled/WorkflowScheduleTest.java	Updates scheduling tests to use registerProxy.
transact/src/test/java/dev/dbos/transact/scheduled/AnnotatedWorkflowScheduleTest.java	Updates registration and expected schedule validation error string.
transact/src/test/java/dev/dbos/transact/queue/QueuesTest.java	Updates registration, internal builder usage, and enum-based statuses.
transact/src/test/java/dev/dbos/transact/queue/PartitionedQueuesTest.java	Updates registration and EnqueueOptions argument order.
transact/src/test/java/dev/dbos/transact/notifications/NotificationServiceTest.java	Updates recv to Optional<T> and status assertions; improves interrupt handling.
transact/src/test/java/dev/dbos/transact/notifications/EventsTest.java	Updates getEvent to Optional<T> and registerProxy.
transact/src/test/java/dev/dbos/transact/json/PortableSerializationTest.java	Updates registration, EnqueueOptions order, Optional APIs, and enum statuses.
transact/src/test/java/dev/dbos/transact/json/InteropTest.java	Updates registration, recv typing, and workflowName/enum status expectations.
transact/src/test/java/dev/dbos/transact/issues/Issue218.java	Updates registration and status assertions to use WorkflowState.
transact/src/test/java/dev/dbos/transact/invocation/StartWorkflowTest.java	Updates registration and status assertions to use WorkflowState.
transact/src/test/java/dev/dbos/transact/invocation/PatchTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/invocation/MultiDbosInstanceTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/invocation/MultiClassInstanceTest.java	Updates registration and workflow name/status assertions.
transact/src/test/java/dev/dbos/transact/invocation/MockDbosInstanceTest.java	Updates mocked recv to return Optional.
transact/src/test/java/dev/dbos/transact/invocation/InstanceTest.java	Updates registration and workflow name/status assertions.
transact/src/test/java/dev/dbos/transact/invocation/DirectInvocationTest.java	Updates registration and workflow name/status assertions.
transact/src/test/java/dev/dbos/transact/invocation/CustomSchemaTest.java	Updates registration and workflow name/status assertions.
transact/src/test/java/dev/dbos/transact/execution/SingleExecutionTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/execution/ScaleTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/execution/RecoveryServiceTest.java	Updates registration and enum-based status assertions.
transact/src/test/java/dev/dbos/transact/execution/LifecycleTest.java	Updates to startRegisteredWorkflow and registerProxy.
transact/src/test/java/dev/dbos/transact/execution/DBOSExecutorTest.java	Updates registration and enum-based status assertions.
transact/src/test/java/dev/dbos/transact/database/SystemDatabaseTest.java	Updates internal builder usage (workflowName) and status assertions.
transact/src/test/java/dev/dbos/transact/database/MetricsTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/database/DBTestAccess.java	Renames helper to findHikariConfig.
transact/src/test/java/dev/dbos/transact/database/ChaosTest.java	Updates registration and recv/getEvent to Optional.
transact/src/test/java/dev/dbos/transact/config/ConfigTest.java	Updates workflow registry accessors, registration, and status assertions.
transact/src/test/java/dev/dbos/transact/config/ConfigEnvTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/conductor/ConductorTest.java	Updates status builder usage to workflowName.
transact/src/test/java/dev/dbos/transact/client/PgSqlClientTest.java	Updates registration and status assertions to WorkflowState.
transact/src/test/java/dev/dbos/transact/client/ClientTest.java	Updates registration and EnqueueOptions order + enum status expectations.
transact/src/test/java/dev/dbos/transact/client/ClientService.java	Updates recv to Optional<T>.
transact/src/test/java/dev/dbos/transact/client/ClientScheduleTest.java	Updates registration to registerProxy.
transact/src/test/java/dev/dbos/transact/admin/AdminServerTest.java	Updates status builder usage and JSON response expectations for enum/string conversions.
transact/src/main/java/dev/dbos/transact/workflow/WorkflowStatus.java	Changes status to WorkflowState, renames to workflowName, expands docs, keeps deep equals/hash.
transact/src/main/java/dev/dbos/transact/workflow/internal/WorkflowStatusInternal.java	Renames internal name to workflowName and builder setter.
transact/src/main/java/dev/dbos/transact/internal/WorkflowRegistry.java	Refactors registration API (registerInstance, registerWorkflow) and key composition.
transact/src/main/java/dev/dbos/transact/internal/Invocation.java	Reorders fields to match new invocation parameter ordering.
transact/src/main/java/dev/dbos/transact/internal/DBOSInvocationHandler.java	Uses DBOS helpers for workflow naming/class naming and updated executor invocation signature.
transact/src/main/java/dev/dbos/transact/execution/SchedulerService.java	Uses new registered-workflow lookup API and updated start method name.
transact/src/main/java/dev/dbos/transact/execution/RegisteredWorkflowInstance.java	Simplifies instance record and null-handling in key creation.
transact/src/main/java/dev/dbos/transact/execution/RegisteredWorkflow.java	Renames name to workflowName, changes fully-qualified naming order, modernizes exception unwrapping.
transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java	Renames registry accessors, updates workflow validation/name ordering, adds null-StartWorkflowOptions support, adds startRegisteredWorkflow.
transact/src/main/java/dev/dbos/transact/DBOSClient.java	Reorders EnqueueOptions params, returns Optional from getEvent, updates internal status builder naming.
transact/src/main/java/dev/dbos/transact/DBOS.java	Renames registration to registerProxy, adds helpers and registered workflow accessors, makes status/event/recv APIs Optional.
transact/src/main/java/dev/dbos/transact/database/WorkflowDAO.java	Updates workflow name comparisons and maps DB status string to WorkflowState.
transact/src/main/java/dev/dbos/transact/database/SystemDatabase.java	Adds dbRetry(SqlRunnable) and refactors void-return DB operations to reduce boilerplate.
transact/src/main/java/dev/dbos/transact/database/SchedulesDAO.java	Uses toArray(String[]::new) for typed array creation.
transact/src/main/java/dev/dbos/transact/conductor/protocol/WorkflowsOutput.java	Emits WorkflowState as status.name() and uses workflowName.
transact/src/main/java/dev/dbos/transact/conductor/protocol/ListStepsResponse.java	Minor refactor for formatting/locals.
transact/src/main/java/dev/dbos/transact/conductor/Conductor.java	Uses method references for protocol mapping.
transact/src/main/java/dev/dbos/transact/admin/WorkflowsOutput.java	Emits WorkflowState as status.name() and uses workflowName.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[devhawk]

In addition to startWorkflow Copilot comment, also should go thru and change instance Name to be null when not used instead of empty string

[kraftp]

This is the one change I don't understand. This does register workflows, right? And it doesn't do anything else?

[devhawk]

This method registers workflows and creates a proxy. I didn't want to call it registerWorkflows anymore because there is a registerWorkflow that will need to be public or package private so it can be called by the spring boot code when it comes. So would you like createProxy as a better name here?

[kraftp]

registerWorkflows is the best name in my opinion, since workflows are a core DBOS concept and "proxies" aren't. For the other method, we can make it package private and then it should be fine?

[devhawk]

funny, that's the reason I want don't want to call this registerWorkflows. Spring integration will require an accessible (package private or public) registerWorkflow method that won't create a proxy. Seems like a poor design to have a registerWorkflows that returns a proxy and registerWorkflow that is void return

[devhawk]

leaving the method named registerProxy but opened #341 to track possible name change

[kraftp]

Looks good other than those minor comments. DBOS.registerWorkflows -> registerProxy is the one change I don't understand.