03 — Wrapper / Correlation Harness Design (Workstream B)

The wrapper is the standard path for turning a DOT producer/verifier pair into a correlated runtime observation. It separates two concerns the current system conflates: (1) invoking a DOT (does not exist), (2) recording a correlated run (now exists, no-execute).

Layered design

caller (next-macro runner or operator harness)
   │  mints process_run_id + correlation_id
   ▼
[GATE]  fn_dot_iu_operator_runtime_enabled()  +  process_dot_runtime.execute_enabled   ← both false today ⇒ no-execute
[GATE]  fn_assert_safe_for_dot_action()        ← preflight BLOCK aborts
[LEASE] fn_dot_iu_runtime_lease_acquire('dot_exec:<pair>', holder, ttl)  ← single-flight
   ▼
fn_process_run_observe(...)        → process_run_observation  (header, 1 per run)
   │
   ├─ (DOT invocation step — NOT IMPLEMENTED; only here would agent_api be called)
   │
fn_process_component_observe(...)  → process_component_observation (producer)
fn_process_component_observe(...)  → process_component_observation (verifier)
   ▼
(optional) event_outbox row  ← only if matching process.* event_type active (all inactive ⇒ skipped today)

Inputs (generic)

dot_code · process_candidate_code · process_run_id · correlation_id · parent_run_id? · evidence_type · dry_run flag · fixture/input_ref · idempotency_key · actor.

Outputs

process_run_observation row · process_component_observation row(s) · optional event_outbox row · output_ref · status · error_ref · returned run/component uuid.

Status model (mapped to live CHECK domains)

wrapper status	stored status	stored evidence_type
prepared	observed	SIMULATED_DRY_RUN (+ evidence_ref.wrapper_phase='prepared')
started	started / step_started	per run mode
completed	completed / step_completed	per run mode
failed	failed	per run mode
skipped	cancelled (+ evidence_ref.skipped=true)	unchanged
blocked	not inserted; raises check_violation (gate refusal)	n/a

prepared/skipped/blocked are not in the status CHECK; they are represented via existing values + evidence_ref flags so the domain stays honest. Optional CHECK-amendment packet in doc 07 if first-class states are ever wanted.

Safety contract (enforced by the live functions)

• No production mutation in dry_run — the functions are pure inserts into observation tables; they cannot call agent_api, cannot touch universal_edges/business tables.
• No REAL_RUN unless explicitly allowed — evidence_type='REAL_RUN' raises check_violation unless process_dot_runtime.real_run_enabled='true' (currently false). Proven in rehearsal.
• Dry-run cannot mark verified — verification is computed by v3 views from v2 has_real_runtime + cross_component_correlation, never from simulated/dry counts (doc 07).
• Idempotent rerun — partial-unique idempotency_key + ON CONFLICT DO NOTHING; re-call returns the existing uuid.
• Fail-closed — dot_code must exist in dot_tools; actor required; correlation_id required.

What the wrapper deliberately does NOT include yet

The DOT-invoking step (the agent_api call). That is the runner. Until it exists, every observation the wrapper can produce is SIMULATED_DRY_RUN (ledger proof) — never DRY_RUN (true plan-mode execution) or REAL_RUN.