feat(state-machine): converge to one enforced state_machine rule (ADR-0020) (#1413)

Make the state_machine validation rule a real write-path guardrail and
retire the redundant declaration shapes. Before this, a record state
machine could be declared three ways (workflow metadata type,
object.stateMachines, or a state_machine validation rule) with zero
runtime enforcement.

Enforcement (objectql):
- New validation/rule-validator.ts: evaluateValidationRules /
  needsPriorRecord / legalNextStates. state_machine rejects illegal
  field transitions on update; script/cross_field predicates now fire
  too (previously silently broken on PATCH). engine.ts plumbs the prior
  record on single-row update; updateMany logs a warning and skips.

Convergence/retirement (spec) — breaking:
- Retire the `workflow` metadata type (enum, registry, schema map,
  collection key, plural mapping). Remove object.stateMachines and
  stack.workflows. The state_machine validation rule is the one home.
- Keep StateMachineSchema (still used by agent lifecycle + protocol) and
  the workflow RPC service surface as a documented follow-up.

Introspection (runtime):
- GET /metadata/objects/:name/state/:field?from=:state returns legal
  next states (null when no FSM, [] for a dead-end).

Surfaces: Studio drops the "Workflow Rules" nav; cli explain drops the
`workflow` related type.

Examples: app-crm workflows migrated — transition table is the
opp_stage_transitions state_machine rule; side effects became
record-triggered/scheduled Flows. app-showcase predicate conditions
corrected to the record.<field> CEL scope.

Tests: rule-validator.test.ts (16 cases) + updates to object/
metadata-plugin/metadata-collection/overlay-precedence tests.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>

Author: xuyushun441-sys

.changeset/adr-0020-state-machine-converge-enforce.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": patch
+"@objectstack/platform-objects": patch
+"@objectstack/cli": patch
+---
+
+ADR-0020 — converge the three "state machine" declaration shapes to one
+**enforced** `state_machine` validation rule.
+
+Before this change a record state machine could be declared three ways (a
+`workflow` metadata type, an `object.stateMachines` map, or a `state_machine`
+validation rule) and **none of them were enforced at runtime** — a declarative
+guardrail that was pure decoration, and a hallucination trap for AI authors.
+
+**Enforcement (`@objectstack/objectql`)**
+- New `validation/rule-validator.ts` evaluates the object's `validations` union
+  on the write path: `evaluateValidationRules`, `needsPriorRecord`, and the
+  `legalNextStates` introspection helper (all exported from the package root).
+- `state_machine` rules reject illegal `field` transitions on update (with the
+  rule's `message`); `script` / `cross_field` predicate rules now also fire
+  (they were silently broken on PATCH updates because only the patch, not the
+  prior record, was available). The engine plumbs the prior record into
+  rule evaluation on single-row update; multi-row (`updateMany`) updates log a
+  warning and skip rule evaluation rather than enforce on incomplete data.
+
+**Convergence / retirement (`@objectstack/spec`) — breaking**
+- Retires the `workflow` metadata type (removed from the metadata-type enum,
+  the registry, the schema map, the `workflows` collection key, and the
+  plural→singular mapping).
+- Removes the `object.stateMachines` map and the `stack.workflows` array. The
+  `state_machine` validation rule is the single canonical home.
+- The XState-style `StateMachineSchema` file is **kept** (still used by the
+  agent conversation lifecycle and the discovery protocol); only its role as
+  the `workflow` metadata-type backing schema was removed. The optional
+  `workflow` **RPC service** surface (`CoreServiceName.workflow`,
+  `/api/v1/workflow`, `IWorkflowService`) is kept as a documented follow-up.
+
+**Introspection (`@objectstack/runtime`)**
+- Adds `GET /metadata/objects/:name/state/:field?from=:state`, returning the
+  legal next states for a field (`next: null` when no FSM governs the field,
+  `[]` for a declared dead-end) so UIs/agents read the transition table instead
+  of re-deriving it.
+
+**Surfaces (`@objectstack/platform-objects`, `@objectstack/cli`)**
+- Studio drops the standalone "Workflow Rules" nav (state machines are edited
+  alongside the object's other validation rules).
+- `explain` no longer lists `workflow` as a related metadata type.
+
+Migration: replace a `workflow` / `StateMachineConfig` declaration with a
+`state_machine` validation rule on the object (`field` + `{ from: [allowedTo] }`
+transition table), and move any side-effecting actions (emails, task creation)
+into a record-triggered or scheduled Flow (ADR-0019). See the migrated
+`examples/app-crm` flows for the pattern.

docs/adr/0020-state-machine-converge-and-enforce.md

@@ -1,6 +1,6 @@
 # ADR-0020: State Machine — converge three declaration forms to one enforced `state_machine`
 
-**Status**: Proposed (2026-05-31)
+**Status**: Accepted — Implemented (2026-05-31)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0019](./0019-approval-as-flow-node.md) (collapse approval into Flow — "one engine, fold the parasitic concept into its host"; this ADR applies the same principle to the state-machine concept), [ADR-0009](./0009-execution-pinned-metadata.md) (execution-pinned metadata), [ADR-0010](./0010-nl-to-flow-authoring.md) + [ADR-0011](./0011-actions-as-ai-tools.md) (AI authoring is the design center)
 **Revises**: the #1398 outcome that "reclaimed `workflow` for state machines" — that reclaim left a *name* (`workflow`) and *three* declaration shapes, but no runtime enforcement. This ADR finishes the job.
@@ -130,14 +130,26 @@ The transition declaration stays a flat, recognizable FSM (`field` + `{ from: [t
 
 ## Blast radius / implementation checklist
 
-- [ ] `spec`: remove `workflow` from the metadata type enum + registry ([`metadata-plugin.zod.ts:90`](../../packages/spec/src/kernel/metadata-plugin.zod.ts#L90), [`:612`](../../packages/spec/src/kernel/metadata-plugin.zod.ts#L612)) and the schema map ([`metadata-type-schemas.ts:85`](../../packages/spec/src/kernel/metadata-type-schemas.ts#L85)).
-- [ ] `spec`: **canonical home decided — the `state_machine` validation rule** ([`validation.zod.ts:105`](../../packages/spec/src/data/validation.zod.ts#L105)). Remove `object.stateMachines` ([`object.zod.ts:534`](../../packages/spec/src/data/object.zod.ts#L534)); delete the XState `StateMachineSchema` ([`state-machine.zod.ts`](../../packages/spec/src/automation/state-machine.zod.ts)); optionally add an optional per-transition CEL `guard` to `StateMachineValidationSchema`.
-- [ ] `spec`: remove/retire `IWorkflowService` ([`workflow-service.ts`](../../packages/spec/src/contracts/workflow-service.ts)) or repurpose it as the enforcement contract.
-- [ ] `objectql`: wire the `validations` union into the write path — **plumb the prior/merged record** into rule evaluation (extend [`validateRecord`](../../packages/objectql/src/validation/record-validator.ts#L198) signature or evaluate from a `beforeUpdate` step at [`engine.ts:1850`](../../packages/objectql/src/engine.ts#L1850)), then add `type` dispatch. Fixes `state_machine`, `cross_field`, and `script` together.
-- [ ] `metadata-collection.zod.ts`: drop the `workflows: 'workflow'` collection key ([`metadata-collection.zod.ts:117`](../../packages/spec/src/shared/metadata-collection.zod.ts#L117)).
-- [ ] `examples/app-crm`: rewrite `src/workflows/*.workflow.ts` — transition rules → `state_machine`; side-effect actions → record-triggered Flow; update `objectstack.config.ts` registration.
-- [ ] `examples/app-showcase`: **already carries the surviving shape** — `state_machine` rules on `Task`, `Project`, `Account` (added in this design pass, typecheck passing). Keep them as enforcement test fixtures; no new authoring needed.
-- [ ] Tests: add write-path tests asserting illegal transitions are rejected and legal ones pass (e.g. `Account` `active → prospect` rejected, `churned → active` allowed).
+- [x] `spec`: remove `workflow` from the metadata type enum + registry ([`metadata-plugin.zod.ts`](../../packages/spec/src/kernel/metadata-plugin.zod.ts)) and the schema map ([`metadata-type-schemas.ts`](../../packages/spec/src/kernel/metadata-type-schemas.ts)).
+- [x] `spec`: **canonical home — the `state_machine` validation rule** ([`validation.zod.ts`](../../packages/spec/src/data/validation.zod.ts)). Removed `object.stateMachines` ([`object.zod.ts`](../../packages/spec/src/data/object.zod.ts)) and the `stack.workflows` array ([`stack.zod.ts`](../../packages/spec/src/stack.zod.ts)). *(Deviation: kept the `StateMachineSchema` file — see Implementation notes.)*
+- [~] `spec`: `IWorkflowService` — **kept as a documented follow-up**, not removed (see Implementation notes).
+- [x] `objectql`: wire the `validations` union into the write path — new [`rule-validator.ts`](../../packages/objectql/src/validation/rule-validator.ts) (`evaluateValidationRules` / `needsPriorRecord` / `legalNextStates`), with the prior record plumbed into [`engine.ts`](../../packages/objectql/src/engine.ts) on single-row update. Enforces `state_machine`, `cross_field`, and `script` together.
+- [x] `metadata-collection.zod.ts`: dropped the `workflows` collection key + `workflows: 'workflow'` plural mapping ([`metadata-collection.zod.ts`](../../packages/spec/src/shared/metadata-collection.zod.ts)).
+- [x] `examples/app-crm`: rewrote `src/workflows/*.workflow.ts` — transition tables already live as the `opp_stage_transitions` `state_machine` rule on the opportunity object; side-effect actions became record-triggered / scheduled Flows ([`high-value-deal.flow.ts`](../../examples/app-crm/src/flows/high-value-deal.flow.ts), [`stale-opportunity.flow.ts`](../../examples/app-crm/src/flows/stale-opportunity.flow.ts)); removed the `workflows` registration from `objectstack.config.ts`.
+- [x] `examples/app-showcase`: carries the surviving shape — `state_machine` rules on `Task`, `Project`, `Account`. Predicate conditions corrected to the `record.<field>` CEL scope form so enforcement actually fires.
+- [x] Tests: [`rule-validator.test.ts`](../../packages/objectql/src/validation/rule-validator.test.ts) (16 cases — allow/reject/no-op transitions, execution-control, predicate fail-open, introspection). Updated `object.test.ts`, `metadata-plugin.test.ts`, `metadata-collection.test.ts`, `overlay-precedence.test.ts` for the retired shapes.
+
+## Implementation notes (deviations from the proposal)
+
+The proposal's intent is fully delivered — converge to the `state_machine` rule, retire the `workflow` metadata type, enforce on the write path — with three **bounded** deviations, all to avoid scope creep into unrelated subsystems:
+
+1. **`StateMachineSchema` (the XState-style schema) is kept, not deleted.** It is still imported by the agent conversation lifecycle ([`ai/agent.zod.ts`](../../packages/spec/src/ai/agent.zod.ts)) and the discovery protocol ([`api/protocol.zod.ts`](../../packages/spec/src/api/protocol.zod.ts)). Only its role as the **`workflow` metadata-type backing schema** and the **`object.stateMachines` / `stack.workflows`** homes were removed. Deleting the schema outright would have churned the agent/protocol surfaces, which is a separate concern.
+
+2. **The `workflow` *RPC service* surface is kept as a follow-up.** `CoreServiceName.workflow`, the `/api/v1/workflow` route catalog (`DEFAULT_WORKFLOW_ROUTES`), and `IWorkflowService` remain — they describe an *unimplemented optional service*, not the retired *metadata type*, and removing them touches the service-discovery contract and its tests. Tracked as a follow-up; the metadata-type retirement (the AI-hallucination hazard this ADR targets) is complete.
+
+3. **No per-transition CEL `guard` was added** to `StateMachineValidationSchema` (it was "optional" in D3/D4). The flat `field` + `transitions` table is enforced as-is; a conditional transition can be expressed today as a sibling `script`/`conditional` rule. Guards can be added later without a breaking change.
+
+**Enforcement scope:** rules run on single-row insert/update through the merged `{...previous, ...patch}` record. Multi-row (`updateMany`) updates **log a warning and skip** rule evaluation rather than silently enforcing on incomplete data — surfaced, not hidden.
 
 ## Alternatives considered
 

examples/app-crm/objectstack.config.ts

@@ -12,7 +12,6 @@ import * as actions from './src/actions/index.js';
 import * as emails from './src/emails/index.js';
 import { allHooks } from './src/hooks/index.js';
 import { allFlows } from './src/flows/index.js';
-import { HighValueDealWorkflow, StaleOpportunityWorkflow } from './src/workflows/index.js';
 import {
   SalesAssistantAgent,
   LookupContactTool,
@@ -105,8 +104,11 @@ export default defineStack({
 
   // Logic
   hooks: allHooks,
+  // ADR-0020: `workflows` retired — record state machines are now a
+  // `state_machine` validation rule on the object (see
+  // src/objects/opportunity.object.ts) and side-effecting automation is
+  // modelled as Flows (high-value-deal, stale-opportunity in allFlows).
   flows: allFlows,
-  workflows: [HighValueDealWorkflow, StaleOpportunityWorkflow],
   jobs: [LeadScoringJob, PipelineReportJob, RenewalSweepJob],
   emailTemplates: Object.values(emails),
 

examples/app-crm/src/flows/high-value-deal.flow.ts

@@ -0,0 +1,58 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Flow } from '@objectstack/spec/automation';
+
+/**
+ * High-Value Deal alert — record-triggered flow.
+ *
+ * Migrated from the legacy `workflow` metadata type (retired in ADR-0020,
+ * which reclaims the runtime FSM as the `state_machine` validation rule on
+ * the object and folds side-effecting automation into Flow). The original
+ * rule fired when a `crm_opportunity` crossed the $100k threshold and
+ * notified sales managers; that side effect is exactly a record-triggered
+ * Flow.
+ *
+ * The lifecycle/transition aspect (open → high_value → won/lost) is no
+ * longer modelled here — record state transitions belong on the object as a
+ * `state_machine` validation rule (see opportunity.object.ts). This Flow
+ * carries only the notification side effect.
+ */
+export const HighValueDealFlow: Flow = {
+  name: 'high_value_deal_alert',
+  label: 'Notify on High-Value Deal',
+  description: 'Notifies sales managers when an opportunity amount crosses the $100k threshold.',
+  type: 'autolaunched',
+
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Opportunity Update',
+      config: {
+        objectName: 'crm_opportunity',
+        triggerType: 'record-after-update',
+        // Fire only on the upward crossing of the threshold, not on every
+        // save of an already-high-value deal.
+        condition: 'amount > 100000 && (previous.amount == null || previous.amount <= 100000)',
+      },
+    },
+    {
+      id: 'notify_managers',
+      type: 'script',
+      label: 'Notify Sales Managers',
+      config: {
+        actionType: 'email',
+        inputs: {
+          to: '{record.owner_manager_email}',
+          subject: '💰 High-Value Deal: {record.name}',
+          template: 'high_value_deal_alert',
+        },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'notify_managers' },
+    { id: 'e2', source: 'notify_managers', target: 'end' },
+  ],
+};

examples/app-crm/src/flows/index.ts

@@ -5,7 +5,19 @@ import { LeadQualificationFlow } from './lead-qualification.flow.js';
 import { RenewalReminderFlow } from './renewal-reminder.flow.js';
 import { ConvertLeadScreenFlow } from './convert-lead.flow.js';
 import { DiscountApprovalFlow } from './discount-approval.flow.js';
+// ADR-0020: side-effecting automation migrated off the retired `workflow`
+// metadata type into record-triggered / scheduled Flows.
+import { HighValueDealFlow } from './high-value-deal.flow.js';
+import { StaleOpportunityFlow } from './stale-opportunity.flow.js';
 
 export { ConvertLeadScreenFlow } from './convert-lead.flow.js';
 
-export const allFlows = [OpportunityWonFlow, LeadQualificationFlow, RenewalReminderFlow, ConvertLeadScreenFlow, DiscountApprovalFlow];
+export const allFlows = [
+  OpportunityWonFlow,
+  LeadQualificationFlow,
+  RenewalReminderFlow,
+  ConvertLeadScreenFlow,
+  DiscountApprovalFlow,
+  HighValueDealFlow,
+  StaleOpportunityFlow,
+];

examples/app-crm/src/flows/stale-opportunity.flow.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Flow } from '@objectstack/spec/automation';
+
+/**
+ * Stale Opportunity sweep — scheduled flow.
+ *
+ * Migrated from the legacy time-based `workflow` metadata type (retired in
+ * ADR-0020). The original rule ran on a schedule, found open
+ * `crm_opportunity` records untouched for 30+ days, and (a) emailed the
+ * owner and (b) created a follow-up task. A scheduled sweep with
+ * side-effecting actions is precisely a schedule-triggered Flow, so it now
+ * lives here rather than as a bespoke workflow metadata type.
+ */
+export const StaleOpportunityFlow: Flow = {
+  name: 'stale_opportunity_sweep',
+  label: 'Stale Opportunity Sweep',
+  description: 'Daily sweep that notifies owners of open opportunities untouched for 30+ days and opens a follow-up task.',
+  type: 'schedule',
+
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'Daily Schedule',
+      config: {
+        triggerType: 'schedule',
+        // Every day at 08:00 — re-evaluate open opportunities for staleness.
+        cron: '0 8 * * *',
+        objectName: 'crm_opportunity',
+        filter: "stage != 'closed_won' && stage != 'closed_lost' && last_modified < daysAgo(30)",
+      },
+    },
+    {
+      id: 'notify_owner',
+      type: 'script',
+      label: 'Notify Owner',
+      config: {
+        actionType: 'email',
+        inputs: {
+          to: '{record.owner_email}',
+          subject: '⏰ Stale Opportunity: {record.name}',
+          template: 'stale_opportunity_alert',
+        },
+      },
+    },
+    {
+      id: 'open_followup_task',
+      type: 'create_record',
+      label: 'Open Follow-up Task',
+      config: {
+        objectName: 'crm_activity',
+        inputs: {
+          subject: 'Follow up on stale opportunity: {record.name}',
+          description: 'This opportunity has not been updated in 30+ days. Please review and update.',
+          due_date: '{daysFromNow(3)}',
+          related_to: '{record.id}',
+        },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'notify_owner' },
+    { id: 'e2', source: 'notify_owner', target: 'open_followup_task' },
+    { id: 'e3', source: 'open_followup_task', target: 'end' },
+  ],
+};

examples/app-crm/src/objects/opportunity.object.ts

@@ -80,7 +80,7 @@ export const Opportunity = ObjectSchema.create({
       name: 'discount_cap',
       label: 'Discount Cap 40%',
       description: 'Discounts over 40% require special approval.',
-      condition: P`discount_percent != null && discount_percent > 40`,
+      condition: P`record.discount_percent != null && record.discount_percent > 40`,
       message: 'Discount cannot exceed 40% without an approved exception.',
       severity: 'error' as const,
     },
@@ -90,7 +90,7 @@ export const Opportunity = ObjectSchema.create({
       label: 'Close Date Must Be Future',
       description: 'Prevent setting close_date to a date in the past on new records.',
       fields: ['close_date'],
-      condition: P`has(close_date) && close_date < now()`,
+      condition: P`has(record.close_date) && record.close_date < now()`,
       message: 'Close Date must be today or a future date.',
       events: ['insert'],
     },