@workbasehq/core 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +4 -0
  3. package/package.json +62 -1
  4. package/src/account-provisioning.ts +24 -0
  5. package/src/admin-forms.tsx +70 -0
  6. package/src/admin-security.ts +63 -0
  7. package/src/admin-ui.tsx +438 -0
  8. package/src/app.ts +115 -0
  9. package/src/audit-event.ts +23 -0
  10. package/src/audit.ts +35 -0
  11. package/src/authorization-api.ts +3 -0
  12. package/src/authorization.ts +135 -0
  13. package/src/authorized-execution.ts +15 -0
  14. package/src/bootstrap.ts +23 -0
  15. package/src/browser-dispatch.ts +19 -0
  16. package/src/calendar-display.ts +26 -0
  17. package/src/capabilities.ts +41 -0
  18. package/src/commands.ts +46 -0
  19. package/src/config-proposal-contract.ts +16 -0
  20. package/src/config-proposals.ts +95 -0
  21. package/src/config-shorthand.ts +200 -0
  22. package/src/config.ts +286 -0
  23. package/src/console-contract.ts +105 -0
  24. package/src/console-contribution.ts +7 -0
  25. package/src/console.ts +84 -0
  26. package/src/crud.ts +146 -0
  27. package/src/crypto.ts +33 -0
  28. package/src/detail-display.ts +59 -0
  29. package/src/detail-layout.ts +17 -0
  30. package/src/errors.ts +3 -0
  31. package/src/event-delivery.ts +76 -0
  32. package/src/events.ts +11 -0
  33. package/src/execution/atomic.ts +70 -0
  34. package/src/execution/compiler.ts +55 -0
  35. package/src/execution/context.ts +100 -0
  36. package/src/execution/d1.ts +46 -0
  37. package/src/execution/errors.ts +21 -0
  38. package/src/execution/index.ts +6 -0
  39. package/src/execution/outbox.ts +8 -0
  40. package/src/execution/permissions.ts +9 -0
  41. package/src/execution/policies.ts +156 -0
  42. package/src/execution/policy-receipts.ts +51 -0
  43. package/src/execution/types.ts +74 -0
  44. package/src/execution/workflow.ts +35 -0
  45. package/src/form-display.ts +36 -0
  46. package/src/idempotency.ts +10 -0
  47. package/src/identity-providers.ts +2 -0
  48. package/src/identity-settings.ts +42 -0
  49. package/src/identity-writes.ts +14 -0
  50. package/src/identity.ts +2 -0
  51. package/src/index.ts +32 -0
  52. package/src/json-csrf.ts +22 -0
  53. package/src/kernel/adapters/tenancy.ts +8 -0
  54. package/src/kernel/audit-port.ts +12 -0
  55. package/src/kernel/builtin-source.ts +34 -0
  56. package/src/kernel/composition.ts +77 -0
  57. package/src/kernel/identity-port.ts +36 -0
  58. package/src/kernel/mail-outbox-port.ts +23 -0
  59. package/src/kernel/migrations.ts +76 -0
  60. package/src/kernel/operation-name.ts +8 -0
  61. package/src/kernel/plugin.ts +92 -0
  62. package/src/kernel/predicate.ts +69 -0
  63. package/src/kernel/registry.ts +198 -0
  64. package/src/kernel/schema-check.ts +13 -0
  65. package/src/logging.ts +21 -0
  66. package/src/migrations/better-auth-schema.ts +2 -0
  67. package/src/migrations/email-delivery-schema.ts +6 -0
  68. package/src/migrations/planner.ts +77 -0
  69. package/src/migrations/schema.ts +85 -0
  70. package/src/migrations/version-contract.ts +28 -0
  71. package/src/migrations/versions.ts +90 -0
  72. package/src/ops-schema.ts +13 -0
  73. package/src/ops.ts +34 -0
  74. package/src/organization-permissions.ts +13 -0
  75. package/src/organization-rules.ts +25 -0
  76. package/src/organizations.ts +43 -0
  77. package/src/plugins.ts +3 -0
  78. package/src/policies.ts +186 -0
  79. package/src/public-schema.ts +65 -0
  80. package/src/query/compiler.ts +395 -0
  81. package/src/query/cursor.ts +43 -0
  82. package/src/query/enum-labels.json +16 -0
  83. package/src/query/enum-values.ts +7 -0
  84. package/src/query/errors.ts +10 -0
  85. package/src/query/executor.ts +118 -0
  86. package/src/query/facade.ts +34 -0
  87. package/src/query/labels.ts +105 -0
  88. package/src/query/limits.ts +8 -0
  89. package/src/query/observability.ts +49 -0
  90. package/src/query/routes.ts +60 -0
  91. package/src/query/schema.ts +216 -0
  92. package/src/query/search.ts +15 -0
  93. package/src/relay.ts +65 -0
  94. package/src/request-timing.ts +71 -0
  95. package/src/schema-compatibility.ts +43 -0
  96. package/src/scope-operations.ts +3 -0
  97. package/src/session-contract.ts +1 -0
  98. package/src/types.ts +30 -0
  99. package/src/worker-fetch.ts +14 -0
  100. package/src/workflow-routes.ts +156 -0
  101. package/src/workflow-runtime.ts +327 -0
  102. package/src/workflow-schema.ts +29 -0
