Implement OTP supervision tree and public API for wf_substrate

This commit implements the complete OTP supervision tree and public API
for wf_substrate as specified in item 012. The implementation provides a
production-grade process architecture for workflow case management with
proper fault containment and supervision.

Key changes:

**New Modules:**
- wf_case_runner: Per-case gen_statem managing execution lifecycle with
  explicit states (initializing, running, waiting_effect, waiting_signal,
  cancelled, done). Executes bytecode in quanta, handles signals, and
  supports state timeout for case timeout.

- wf_case_sup: Dynamic supervisor using simple_one_for_one strategy to
  manage per-case runner processes. Cases are temporary (not restarted on
  normal termination) to avoid replaying execution state.

- Updated wf_substrate_sup: Added wf_case_sup as permanent child in the
  supervision tree alongside existing singletons (wf_governance,
  wf_budget, wf_approval).

- Updated wf_substrate: Implemented complete public API including:
  * new_case/3: Create workflow case (accepts bytecode directly until item 004)
  * signal/2: Send external signal to running case
  * cancel/1, cancel_region/2: Cancel case or specific region
  * await/2: Block until case completion with monitor/timeout
  * status/1: Query current case status
  * trace/3: Configure trace level and sink
  * validate/2: Stub returning ok (item 013 will implement)

**Testing:**
- wf_case_runner_tests: State machine transition tests
- wf_supervision_tree_tests: Supervisor behavior, dynamic children,
  restart strategies, name conflicts
- wf_substrate_api_tests: Complete API coverage including error cases
- wf_exec_tests.hrl: Shared mock bytecode generators

**Examples:**
- examples/basic_usage.erl: Demonstrates sequential and parallel workflows
  with tracing and signal delivery

**Configuration:**
- Updated wf_substrate.app.src: registered includes wf_case_sup,
  modules list includes all new modules

The supervision tree structure:
  wf_substrate_sup (one_for_one)
  ├── wf_case_sup (simple_one_for_one)
  │   └── wf_case_runner (temporary, per case)
  ├── wf_governance (permanent)
  ├── wf_budget (permanent)
  └── wf_approval (permanent)

All modules compile without warnings and follow existing code patterns.
Process registration uses Erlang registry (no external dependencies).
TODO comments added for item 004 (wf_compile) and item 013 (wf_validate).

Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>

Author: jmanhype

.wreckit/items/012-otp-supervision-tree/item.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "id": "012-otp-supervision-tree",
   "title": "Implement OTP supervision tree and public API",
