docs(workflow): document JF execution policies and platform concurrency limits#166
Merged
Conversation
k1LoW
added a commit
that referenced
this pull request
Jul 14, 2026
…eference Two Copilot review findings on #166: - The Concurrency Control intro implied both policies hold excess work in PENDING, but the job function execution policy suspends the running workflow to PENDING_RESUME (not PENDING). Rewrite the intro to distinguish the two states. - The SDK reference still said "longest matching prefix wins" for overlapping wildcard policies, contradicting the AND-of-caps behavior documented in the guide (matches the current platform implementation). Update the SDK page to describe the stacking behavior. The auto-sync from tailor-platform/sdk will need a matching upstream fix; this edit keeps the two pages consistent in the meantime.
k1LoW
marked this pull request as ready for review
July 14, 2026 09:19
…cy limits The workflow service now supports per-key concurrency control for job function dispatches: workflow scripts pass `executionPolicyKey` on `.trigger()` / `tailor.workflow.triggerJobFunction()`, and workspace-scoped policies declared via `defineWorkflowExecutionPolicies` cap how many dispatches with a matching key run at once. The SDK reference pages (`docs/sdk/services/workflow.md`, `docs/sdk/configuration.md`) are auto-synced from tailor-platform/sdk#1679, but the guide pages and platform-limits reference had no coverage of the new capability yet. - `docs/guides/workflow/index.md`: new "Concurrency Control" section that contrasts the scheduler-level per-workflow `concurrencyPolicy` with the runner-level `executionPolicyKey` mechanism, shows the exact- and wildcard-match modes with runnable SDK snippets, and explains how overlapping policies stack (AND-of-caps) so a broad wildcard cannot be silently disabled by a narrower policy. - `docs/reference/platform/platform-limits.md`: add the two platform hard limits enforced by the workflow runner — workspace-wide 100 dispatches and the per-key fallback of 50 that applies when a policy has no user-defined cap — and describe the `PENDING_RESUME` retry behavior. - `docs/guides/function/builtin-interfaces.md`: update the `tailor.workflow.triggerJobFunction` signature and table to include the new `options.executionPolicyKey` argument, with a link to the SDK reference for policy declaration.
…eference Two Copilot review findings on #166: - The Concurrency Control intro implied both policies hold excess work in PENDING, but the job function execution policy suspends the running workflow to PENDING_RESUME (not PENDING). Rewrite the intro to distinguish the two states. - The SDK reference still said "longest matching prefix wins" for overlapping wildcard policies, contradicting the AND-of-caps behavior documented in the guide (matches the current platform implementation). Update the SDK page to describe the stacking behavior. The auto-sync from tailor-platform/sdk will need a matching upstream fix; this edit keeps the two pages consistent in the meantime.
- `docs/guides/workflow/index.md`: replace the awkward "unaffected by every declared policy" with "unaffected by all declared policies". - `docs/reference/platform/platform-limits.md`: spell out `concurrencyPolicy.maxConcurrentExecutions` (both in the Service Limits table row and in the "Per-key fallback limit" description) so it is unambiguous where the user-defined cap is configured. Matches how the SDK reference names the setting.
…urn type - `docs/sdk/services/workflow.md`: revert the local AND-of-caps rewrite. This file is regenerated by the `sdk-docs-sync` workflow, so hand edits here get overwritten on the next sync. The durable fix belongs upstream in `tailor-platform/sdk`; a follow-up PR there will bring the corrected wording back in through sync. - `docs/guides/function/builtin-interfaces.md`: `triggerJobFunction` returns `Promise<any>` (the surrounding table already spells that out for `triggerWorkflow`, and the code sample `await`s the call).
anukiransolur
approved these changes
Jul 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The workflow service now supports per-key concurrency control for workflow job function (JF) dispatches: workflow scripts pass
executionPolicyKeyon.trigger()/tailor.workflow.triggerJobFunction(), and workspace-scoped policies declared viadefineWorkflowExecutionPoliciescap how many dispatches with a matching key run at once. SDK-side coverage indocs/sdk/services/workflow.mdanddocs/sdk/configuration.mdis auto-synced from tailor-platform/sdk#1679 by thesdk-docs-syncworkflow, but the guide pages and platform-limits reference had no coverage of the new capability yet. This PR fills those gaps.Changes
docs/guides/workflow/index.mdAdd a new Concurrency Control section under How Workflow Execution Works. Structured as:
concurrencyPolicy.maxConcurrentExecutionsoncreateWorkflow(scheduler-level; excess executions stayPENDING). Includes acreateWorkflowsnippet.defineWorkflowExecutionPolicies+executionPolicyKey(runner-level; excess dispatches suspend toPENDING_RESUME). Includes snippets for declaring policies, registering them ontailor.config.ts, and routing dispatches with.key(exact) vs..keyFor(suffix)(wildcard).matchType: "exact"(one shared pool) andmatchType: "prefix"(one independent pool per resolved key).one*, a narrower wildcardone.two*, and an exactone.two.threeall apply simultaneously to a dispatch keyedone.two.three; each covering policy contributes a cap and the tightest one blocks. This corrects the "longest-prefix wins" mental model that the initial rollout implied.docs/reference/platform/platform-limits.mdmaxConcurrentExecutions), and thePENDING_RESUME+ retry-after behavior when a cap is hit.docs/guides/function/builtin-interfaces.mdtailor.workflow.triggerJobFunctionsample and API table to include the newoptions.executionPolicyKeyargument, with an example dispatching through a wildcard policy and a link to the SDK reference for policy declaration.Verification
pnpm build✅ (232 URLs in sitemap, no schema errors, new anchors#concurrency-control,#workflow-level-concurrency-policy,#job-function-execution-policies,#workflow-job-function-concurrency-limitsgenerated).pnpm lint✅ (only the pre-existingsitemap.tsunused-param warning)./sdk/services/workflow#concurrency-policy,/sdk/services/workflow#execution-policies,/reference/platform/platform-limits#workflow-job-function-concurrency-limits,/guides/workflow/#job-function-execution-policies) resolve onpnpm dev.