@@ -0,0 +1,43 @@
1
+ import { pluginMigrationStatus } from './kernel/migrations'
2
+ import { resolvePlugins } from './kernel/composition'
3
+ import { CORE_VERSION, type InstanceConfig } from './config'
4
+ export interface SchemaEnvironment { SCHEMA_EXPECTED?: string; STAGE?: string }
5
+ export interface SchemaRevision { revision: number; coreVersion: string; migrations: string; pluginMigrations?: string }
6
+ export interface SchemaStatus { enabled: boolean; compatible: boolean; expected: SchemaRevision | null; applied: SchemaRevision | null }
7
+ export async function hashMigrationRows(rows: { filename: string; checksum: string }[]) {
8
+ const bytes = new TextEncoder().encode(JSON.stringify(rows.map(({ filename, checksum }) => ({ filename, checksum }))))
9
+ return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))).map(byte => byte.toString(16).padStart(2, '0')).join('')
10
+ }
11
+ async function migrationRevision(db: D1Database) {
12
+ const rows = await db.prepare('SELECT filename,checksum FROM _migrations ORDER BY filename').all<{ filename: string; checksum: string }>()
13
+ return hashMigrationRows(rows.results)
14
+ }
15
+ // Full validation for health, deployment verification and explicit diagnostic callers.
16
+ // Ordinary request handling never checks schema compatibility.
17
+ // SCHEMA_EXPECTED is injected by SST for every deployed Worker. Local workerd/Wrangler uses its own migration ledger.
18
+ export async function schemaStatus(env: SchemaEnvironment & { DB: D1Database; AUDIT_KV?: KVNamespace }, config?: Pick<InstanceConfig, 'revision'> & Partial<Pick<InstanceConfig, 'plugins' | 'interactive' | 'entities'>>): Promise<SchemaStatus> {
19
+ if (!env.SCHEMA_EXPECTED) return { enabled: false, compatible: !env.STAGE || env.STAGE === 'local', expected: null, applied: null }
20
+ let expected: SchemaRevision | null = null
21
+ try {
22
+ expected = JSON.parse(env.SCHEMA_EXPECTED) as SchemaRevision
23
+ if (!Number.isInteger(expected.revision) || typeof expected.coreVersion !== 'string' || !/^[a-f0-9]{64}$/.test(expected.migrations)) throw new Error('invalid_expected_revision')
24
+ const meta = config || env.AUDIT_KV ? await env.DB.prepare('SELECT revision,core_version FROM instance_meta ORDER BY revision DESC LIMIT 1').first<{ revision: number; core_version: string }>() : { revision: 1, core_version: 'receiver-v1' }
25
+ const applied: SchemaRevision = { revision: meta?.revision ?? -1, coreVersion: meta?.core_version ?? '', migrations: await migrationRevision(env.DB) }
26
+ let pluginsCompatible = true
27
+ if (config?.plugins?.length || expected.pluginMigrations) {
28
+ if (!config?.plugins || !/^[a-f0-9]{64}$/.test(expected.pluginMigrations ?? '')) throw new Error('missing_plugin_revision')
29
+ const plugins = resolvePlugins(config.plugins, config.interactive).plugins
30
+ if (!config.entities) throw new Error('missing_instance_schema')
31
+ const pluginStatus = await pluginMigrationStatus(env.DB, plugins, { entities: config.entities })
32
+ for (const plugin of plugins) await plugin.checkEnvironment?.(env)
33
+ applied.pluginMigrations = pluginStatus.applied
34
+ pluginsCompatible = expected.pluginMigrations === pluginStatus.expected && pluginStatus.applied === pluginStatus.expected
35
+ }
36
+ const compatible = pluginsCompatible && applied.revision === expected.revision && applied.coreVersion === expected.coreVersion && applied.migrations === expected.migrations
37
+ && (!config || (config.revision === expected.revision && CORE_VERSION === expected.coreVersion))
38
+ return { enabled: true, compatible, expected, applied }
39
+ } catch {
40
+ // A missing ledger/binding or unreadable DB fails closed, without leaking database exceptions.
41
+ return { enabled: true, compatible: false, expected, applied: null }
42
+ }
43
+ }
@@ -0,0 +1,3 @@
1
+ import type { Scope } from './identity'
2
+ /** Core-private credential provenance, preserved only by trusted context/live-scope builders. */
3
+ export const scopeOperations = new WeakMap<Scope, { operations: string[] | null }>()
@@ -0,0 +1 @@
1
+ export const SESSION_COOKIE = '__Host-workbase.session'
package/src/types.ts ADDED
@@ -0,0 +1,30 @@
1
+ import type { AuditOutboxRow } from './kernel/audit-port'
2
+ import type { WorkbasePlugin, PluginMigration } from './kernel/plugin'
3
+ import type { WorkflowRegistry } from './workflow-runtime'
4
+ import type { SchemaEnvironment } from './schema-compatibility'
5
+ import type { Context, Hono } from 'hono'
6
+ import type { InstanceConfig } from './config'
7
+ import type { CommandRegistry } from './commands'
8
+ export interface EmailEnvironment { EMAIL?: SendEmail; EMAIL_FROM?: string }
9
+ export interface IdentitySettings {
10
+ baseURL: string; secret: string
11
+ localPassword?: boolean
12
+ oidc?: { issuer: string; clientId: string; clientSecret: string }
13
+ }
14
+ export interface RuntimeEnv extends SchemaEnvironment, EmailEnvironment { CONFIG_EDITOR_URL?: string; CONFIG_EDITOR_TOKEN?: string; ASSETS?: Fetcher; BUILD_SHA?: string; BUILD_AT?: string; AUTH_BASE_URL?: string; BETTER_AUTH_SECRET?: string; OIDC_ISSUER?: string; OIDC_CLIENT_ID?: string; OIDC_CLIENT_SECRET?: string; DEV_LOCAL_IDENTITY?: string; IDENTITY?: IdentitySettings; DB: D1Database; AUDIT_KV: KVNamespace; EVENTS_QUEUE?: Queue<AuditOutboxRow>; INTERNAL_TOKEN?: string; WEBHOOK_URL?: string; WEBHOOK_EVENTS?: string; WEBHOOK_ALLOWED_HOSTS?: string; WEBHOOK_SERVICE?: Fetcher }
15
+ export type { ResolvedActor } from './authorization'
16
+ import type { ResolvedActor } from './authorization'
17
+ export type { Actor, Scope } from './identity'
18
+ import type { Scope } from './identity'
19
+ export type AppEnv = { Variables: { scope: Scope; resolvedActor: ResolvedActor; userId: string; correlationId: string } }
20
+ export type App = Hono<AppEnv>
21
+ export type AppContext = Context<AppEnv>
22
+ export interface RuntimeOptions {
23
+ plugins?: readonly WorkbasePlugin[]
24
+ /** Explicit development bypass; never inferred from environment. */
25
+ authorization?: 'trust'
26
+ migrations?: readonly PluginMigration[]
27
+ workflows?: WorkflowRegistry
28
+ commands?: CommandRegistry
29
+ extend?: (app: App, config: InstanceConfig, env: RuntimeEnv) => void
30
+ }
@@ -0,0 +1,14 @@
1
+ import type { RuntimeEnv } from './types'
2
+ import { publicConsoleResponse } from './console'
3
+ import { timed, timeRequest } from './request-timing'
4
+
5
+ type Worker = { fetch(request: Request, env: RuntimeEnv, ctx?: ExecutionContext): Response | Promise<Response> }
6
+ /** Keep public assets independent of deferred config/auth/plugin initialization. */
7
+ export function workerFetch(load: () => Promise<Worker>) {
8
+ return (request: Request, env: RuntimeEnv, ctx?: ExecutionContext) => timeRequest(async () => {
9
+ const response = await timed('handler', () => publicConsoleResponse(request, env))
10
+ if (response) return response
11
+ const worker = await timed('bootstrap', load)
12
+ return worker.fetch(request, env, ctx)
13
+ })
14
+ }
@@ -0,0 +1,156 @@
1
+ import { kernelFor } from './kernel/registry'
2
+ import { z } from 'zod'
3
+ import { coreExecutionContext } from './execution/context'
4
+ import { D1AtomicStore, D1AtomicReader } from './execution/d1'
5
+ import type { InstanceConfig } from './config'
6
+ import type { App, AppContext, RuntimeEnv } from './types'
7
+ import { ApiError } from './errors'
8
+ import { requireScope } from './authorization'
9
+ import { atomicPermission } from './execution/permissions'
10
+ import { authorizeReceiptRows, needsPolicyReceipt } from './execution/policy-receipts'
11
+ import type { WorkflowDefinition } from './execution/workflow'
12
+ import { startWorkflow } from './execution/workflow'
13
+ import { D1WorkflowRuntime, workflowSignature, type WorkflowRegistry } from './workflow-runtime'
14
+ export function workflowRoutes(app: App, config: InstanceConfig, env: RuntimeEnv, definitions: WorkflowRegistry) {
15
+ const runtime = new D1WorkflowRuntime(env, config, definitions)
16
+ const context = (scope: Awaited<ReturnType<typeof requireScope>>, key?: string) => coreExecutionContext(config, scope, new D1AtomicStore(env.DB, { env, config }), new D1AtomicReader(env.DB), key, runtime)
17
+ app.post('/internal/workflows/run', async c => c.json(await runtime.tick()))
18
+ const scopeFor = async (c: AppContext, name?: string) => {
19
+ const scope = await requireScope(await kernelFor(config).requireActor(c.req.raw, env), c.req.header('X-Organization-Id') ?? '', config, c.get('correlationId'), name)
20
+ c.set('scope', scope)
21
+ return scope
22
+ }
23
+ const reader = async (c: AppContext) => {
24
+ const actor = await kernelFor(config).requireActor(c.req.raw, env)
25
+ const organizationId = c.req.header('X-Organization-Id') ?? ''
26
+ c.set('scope', await requireScope(actor, organizationId, config, c.get('correlationId')))
27
+ return workflowReader(config, env, definitions, actor, organizationId, c.get('correlationId'))
28
+ }
29
+ const lookup = async (id: string, org: string) => lookupWorkflow(env, id, org)
30
+ app.get('/workflows', async c => c.json({ data: await (await reader(c)).list(c.req.query('status')) }))
31
+ app.get('/workflows/:id', async c => c.json(await (await reader(c)).detail(c.req.param('id'))))
32
+ app.post('/workflows/:id/resume', async c => {
33
+ const scope = await scopeFor(c)
34
+ if (scope.actor.type !== 'user' || scope.role !== 'owner') throw new ApiError(403, 'owner_required')
35
+ kernelFor(config).resourcePermission(scope, 'workflows.resume')
36
+ await lookup(c.req.param('id'), scope.organizationId)
37
+ const status = await runtime.resume(c.req.param('id'), context(scope))
38
+ return c.json({ id: c.req.param('id'), status }, 202)
39
+ })
40
+ app.post('/workflows/:id/cancel', async c => {
41
+ const scope = await scopeFor(c)
42
+ if (scope.actor.type !== 'user' || scope.role !== 'owner') throw new ApiError(403, 'owner_required')
43
+ kernelFor(config).resourcePermission(scope, 'workflows.cancel')
44
+ await lookup(c.req.param('id'), scope.organizationId)
45
+ const status = await runtime.cancel(c.req.param('id'), context(scope))
46
+ return c.json({ id: c.req.param('id'), status }, status === 'cancelled' ? 200 : 202)
47
+ })
48
+ // Names may include slashes, like commands; register after resume and GET routes.
49
+ app.post('/workflows/*', async c => {
50
+ const name = c.req.path.slice('/workflows/'.length)
51
+ const definition = definitions.get(name)
52
+ if (!definition) throw new ApiError(404, 'workflow_not_found')
53
+ const scope = await (await reader(c)).startScope(definition)
54
+ const { idempotencyKey, ...input } = z.record(z.string(), z.unknown()).parse(await c.req.json())
55
+ const bodyKey = z.string().min(1).max(128).optional().parse(idempotencyKey)
56
+ const headerKey = c.req.header('Idempotency-Key')
57
+ if (headerKey && bodyKey && headerKey !== bodyKey) throw new ApiError(422, 'idempotency_payload_mismatch')
58
+ const handle = await startWorkflow(definition, input, context(scope, headerKey ?? bodyKey))
59
+ const row = await lookup(handle.id, scope.organizationId)
60
+ return c.json({ id: handle.id, status: row.status }, 202)
61
+ })
62
+ }
63
+
64
+ /** Shared authorized reads. Browser-only projections add safe metadata, never stored input or credentials. */
65
+ export function workflowReader(config: InstanceConfig, env: RuntimeEnv, definitions: WorkflowRegistry,
66
+ actor: import('./types').ResolvedActor, organizationId: string, correlationId: string) {
67
+ const scopeFor = (name?: string) => requireScope(actor, organizationId, config, correlationId, name)
68
+ const readScope = async () => {
69
+ const scope = await scopeFor()
70
+ kernelFor(config).resourcePermission(scope, 'workflows.read')
71
+ return scope
72
+ }
73
+ const startScope = async (definition: WorkflowDefinition<any>) => {
74
+ let scope = await scopeFor()
75
+ for (const step of definition.steps!) { scope = await scopeFor(step.operation.name); atomicPermission(config, scope, step.operation) }
76
+ return scope
77
+ }
78
+ const authorize = async (row: Record<string, any>) => {
79
+ const scope = await readScope()
80
+ if (scope.actor.type === 'user' && scope.role === 'owner') return
81
+ const definition = definitions.get(row.definition_name)
82
+ if (!definition || definition.version !== row.definition_version || workflowSignature(definition) !== row.definition_signature) throw new ApiError(403, 'workflow_forbidden')
83
+ await startScope(definition)
84
+ }
85
+ const visible = async (row: Record<string, any>) => {
86
+ try { await authorize(row); return true } catch (error) { if (error instanceof ApiError && error.status === 403) return false; throw error }
87
+ }
88
+ return {
89
+ startScope,
90
+ async catalog() {
91
+ const available = []
92
+ for (const definition of definitions.values()) {
93
+ try { await startScope(definition); available.push(definition) } catch (error) { if (!(error instanceof ApiError) || error.status !== 403) throw error }
94
+ }
95
+ return available
96
+ },
97
+ async counts() {
98
+ await readScope()
99
+ const rows = await env.DB.prepare('SELECT definition_name,definition_version,definition_signature,status,count(*) AS n FROM workflow_runs WHERE organization_id=? GROUP BY definition_name,definition_version,definition_signature,status').bind(organizationId).all<Record<string, any>>()
100
+ const counts: Record<string, number> = {}
101
+ for (const row of rows.results) if (await visible(row)) counts[row.status] = (counts[row.status] ?? 0) + row.n
102
+ return counts
103
+ },
104
+ async list(status?: string, browser = false) {
105
+ await readScope()
106
+ const rows = await env.DB.prepare(`SELECT id,definition_name,definition_version,definition_signature,status,last_error_code,created_at,updated_at${browser ? ',actor_type' : ''} FROM workflow_runs WHERE organization_id=?${status ? ' AND status=?' : ''} ORDER BY created_at DESC,id LIMIT 100`).bind(organizationId, ...(status ? [status] : [])).all<Record<string, any>>()
107
+ const data = []
108
+ for (const row of rows.results) if (await visible(row)) { const { definition_signature, ...item } = row; data.push(item) }
109
+ return data
110
+ },
111
+ async detail(id: string, browser = false): Promise<Record<string, any>> {
112
+ const scope = await readScope()
113
+ const row = await lookupWorkflow(env, id, organizationId)
114
+ await authorize(row)
115
+ const { result_json, definition_signature, ...rest } = row
116
+ let result = result_json ? JSON.parse(result_json) : null
117
+ if (result) {
118
+ try {
119
+ const kernel = kernelFor(config)
120
+ const definition = definitions.get(row.definition_name)
121
+ if (!definition || definition.version !== row.definition_version || workflowSignature(definition) !== definition_signature) throw new ApiError(403, 'workflow_forbidden')
122
+ for (const step of definition.steps!) {
123
+ const entities = [...('entity' in step.operation.permission ? [step.operation.permission.entity] : []), ...(step.operation.additionalPermissions ?? []).map(grant => grant.entity)]
124
+ if (entities.some(entity => !kernel.can(scope, entity, 'read'))) throw new ApiError(403, 'policy_violation')
125
+ }
126
+ const atomicSteps = definition.steps!.filter(step => step.kind !== 'external')
127
+ const required = needsPolicyReceipt(kernel)
128
+ if (required && !atomicSteps.length) throw new ApiError(403, 'policy_violation')
129
+ for (const step of atomicSteps) {
130
+ const rows = result[step.id]?.__workbase_policy?.rows
131
+ // Historical/read-only results have no row evidence; only unrestricted
132
+ // read policies can authorize those opaque snapshots.
133
+ if (!rows?.length) { if (required || rows) throw new ApiError(403, 'policy_violation'); continue }
134
+ await authorizeReceiptRows(kernel, scope, new D1AtomicReader(env.DB), rows, true)
135
+ }
136
+ } catch (error) {
137
+ if (!(error instanceof ApiError) || error.status !== 403) throw error
138
+ result = null
139
+ }
140
+ }
141
+ // Private effect receipts may also survive crash recovery in old runs.
142
+ if (result) result = Object.fromEntries(Object.entries(result).map(([key, value]) => {
143
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return [key, value]
144
+ const { __workbase_policy, ...publicValue } = value as Record<string, unknown>
145
+ return [key, publicValue]
146
+ }))
147
+ const steps = await env.DB.prepare(`SELECT step_id,status,attempts,compensation_attempts,next_attempt_at,last_error_code${browser ? ',deadline_at,compensation_deadline_at' : ''} FROM workflow_steps WHERE run_id=? ORDER BY position`).bind(id).all()
148
+ return { ...rest, result, steps: steps.results }
149
+ },
150
+ }
151
+ }
152
+ async function lookupWorkflow(env: RuntimeEnv, id: string, organizationId: string) {
153
+ const row = await env.DB.prepare('SELECT id,organization_id,definition_name,definition_version,definition_signature,status,result_json,last_error_code,created_at,updated_at FROM workflow_runs WHERE id=? AND organization_id=?').bind(id, organizationId).first<Record<string, any>>()
154
+ if (!row) throw new ApiError(403, 'workflow_forbidden')
155
+ return row
156
+ }
@@ -0,0 +1,327 @@
1
+ import { outboxInsert } from './execution/outbox'
2
+ import { kernelFor } from './kernel/registry'
3
+ import { z } from 'zod'
4
+ import type { InstanceConfig } from './config'
5
+ import type { RuntimeEnv, Scope } from './types'
6
+ import { ApiError } from './errors'
7
+ import { makeEvent } from './audit-event'
8
+ import { requestHash } from './idempotency'
9
+ import { ulid } from './crypto'
10
+ import { coreExecutionContext, assertLivePermission, infrastructure, holdReleaseContext } from './execution/context'
11
+ import { D1AtomicStore, D1AtomicReader } from './execution/d1'
12
+ import { PermissionRevoked } from './execution/errors'
13
+ import type { ExecutionContext, GuardedStatement, AtomicStore } from './execution/types'
14
+ import type { WorkflowDefinition, WorkflowRuntime, WorkflowStatus, WorkflowStep } from './execution/workflow'
15
+ export type WorkflowRegistry = ReadonlyMap<string, WorkflowDefinition<any>>
16
+ interface Run {
17
+ id: string; organization_id: string; actor_id: string; actor_type: 'user' | 'agent'; token_id: string | null
18
+ definition_name: string; definition_version: string; definition_signature: string; input_json: string
19
+ cancel_actor_id: string | null; status: WorkflowStatus; resume_status: WorkflowStatus | null; correlation_id: string; lease_token: string; last_error_code: string | null
20
+ }
21
+ interface Step {
22
+ step_id: string; status: string; attempts: number; compensation_attempts: number; deadline_at: number | null
23
+ compensation_deadline_at: number | null; compensation_checkpoint_json: string | null; last_error_code: string | null; checkpoint_json: string | null; next_attempt_at: number
24
+ }
25
+ function publicCheckpoint(serialized: string) {
26
+ const value = JSON.parse(serialized)
27
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return value
28
+ const { __workbase_policy, ...result } = value
29
+ return result
30
+ }
31
+ const active = "'pending','running','waiting_external','compensating'"
32
+ export function createWorkflowRegistry(definitions: readonly WorkflowDefinition<any>[]): WorkflowRegistry {
33
+ const registry = new Map<string, WorkflowDefinition<any>>()
34
+ for (const definition of definitions) {
35
+ if (!definition.steps?.length || definition.steps.length > 20 || !/^[a-z][a-z0-9_-]*(\/[a-z][a-z0-9_-]*)+$/.test(definition.name) || !definition.version || definition.version.length > 100 || registry.has(definition.name)) throw new Error('invalid_workflow_definition')
36
+ const ids = new Set<string>()
37
+ for (const step of definition.steps) {
38
+ const p = step.policy
39
+ if (step.id.length > 64 || !/^[a-z][a-z0-9_]*$/.test(step.id) || ids.has(step.id) || typeof step.sideEffect !== 'boolean' || (step.sideEffect && !step.compensate)
40
+ || !Number.isInteger(p.maxAttempts) || p.maxAttempts < 1 || p.maxAttempts > 10 || p.timeoutMs < 1 || p.timeoutMs > 10000
41
+ || ![p.timeoutMs, p.deadlineMs, p.backoffMs].every(Number.isFinite) || p.deadlineMs < p.timeoutMs || p.backoffMs < 0) throw new Error('invalid_workflow_step')
42
+ if (step.holdsCapacity && (!step.sideEffect || !step.compensate || step.kind === 'external' || definition.steps.filter(s => s.holdsCapacity).length !== 1)) throw new Error('invalid_workflow_hold_step')
43
+ ids.add(step.id)
44
+ }
45
+ registry.set(definition.name, definition)
46
+ }
47
+ return registry
48
+ }
49
+ export function workflowSignature(definition: WorkflowDefinition<any>) {
50
+ // Version owners must bump for semantic code changes; this also detects incompatible structural edits.
51
+ return JSON.stringify(definition.steps?.map(s => ({ id: s.id, operation: { name: s.operation.name, permission: s.operation.permission, additionalPermissions: s.operation.additionalPermissions }, kind: s.kind ?? 'atomic', policy: s.policy, sideEffect: !!s.sideEffect, compensation: s.compensate ? { name: s.compensate.operation.name, permission: s.compensate.operation.permission, additionalPermissions: s.compensate.operation.additionalPermissions } : null })))
52
+ }
53
+ export class D1WorkflowRuntime implements WorkflowRuntime {
54
+ constructor(readonly env: RuntimeEnv, readonly config: InstanceConfig, readonly definitions: WorkflowRegistry) { kernelFor(config) }
55
+ #context(scope: Scope, key?: string) {
56
+ return coreExecutionContext(this.config, scope, new D1AtomicStore(this.env.DB, { env: this.env, config: this.config }), new D1AtomicReader(this.env.DB), key, this)
57
+ }
58
+ async start<S extends z.ZodType>(definition: WorkflowDefinition<S>, input: z.output<S>, context: ExecutionContext) {
59
+ if (infrastructure(context).workflowRuntime !== this || context.config.id !== this.config.id || context.config.revision !== this.config.revision) throw new ApiError(403, 'workflow_context_mismatch')
60
+ if (this.definitions.get(definition.name) !== definition) throw new ApiError(404, 'workflow_not_found')
61
+ for (const step of definition.steps!) await assertLivePermission(context, step.operation)
62
+ z.string().min(1).max(128).parse(context.idempotencyKey)
63
+ const operation = `workflow:${definition.name}:${definition.version}`
64
+ const hash = await requestHash(operation, input)
65
+ const replay = async () => {
66
+ const row = await this.env.DB.prepare('SELECT command,request_hash,response_json FROM idempotency_keys WHERE organization_id=? AND key=?').bind(context.scope.organizationId, context.idempotencyKey!).first<{ command: string; request_hash: string; response_json: string }>()
67
+ if (!row) return null
68
+ if (row.command !== operation || row.request_hash !== hash) throw new ApiError(422, 'idempotency_payload_mismatch')
69
+ return JSON.parse(row.response_json) as { id: string }
70
+ }
71
+ const previous = await replay(); if (previous) return previous
72
+ const id = ulid(); const now = new Date().toISOString(); const scope = context.scope
73
+ const statements: GuardedStatement[] = [{
74
+ sql: 'INSERT INTO workflow_runs (id,organization_id,actor_id,actor_type,token_id,definition_name,definition_version,definition_signature,input_json,status,correlation_id,next_attempt_at,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
75
+ bindings: [id, scope.organizationId, scope.actor.id, scope.actor.type, scope.actor.tokenId ?? null, definition.name, definition.version, workflowSignature(definition), JSON.stringify(input), 'pending', scope.correlationId, Date.now(), now, now], expectRows: 1,
76
+ }, ...definition.steps!.map((s, i) => ({ sql: "INSERT INTO workflow_steps (run_id,step_id,position,status) VALUES (?,?,?,'pending')", bindings: [id, s.id, i], expectRows: 1 as const })), this.audit(scope, id, 'workflow.started'), {
77
+ sql: 'INSERT INTO idempotency_keys (organization_id,key,command,response_json,request_hash) VALUES (?,?,?,?,?)',
78
+ bindings: [scope.organizationId, context.idempotencyKey!, operation, JSON.stringify({ id }), hash], expectRows: 1,
79
+ }]
80
+ try { await this.submit(statements) } catch (error) { const winner = await replay(); if (winner) return winner; throw error }
81
+ return { id }
82
+ }
83
+ private submit(statements: GuardedStatement[]) {
84
+ return new D1AtomicStore(this.env.DB, { env: this.env, config: this.config }).run({ runId: crypto.randomUUID(), rules: [{ name: 'workflow_state', statements }] })
85
+ }
86
+ private audit(scope: Scope, id: string, code: string, stepId?: string, errorCode?: string): GuardedStatement {
87
+ const event = makeEvent(this.config, scope, code, 'workflows', id, {}, {}, { run_id: id, ...(stepId ? { step_id: stepId } : {}), ...(errorCode ? { code: errorCode } : {}) })
88
+ return outboxInsert(event)
89
+ }
90
+ private scope(run: Run): Scope {
91
+ if (run.cancel_actor_id) return { organizationId: run.organization_id, actor: { type: 'user', id: run.cancel_actor_id }, role: '', correlationId: run.correlation_id }
92
+ return { organizationId: run.organization_id, actor: { type: run.actor_type, id: run.actor_id, ...(run.token_id ? { tokenId: run.token_id } : {}) }, role: '', correlationId: run.correlation_id }
93
+ }
94
+ private fence(run: Run, now: number): GuardedStatement {
95
+ // D1's clock also rejects a write delayed in transit beyond its lease.
96
+ return { sql: `UPDATE workflow_runs SET updated_at=? WHERE id=? AND lease_token=? AND lease_until>max(?,CAST((julianday('now')-2440587.5)*86400000 AS INTEGER))${run.cancel_actor_id ? " AND EXISTS(SELECT 1 FROM memberships WHERE user_id=? AND organization_id=workflow_runs.organization_id AND role='owner')" : ''}`, bindings: [new Date(now).toISOString(), run.id, run.lease_token, now, ...(run.cancel_actor_id ? [run.cancel_actor_id] : [])], expectRows: 1 }
97
+ }
98
+ private async transition(run: Run, now: number, status: WorkflowStatus, event: string, code: string | null = null, statements: GuardedStatement[] = [], stepId?: string, nextAt = now) {
99
+ await this.submit([this.fence(status === 'needs_attention' ? { ...run, cancel_actor_id: null } : run, now), ...statements, {
100
+ sql: 'UPDATE workflow_runs SET status=?,resume_status=?,last_error_code=?,next_attempt_at=?,lease_until=NULL,lease_token=NULL WHERE id=?',
101
+ bindings: [status, status === 'needs_attention' ? (run.status === 'compensating' ? 'compensating' : 'running') : null, code, nextAt, run.id], expectRows: 1,
102
+ }, this.audit(this.scope(run), run.id, event, stepId, code ?? undefined)])
103
+ }
104
+ async resume(id: string, context: ExecutionContext) {
105
+ if (infrastructure(context).workflowRuntime !== this || context.config.id !== this.config.id || context.config.revision !== this.config.revision) throw new ApiError(403, 'workflow_context_mismatch')
106
+ kernelFor(this.config).resourcePermission(context.scope, 'workflows.resume')
107
+ // The resumer is an authenticated current owner, independently of the saved actor.
108
+ const member = context.scope.actor.type === 'user' ? await this.env.DB.prepare('SELECT role FROM memberships WHERE user_id=? AND organization_id=?').bind(context.scope.actor.id, context.scope.organizationId).first<{ role: string }>() : null
109
+ if (member?.role !== 'owner') throw new ApiError(403, 'owner_required')
110
+ const organizationId = context.scope.organizationId
111
+ const run = await this.env.DB.prepare('SELECT * FROM workflow_runs WHERE id=? AND organization_id=?').bind(id, organizationId).first<Run>()
112
+ if (!run) throw new ApiError(403, 'workflow_forbidden')
113
+ if (run.status !== 'needs_attention') throw new ApiError(409, 'workflow_not_paused')
114
+ const definition = this.definitions.get(run.definition_name)
115
+ if (!definition || definition.version !== run.definition_version || workflowSignature(definition) !== run.definition_signature) {
116
+ await this.submit([{ sql: "UPDATE workflow_runs SET last_error_code='workflow.definition_mismatch' WHERE id=? AND status='needs_attention'", bindings: [id], expectRows: 1 }, this.audit(this.scope(run), id, 'workflow.needs_attention', undefined, 'workflow.definition_mismatch')])
117
+ throw new ApiError(409, 'workflow.definition_mismatch')
118
+ }
119
+ const saved = (await this.env.DB.prepare('SELECT * FROM workflow_steps WHERE run_id=? ORDER BY position').bind(id).all<Step>()).results
120
+ for (const [index, step] of definition.steps!.entries()) {
121
+ const operation = run.resume_status === 'compensating'
122
+ ? (['completed', 'executing', 'failed'].includes(saved[index].status) ? step.compensate?.operation : undefined)
123
+ : (saved[index].status !== 'completed' ? step.operation : undefined)
124
+ if (!operation) continue
125
+ await assertLivePermission(context, operation)
126
+ await assertLivePermission(this.#context(this.scope(run)), operation)
127
+ }
128
+ // Resume does not reset retry/deadline budgets. A failed compensation gets a new, explicit owner-authorized budget.
129
+ const now = Date.now()
130
+ await this.submit([{
131
+ sql: "UPDATE workflow_runs SET status=coalesce(resume_status,'running'),last_error_code=NULL,next_attempt_at=?,updated_at=? WHERE id=? AND organization_id=? AND status='needs_attention' AND (lease_until IS NULL OR lease_until<=?) AND EXISTS(SELECT 1 FROM memberships WHERE user_id=? AND organization_id=? AND role='owner')",
132
+ bindings: [now, new Date(now).toISOString(), id, organizationId, now, context.scope.actor.id, organizationId], expectRows: 1,
133
+ }, ...(run.resume_status === 'compensating' ? [{ sql: "UPDATE workflow_steps SET compensation_attempts=0,compensation_deadline_at=NULL,next_attempt_at=0 WHERE run_id=? AND status<>'compensated'", bindings: [id] }] : []), this.audit(context.scope, id, 'workflow.resumed')])
134
+ return run.resume_status ?? 'running'
135
+ }
136
+ async cancel(id: string, context: ExecutionContext) {
137
+ if (infrastructure(context).workflowRuntime !== this || context.config.id !== this.config.id || context.config.revision !== this.config.revision) throw new ApiError(403, 'workflow_context_mismatch')
138
+ kernelFor(this.config).resourcePermission(context.scope, 'workflows.cancel')
139
+ const scope = context.scope
140
+ const member = scope.actor.type === 'user' ? await this.env.DB.prepare('SELECT role FROM memberships WHERE user_id=? AND organization_id=?').bind(scope.actor.id, scope.organizationId).first<{ role: string }>() : null
141
+ if (member?.role !== 'owner') throw new ApiError(403, 'owner_required')
142
+ const saved = await this.env.DB.prepare('SELECT * FROM workflow_runs WHERE id=? AND organization_id=?').bind(id, scope.organizationId).first<Run>()
143
+ if (!saved) throw new ApiError(403, 'workflow_forbidden')
144
+ if (saved.status === 'cancelled') return 'cancelled'
145
+ if (['completed', 'compensated'].includes(saved.status)) throw new ApiError(409, 'workflow_terminal')
146
+ const definition = this.definitions.get(saved.definition_name)
147
+ if (!definition || definition.version !== saved.definition_version || workflowSignature(definition) !== saved.definition_signature) throw new ApiError(409, 'workflow.definition_mismatch')
148
+ // Independently authorize the owner; never test or borrow the saved token.
149
+ for (const step of definition.steps!) if (step.compensate) await assertLivePermission(context, step.compensate.operation)
150
+ const now = Date.now()
151
+ await this.submit([{
152
+ sql: "UPDATE workflow_runs SET status='compensating',cancel_actor_id=?,resume_status=NULL,last_error_code=NULL,next_attempt_at=?,lease_token=NULL,lease_until=NULL WHERE id=? AND organization_id=? AND status NOT IN ('completed','compensated','cancelled') AND (lease_until IS NULL OR lease_until<=?) AND EXISTS(SELECT 1 FROM memberships WHERE user_id=? AND organization_id=? AND role='owner')",
153
+ bindings: [scope.actor.id, now, id, scope.organizationId, now, scope.actor.id, scope.organizationId], expectRows: 1,
154
+ }, { sql: "UPDATE workflow_steps SET compensation_attempts=0,compensation_deadline_at=NULL,next_attempt_at=0 WHERE run_id=? AND status<>'compensated'", bindings: [id] }, this.audit(scope, id, 'workflow.cancellation_requested')])
155
+ // Drain a bounded reverse pass for the HTTP caller. Failed attempts retain their
156
+ // durable budgets/backoff and the cron continues under this owner's live scope.
157
+ for (let i = 0; i <= definition.steps!.length; i++) {
158
+ const time = Date.now()
159
+ const run = await this.env.DB.prepare("UPDATE workflow_runs SET lease_token=?,lease_until=? WHERE id=? AND status='compensating' AND next_attempt_at<=? AND (lease_until IS NULL OR lease_until<=?) RETURNING *").bind(crypto.randomUUID(), time + 60000, id, time, time).first<Run>()
160
+ if (!run) break
161
+ await this.advance(run, time)
162
+ }
163
+ return (await this.env.DB.prepare('SELECT status FROM workflow_runs WHERE id=?').bind(id).first<string>('status'))!
164
+ }
165
+ private async sweepHolds(scanNow: number, limit: number) {
166
+ const started = Date.now(); const time = () => scanNow + Date.now() - started
167
+ const rows = await this.env.DB.prepare("SELECT r.id FROM workflow_holds h JOIN workflow_runs r ON r.id=h.run_id AND r.organization_id=h.organization_id WHERE h.status='held' AND h.expires_at<=? AND r.status IN ('needs_attention','failed','compensating') AND (r.lease_until IS NULL OR r.lease_until<=?) ORDER BY h.expires_at,r.id LIMIT ?").bind(new Date(scanNow).toISOString(), scanNow, limit).all<{ id: string }>()
168
+ let released = 0
169
+ for (const row of rows.results) {
170
+ const run = await this.env.DB.prepare("UPDATE workflow_runs SET lease_token=?,lease_until=? WHERE id=? AND status IN ('needs_attention','failed','compensating') AND (lease_until IS NULL OR lease_until<=?) AND EXISTS(SELECT 1 FROM workflow_holds WHERE run_id=workflow_runs.id AND organization_id=workflow_runs.organization_id AND status='held' AND expires_at<=?) RETURNING *").bind(crypto.randomUUID(), time() + 60000, row.id, time(), new Date(time()).toISOString()).first<Run>()
171
+ if (!run) continue
172
+ try {
173
+ const definition = this.definitions.get(run.definition_name)
174
+ if (!definition || definition.version !== run.definition_version || workflowSignature(definition) !== run.definition_signature) continue
175
+ const step = definition.steps!.find(s => s.holdsCapacity && s.kind !== 'external' && s.compensate)
176
+ if (!step) continue
177
+ const steps = (await this.env.DB.prepare('SELECT * FROM workflow_steps WHERE run_id=? ORDER BY position').bind(run.id).all<Step>()).results
178
+ if (!steps.some(s => s.step_id === step.id && ['completed', 'executing', 'failed'].includes(s.status))) continue
179
+ const scope: Scope = { organizationId: run.organization_id, actor: { type: 'service', id: 'system' }, role: 'SYSTEM', correlationId: run.correlation_id }
180
+ const base = new D1AtomicStore(this.env.DB, { env: this.env, config: this.config })
181
+ const store: AtomicStore = { run: plan => base.run({ ...plan, rules: [
182
+ { name: 'expired_hold_lease', statements: [this.fence({ ...run, cancel_actor_id: null }, time()), {
183
+ sql: "UPDATE workflow_holds SET status=status WHERE run_id=? AND organization_id=? AND status='held' AND expires_at<=?", bindings: [run.id, run.organization_id, new Date(time()).toISOString()], expectRows: 1,
184
+ }] }, ...plan.rules, { name: 'expired_hold_audit', statements: [{
185
+ sql: "UPDATE workflow_holds SET status=status WHERE run_id=? AND organization_id=? AND status='released'", bindings: [run.id, run.organization_id], expectRows: 1,
186
+ }, this.audit(scope, run.id, 'workflow.hold_expired', step.id)] },
187
+ ] }) }
188
+ const context = holdReleaseContext(coreExecutionContext(this.config, scope, store, new D1AtomicReader(this.env.DB), `${run.id}:${step.id}:undo`), step.compensate!.operation)
189
+ await assertLivePermission(context, step.compensate!.operation)
190
+ let timer: ReturnType<typeof setTimeout> | undefined
191
+ const controller = new AbortController()
192
+ await Promise.race([step.compensate!.run(Object.freeze({ context, runId: run.id, input: JSON.parse(run.input_json), checkpoints: Object.fromEntries(steps.filter(s => s.checkpoint_json).map(s => [s.step_id, publicCheckpoint(s.checkpoint_json!)])), signal: controller.signal })), new Promise<never>((_, reject) => {
193
+ timer = setTimeout(() => { controller.abort(); reject(new ApiError(408, 'workflow.external_timeout')) }, step.policy.timeoutMs)
194
+ })]).finally(() => clearTimeout(timer))
195
+ if (await this.env.DB.prepare("SELECT 1 FROM workflow_holds h JOIN workflow_runs r ON r.id=h.run_id WHERE h.run_id=? AND h.status='released' AND r.lease_token=?").bind(run.id, run.lease_token).first()) released++
196
+ } catch (error) {
197
+ const owner = await this.env.DB.prepare('SELECT lease_token FROM workflow_runs WHERE id=?').bind(run.id).first<{ lease_token: string | null }>()
198
+ if (owner?.lease_token === run.lease_token) throw error
199
+ } finally {
200
+ await this.env.DB.prepare('UPDATE workflow_runs SET lease_token=NULL,lease_until=NULL WHERE id=? AND lease_token=?').bind(run.id, run.lease_token).run()
201
+ }
202
+ }
203
+ return released
204
+ }
205
+ async tick(options: { now?: number; limit?: number } = {}) {
206
+ const started = Date.now(); const scanNow = options.now ?? started
207
+ const limit = Math.max(0, Math.min(Math.trunc(options.limit ?? 20), 100))
208
+ const released = await this.sweepHolds(scanNow, limit)
209
+ const rows = await this.env.DB.prepare(`SELECT id FROM workflow_runs WHERE status IN (${active}) AND next_attempt_at<=? AND (lease_until IS NULL OR lease_until<=?) ORDER BY next_attempt_at,id LIMIT ?`).bind(scanNow, scanNow, limit).all<{ id: string }>()
210
+ let claimed = 0
211
+ for (const row of rows.results) {
212
+ const now = scanNow + Date.now() - started
213
+ const run = await this.env.DB.prepare(`UPDATE workflow_runs SET lease_token=?,lease_until=? WHERE id=? AND status IN (${active}) AND next_attempt_at<=? AND (lease_until IS NULL OR lease_until<=?) RETURNING *`).bind(crypto.randomUUID(), now + 60000, row.id, now, now).first<Run>()
214
+ if (!run) continue
215
+ claimed++
216
+ try { await this.advance(run, scanNow + Date.now() - started) }
217
+ catch (error) {
218
+ // Losing a lease is an expected race. Other storage failures leave the lease
219
+ // for crash recovery and remain visible to the caller/cron metrics.
220
+ const owner = await this.env.DB.prepare('SELECT lease_token FROM workflow_runs WHERE id=?').bind(run.id).first<{ lease_token: string | null }>()
221
+ if (owner?.lease_token === run.lease_token) throw error
222
+ }
223
+ }
224
+ return { claimed, released }
225
+ }
226
+ private async advance(run: Run, now: number) {
227
+ // Include permission/checkpoint reads in elapsed time, not only the effect.
228
+ const started = Date.now(); const optionsNow = () => now + Date.now() - started
229
+ const definition = this.definitions.get(run.definition_name)
230
+ if (!definition || definition.version !== run.definition_version || workflowSignature(definition) !== run.definition_signature) {
231
+ await this.transition(run, optionsNow(), 'needs_attention', 'workflow.needs_attention', 'workflow.definition_mismatch'); return
232
+ }
233
+ const rows = (await this.env.DB.prepare('SELECT * FROM workflow_steps WHERE run_id=? ORDER BY position').bind(run.id).all<Step>()).results
234
+ if (run.cancel_actor_id) {
235
+ const owner = await this.env.DB.prepare("SELECT 1 FROM memberships WHERE user_id=? AND organization_id=? AND role='owner'").bind(run.cancel_actor_id, run.organization_id).first()
236
+ if (!owner) { await this.transition(run, optionsNow(), 'needs_attention', 'workflow.needs_attention', 'permission_revoked'); return }
237
+ }
238
+ const compensating = run.status === 'compensating'
239
+ const index = compensating ? rows.findLastIndex(s => ['completed', 'executing', 'failed'].includes(s.status) && !!definition.steps!.find(d => d.id === s.step_id)?.compensate) : rows.findIndex(s => s.status !== 'completed')
240
+ if (index === -1) {
241
+ await this.transition(run, optionsNow(), compensating ? (run.cancel_actor_id ? 'cancelled' : 'compensated') : 'completed', compensating ? (run.cancel_actor_id ? 'workflow.cancelled' : 'workflow.compensated') : 'workflow.completed', compensating ? run.last_error_code : null,
242
+ compensating ? [] : [{ sql: 'UPDATE workflow_runs SET result_json=? WHERE id=?', bindings: [JSON.stringify(Object.fromEntries(rows.map(s => [s.step_id, s.checkpoint_json ? JSON.parse(s.checkpoint_json) : null]))), run.id] }]); return
243
+ }
244
+ const step = definition.steps![index]; const saved = rows[index]
245
+ const action = compensating ? step.compensate! : step
246
+ const count = compensating ? saved.compensation_attempts : saved.attempts
247
+ const deadline = (compensating ? saved.compensation_deadline_at : saved.deadline_at) ?? optionsNow() + step.policy.deadlineMs
248
+ const key = `${run.id}:${step.id}:${compensating ? 'undo' : 'do'}`
249
+ const scope = this.scope(run)
250
+ // Fence every executeAtomic batch supplied to a step, even if its runner outlives its lease.
251
+ const base = new D1AtomicStore(this.env.DB, { env: this.env, config: this.config })
252
+ const store: AtomicStore = { run: plan => base.run({ ...plan, rules: [
253
+ { name: 'workflow_lease', statements: [this.fence(run, optionsNow())] }, ...plan.rules,
254
+ // The public idempotency table accepts caller-chosen keys. Only this fenced
255
+ // effect batch can create the private receipt used for workflow crash recovery.
256
+ { name: 'workflow_effect_receipt', statements: [{
257
+ sql: `UPDATE workflow_steps SET ${compensating ? 'compensation_checkpoint_json' : 'checkpoint_json'}=(SELECT response_json FROM idempotency_keys WHERE organization_id=? AND key=? AND command=?) WHERE run_id=? AND step_id=? AND EXISTS(SELECT 1 FROM idempotency_keys WHERE organization_id=? AND key=? AND command=?)`,
258
+ bindings: [scope.organizationId, key, action.operation.name, run.id, step.id, scope.organizationId, key, action.operation.name], expectRows: 1,
259
+ }] },
260
+ ] }) }
261
+ // Use elapsed real time relative to the tick clock, allowing deterministic local tests.
262
+ let context = coreExecutionContext(this.config, scope, store, new D1AtomicReader(this.env.DB), key, undefined, { policyReceipt: !compensating })
263
+ try {
264
+ const live = await assertLivePermission(context, action.operation)
265
+ context = coreExecutionContext(this.config, live, store, new D1AtomicReader(this.env.DB), key, undefined, { policyReceipt: !compensating })
266
+ // If an atomic effect committed before a crash, recover its receipt without repeating it or spending another attempt.
267
+ const receipt = compensating ? saved.compensation_checkpoint_json : saved.checkpoint_json
268
+ if (receipt) { await this.finishStep(run, optionsNow(), step, compensating, JSON.parse(receipt)); return }
269
+ if (optionsNow() >= deadline) throw new ApiError(408, 'workflow.deadline_exceeded')
270
+ if (count >= step.policy.maxAttempts && !compensating && step.kind === 'external' && step.recover) {
271
+ const controller = new AbortController()
272
+ let timer: ReturnType<typeof setTimeout> | undefined
273
+ const result = await Promise.race([step.recover(Object.freeze({ context, runId: run.id, input: JSON.parse(run.input_json), checkpoints: Object.fromEntries(rows.filter(s => s.checkpoint_json).map(s => [s.step_id, publicCheckpoint(s.checkpoint_json!)])), signal: controller.signal })), new Promise<never>((_, reject) => {
274
+ timer = setTimeout(() => { controller.abort(); reject(new ApiError(408, 'workflow.external_timeout')) }, Math.min(step.policy.timeoutMs, deadline - optionsNow()))
275
+ })]).finally(() => clearTimeout(timer))
276
+ if (result !== null && optionsNow() < deadline) { await this.finishStep(run, optionsNow(), step, false, result); return }
277
+ }
278
+ if (count >= step.policy.maxAttempts) throw new ApiError(408, 'workflow.attempts_exhausted')
279
+ await this.submit([this.fence(run, optionsNow()), {
280
+ sql: `UPDATE workflow_steps SET ${compensating ? 'compensation_attempts' : 'attempts'}=${compensating ? 'compensation_attempts' : 'attempts'}+1,${compensating ? 'compensation_deadline_at' : 'deadline_at'}=?,status=? WHERE run_id=? AND step_id=?`,
281
+ bindings: [deadline, compensating ? saved.status : 'executing', run.id, step.id], expectRows: 1,
282
+ }, { sql: 'UPDATE workflow_runs SET status=? WHERE id=?', bindings: [compensating ? 'compensating' : step.kind === 'external' ? 'waiting_external' : 'running', run.id], expectRows: 1 }])
283
+ const remaining = deadline - optionsNow()
284
+ if (remaining <= 0) throw new ApiError(408, 'workflow.deadline_exceeded')
285
+ const controller = new AbortController()
286
+ let timer: ReturnType<typeof setTimeout> | undefined
287
+ const result = await Promise.race([action.run(Object.freeze({ context, runId: run.id, input: JSON.parse(run.input_json), checkpoints: Object.fromEntries(rows.filter(s => s.checkpoint_json).map(s => [s.step_id, publicCheckpoint(s.checkpoint_json!)])), signal: controller.signal })), new Promise<never>((_, reject) => {
288
+ timer = setTimeout(() => { controller.abort(); reject(new ApiError(408, 'workflow.external_timeout')) }, Math.min(step.policy.timeoutMs, remaining))
289
+ })]).finally(() => clearTimeout(timer))
290
+ // No late response can checkpoint after the deadline or a newer runner's lease.
291
+ if (optionsNow() >= deadline) throw new ApiError(408, 'workflow.deadline_exceeded')
292
+ await this.finishStep(run, optionsNow(), step, compensating, result ?? null)
293
+ } catch (error) {
294
+ const time = optionsNow()
295
+ if (error instanceof PermissionRevoked) { await this.transition(run, time, 'needs_attention', 'workflow.needs_attention', 'permission_revoked'); return }
296
+ let code = error instanceof ApiError && ['workflow.external_timeout', 'workflow.deadline_exceeded', 'workflow.attempts_exhausted', 'rule_failed', 'workflow.external_not_configured', 'workflow.external_transport_failed', 'workflow.external_forbidden', 'workflow.external_rejected', 'workflow.external_invalid_receipt'].includes(error.code) ? error.code : 'workflow.step_failed'
297
+ const uncertainCodes = ['workflow.external_timeout', 'workflow.external_transport_failed']
298
+ const waitForDeadline = !compensating && step.kind === 'external' && time < deadline
299
+ && count + 1 >= step.policy.maxAttempts
300
+ && (count >= step.policy.maxAttempts || uncertainCodes.includes(code))
301
+ if (waitForDeadline && count >= step.policy.maxAttempts) code = 'workflow.external_uncertain'
302
+ // A missing response is not a rejection. Once the bounded delivery budget is
303
+ // spent, retain the uncertainty until the deadline before cancelling it.
304
+ const exhausted = !waitForDeadline && (count + 1 >= step.policy.maxAttempts || time >= deadline)
305
+ const hasCompensation = definition.steps!.some((s, i) => s.compensate && (i === index || ['completed', 'executing'].includes(rows[i].status)))
306
+ const status = compensating ? (exhausted ? 'needs_attention' : 'compensating') : exhausted ? (hasCompensation ? 'compensating' : 'failed') : step.kind === 'external' ? 'waiting_external' : 'running'
307
+ const next = waitForDeadline ? (step.recover ? Math.min(deadline, time + Math.max(10000, step.policy.backoffMs)) : deadline) : Math.min(deadline, time + step.policy.backoffMs * 2 ** Math.min(count, 8))
308
+ await this.transition({ ...run, status: compensating ? 'compensating' : run.status }, time, status, exhausted && compensating ? 'workflow.needs_attention' : 'workflow.step.failed', code, [
309
+ { sql: 'UPDATE workflow_steps SET status=?,last_error_code=?,next_attempt_at=? WHERE run_id=? AND step_id=?', bindings: [!compensating && exhausted ? 'failed' : compensating ? saved.status : 'executing', code, next, run.id, step.id], expectRows: 1 },
310
+ ...(exhausted && compensating ? [this.audit(scope, run.id, 'workflow.step.failed', step.id, code)] : []),
311
+ ...(exhausted && !compensating ? [this.audit(scope, run.id, 'workflow.failed', step.id, code)] : []),
312
+ ], step.id, exhausted ? time : next)
313
+ }
314
+ }
315
+ private finishStep(run: Run, now: number, step: WorkflowStep, undo: boolean, result: unknown) {
316
+ const checkpoint = undo ? 'compensation_checkpoint_json' : 'checkpoint_json'
317
+ return this.transition(run, now, undo ? 'compensating' : 'running', undo ? 'workflow.step.compensated' : 'workflow.step.completed', undo ? run.last_error_code : null, [{
318
+ // Keep the execution-owned policy receipt committed with an atomic effect.
319
+ // The public return value has already stripped the affected-row metadata.
320
+ sql: `UPDATE workflow_steps SET status=?,${checkpoint}=COALESCE(${checkpoint},?),last_error_code=NULL,next_attempt_at=0 WHERE run_id=? AND step_id=?`,
321
+ bindings: [undo ? 'compensated' : 'completed', JSON.stringify(result), run.id, step.id], expectRows: 1,
322
+ }], step.id)
323
+ }
324
+ }
325
+ export async function runWorkflows(env: RuntimeEnv, config: InstanceConfig, definitions: WorkflowRegistry, options: { now?: number; limit?: number } = {}) {
326
+ return new D1WorkflowRuntime(env, config, definitions).tick(options)
327
+ }
@@ -0,0 +1,29 @@
1
+ export const workflowSchema = `
2
+ CREATE TABLE workflow_runs (
3
+ id TEXT PRIMARY KEY, organization_id TEXT NOT NULL REFERENCES organizations(id),
4
+ actor_id TEXT NOT NULL, actor_type TEXT NOT NULL CHECK(actor_type IN ('user','agent')), token_id TEXT,
5
+ definition_name TEXT NOT NULL, definition_version TEXT NOT NULL,
6
+ input_json TEXT NOT NULL CHECK(json_valid(input_json)), definition_signature TEXT NOT NULL,
7
+ status TEXT NOT NULL CHECK(status IN ('pending','running','waiting_external','completed','failed','compensating','compensated','needs_attention','cancelled')),
8
+ cancel_actor_id TEXT, resume_status TEXT, correlation_id TEXT NOT NULL, result_json TEXT CHECK(result_json IS NULL OR json_valid(result_json)),
9
+ last_error_code TEXT, next_attempt_at INTEGER NOT NULL, lease_until INTEGER, lease_token TEXT,
10
+ created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(organization_id,id)
11
+ );
12
+ CREATE INDEX workflow_runs_due_idx ON workflow_runs(status,next_attempt_at,lease_until);
13
+ CREATE INDEX workflow_runs_org_idx ON workflow_runs(organization_id,created_at,id);
14
+ CREATE TABLE workflow_steps (
15
+ run_id TEXT NOT NULL REFERENCES workflow_runs(id), step_id TEXT NOT NULL, position INTEGER NOT NULL,
16
+ status TEXT NOT NULL CHECK(status IN ('pending','executing','completed','failed','compensated')),
17
+ attempts INTEGER NOT NULL DEFAULT 0, compensation_attempts INTEGER NOT NULL DEFAULT 0,
18
+ next_attempt_at INTEGER NOT NULL DEFAULT 0, deadline_at INTEGER, compensation_deadline_at INTEGER,
19
+ compensation_checkpoint_json TEXT CHECK(compensation_checkpoint_json IS NULL OR json_valid(compensation_checkpoint_json)),
20
+ checkpoint_json TEXT CHECK(checkpoint_json IS NULL OR json_valid(checkpoint_json)), last_error_code TEXT,
21
+ PRIMARY KEY(run_id,step_id), UNIQUE(run_id,position)
22
+ );
23
+ CREATE TABLE workflow_holds (
24
+ run_id TEXT PRIMARY KEY REFERENCES workflow_runs(id), organization_id TEXT NOT NULL,
25
+ resource_id TEXT NOT NULL, expires_at TEXT NOT NULL,
26
+ status TEXT NOT NULL CHECK(status IN ('held','confirmed','released'))
27
+ );
28
+ CREATE INDEX workflow_holds_expiry_idx ON workflow_holds(status,expires_at);
29
+ `