-  "state": "researched",
-  "overview": "Implement the OTP supervision tree and public API for wf_substrate.\n\nSupervision hierarchy:\n- wf_substrate_sup: top-level supervisor (one_for_one), starts wf_case_sup and optional singletons.\n- wf_case_sup: dynamic supervisor (simple_one_for_one) for per-case runner processes.\n- wf_effect_sup (optional): dynamic supervisor for effect handler processes if effects are executed in-process.\n- wf_trace_sink: optional gen_server that collects trace events from all cases (for centralized logging/monitoring).\n\nPer-case runner as gen_statem with states: {initializing, running, waiting_effect, waiting_signal, cancelled, done}. The runner holds the exec_state, steps in configurable bursts (N reductions then yield to scheduler), handles incoming signals (external events that feed into XOR choices or task completions), effect responses, and cancel requests. Uses state_timeout for overall case timeout.\n\nPublic API module wf_substrate.erl exports:\n- new_case/3 :: (CaseId, wf_term(), Ctx) -> {ok, Pid} \u2014 compile term, create runner.\n- signal/2 :: (CaseId, Signal) -> ok \u2014 send external signal to running case.\n- cancel/1 :: (CaseId) -> ok \u2014 cancel entire case.\n- cancel_region/2 :: (CaseId, ScopeId) -> ok \u2014 cancel a region within a case.\n- await/2 :: (CaseId, Timeout) -> {ok, Result} | {error, Reason} \u2014 block until case completes.\n- status/1 :: (CaseId) -> Status \u2014 get current case status.\n- trace/3 :: (CaseId, Level, Sink) -> ok \u2014 configure tracing for a case.\n- validate/2 :: (wf_term(), Options) -> ok | {error, Issues} \u2014 static validation without execution.\n\nInclude wf_substrate_app.erl (application behaviour) that starts wf_substrate_sup.",
+  "state": "implementing",
+  "overview": "Implement the OTP supervision tree and public API for wf_substrate.\n\nSupervision hierarchy:\n- wf_substrate_sup: top-level supervisor (one_for_one), starts wf_case_sup and optional singletons.\n- wf_case_sup: dynamic supervisor (simple_one_for_one) for per-case runner processes.\n- wf_effect_sup (optional): dynamic supervisor for effect handler processes if effects are executed in-process.\n- wf_trace_sink: optional gen_server that collects trace events from all cases (for centralized logging/monitoring).\n\nPer-case runner as gen_statem with states: {initializing, running, waiting_effect, waiting_signal, cancelled, done}. The runner holds the exec_state, steps in configurable bursts (N reductions then yield to scheduler), handles incoming signals (external events that feed into XOR choices or task completions), effect responses, and cancel requests. Uses state_timeout for overall case timeout.\n\nPublic API module wf_substrate.erl exports:\n- new_case/3 :: (CaseId, wf_term(), Ctx) -> {ok, Pid} — compile term, create runner.\n- signal/2 :: (CaseId, Signal) -> ok — send external signal to running case.\n- cancel/1 :: (CaseId) -> ok — cancel entire case.\n- cancel_region/2 :: (CaseId, ScopeId) -> ok — cancel a region within a case.\n- await/2 :: (CaseId, Timeout) -> {ok, Result} | {error, Reason} — block until case completes.\n- status/1 :: (CaseId) -> Status — get current case status.\n- trace/3 :: (CaseId, Level, Sink) -> ok — configure tracing for a case.\n- validate/2 :: (wf_term(), Options) -> ok | {error, Issues} — static validation without execution.\n\nInclude wf_substrate_app.erl (application behaviour) that starts wf_substrate_sup.",
   "branch": null,
   "pr_url": null,
   "pr_number": null,
   "last_error": null,
   "created_at": "2026-02-10T00:00:00.000Z",
-  "updated_at": "2026-02-10T00:00:00.000Z"
-}
+  "updated_at": "2026-02-11T18:49:05.771Z"
+}

examples/basic_usage.erl

@@ -0,0 +1,66 @@
+%%%-------------------------------------------------------------------
+%%% @doc Basic usage examples for wf_substrate
+%%% @end
+%%%-------------------------------------------------------------------
+-module(basic_usage).
+-export([run_simple_workflow/0, run_parallel_workflow/0]).
+
+%% @doc Run a simple sequential workflow
+run_simple_workflow() ->
+    %% Define bytecode for sequence: Task A -> Task B -> Done
+    Bytecode = [
+        {'SEQ_ENTER', 0},
+        {'TASK_EXEC', task_a},
+        {'SEQ_NEXT', 3},
+        {'TASK_EXEC', task_b},
+        {'DONE'}
+    ],
+
+    %% Start application
+    {ok, _Apps} = application:ensure_all_started(wf_substrate),
+
+    %% Create new case
+    {ok, Pid} = wf_substrate:new_case(simple_seq, Bytecode, #{}),
+
+    %% Await completion
+    Result = wf_substrate:await(simple_seq, 5000),
+
+    %% Clean up
+    application:stop(wf_substrate),
+
+    Result.
+
+%% @doc Run a parallel workflow
+run_parallel_workflow() ->
+    %% Define bytecode for parallel: Task A || Task B
+    Bytecode = [
+        {'PAR_FORK', [1, 3]},
+        {'TASK_EXEC', task_a},
+        {'DONE'},
+        {'TASK_EXEC', task_b},
+        {'DONE'},
+        {'JOIN_WAIT', all}
+    ],
+
+    %% Start application
+    {ok, _Apps} = application:ensure_all_started(wf_substrate),
+
+    %% Create new case with tracing enabled
+    {ok, Pid} = wf_substrate:new_case(parallel_flow, Bytecode, #{}),
+
+    %% Configure tracing
+    ok = wf_substrate:trace(parallel_flow, min, {ets, wf_trace_events}),
+
+    %% Send signal during execution
+    ok = wf_substrate:signal(parallel_flow, {user_event, data}),
+
+    %% Check status
+    {ok, StatusInfo} = wf_substrate:status(parallel_flow),
+
+    %% Await completion
+    Result = wf_substrate:await(parallel_flow, 10000),
+
+    %% Clean up
+    application:stop(wf_substrate),
+
+    Result.