[reeceyang]

Summary

Replaces v.string() with v.function() (convex/convex#59475) for function handles, so they're validated as handles and typed as FunctionHandle_future. With convex/convex#59998 deployed, the signatures carry through to the generated ComponentApi. Same change as convex/workpool#250.

• src/component/schema.ts:
  • workflowHandle is v.function({ fnType: "mutation", args: { workflowId: v.string(), generationNumber } }). The component calls it with the document Id<"workflows">, not the branded WorkflowId, so workflowId is v.string().
  • onComplete.fnHandle is v.function({ fnType: "mutation", args: { workflowId: vWorkflowId, result, context } }), the same args as nestedWorkflowOnComplete and OnCompleteArgs.
  • Step handles are a bare v.function(), since their function type is only known at runtime.
• src/client/workflowMutation.ts: the direct-call onComplete arg is v.function({ fnType: "mutation" }), and the workflow's own reference is typed "mutation" so its handle matches workflowHandle.
• src/component/workflow.ts: drops the as FunctionHandle<...> casts where handles go to ctx.runMutation.
• Tests cast fake handle strings to FunctionHandle_future<any>.
• package.json: requires convex ^1.49.0, the first release with v.function(), as both the dev dependency and the peer dependency.

The workflowHandle casts at the three workpool.enqueueMutation calls stay. In @convex-dev/workpool 0.4.14, enqueue* infers through FunctionReference, which rejects FunctionHandle_future. Making workpool's client accept FunctionReference_future would remove them. The step-handle casts in journal.ts stay because the type is only known at runtime.

Compatibility

• The direct-call onComplete validator runs in apps that define workflows, so those apps need a backend that supports v.function(). This matters for self-hosted deployments.
• Generated types show workflowId: string for onComplete, because validator JSON can't carry the WorkflowId brand.

Testing

Ran codegen against a dev deployment, then tsc --noEmit, build, lint, the example/convex typecheck, and npm test (129 passed), and reran codegen, typechecks and tests on convex 1.49.0. Checked that the generated types reject a query handle for workflowHandle and onComplete, and a mutation with the wrong args for onComplete.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@convex-dev/workflow@311

commit: 66cc46b

[ianmacartney]

did you try running it with an older version, then migrating to v.function to ensure they still validate in the table? And will it do a table scan on the workflows steps table when deployed the first time? I think a lot of users likely forget to clean up older workflows, so they might have a migration on their hands. maybe we could publish an intermediate version that stages the schema change..

…

On Tue, Oct 27, 2026 at 10:54 AM pkg-pr-new[bot] ***@***.***> wrote: *pkg-pr-new[bot]* left a comment (convex/workflow#311) <#311 (comment)> Open in StackBlitz <https://pkg.pr.new/template/946f7e7a-3e9d-416c-ad27-d19e15cf449c> npm i ***@***.******@***.*** *commit: e599d7f <https://github.com/convex/workflow/runs/122368055505>* — Reply to this email directly, view it on GitHub <#311?email_source=notifications&email_token=AACZQW5WNWVKBKF3IL5JBRT5WDOM3A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMNBUHE2TMOJRHAZKM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-6449569182>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW36P2DRZSJLF6AUQZL5WDOM3AVCNFSNUABFKJSXA33TNF2G64TZHM4DKNBYGI3DONBQHNEXG43VMU5TMMBWGQ3TMMJRHA22C5QC> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>