KB-7482

IU Core Structure-Event/Tree Scale — 06 Delivery seam next-step package

4 min read Revision 1
dieu44iu-core-mvpstructure-eventdelivery-seamdry-run-falsenext-stepv0.62026-05-22

06 — Delivery Seam Next-step Package

The route worker now produces real dry_run decisions for structure events. The remaining gap to actual delivery is the unbuilt fn_iu_route_deliver seam. This package scopes the dry_run=false macro. Nothing here is executed.

Current state

  • fn_iu_route_deliver(text,uuid,jsonb) RAISEs feature_not_supported — any dry_run=false route would dead-letter every event. No downstream delivery is possible.
  • Route iu.structure_op_applied.workflow is enabled=true, dry_run=true.
  • The CHECK iu_outbound_route_safe_chk (enabled=false OR dry_run=true) makes an enabled+dry_run=false route structurally impossible to seed today.

Real target contract (to be built)

target_kind='workflow', target_ref='event_outbox' is the seeded contract. The first real delivery target should be the lowest-blast-radius sink:

  1. Recommended — sql_function target. A new idempotent fn_iu_structure_consumer(event_ref uuid, safe_payload jsonb) that records an IU-tree-change projection (e.g. a iu_tree_change_log row). Delivery stays inside PostgreSQL; no external endpoint, no network. Idempotent on event_ref.
  2. Alternative — a Directus flow trigger (target_kind='directus_flow'): higher blast radius, touches the Directus layer.
  3. Not recommended for the first cut — external_endpoint: network egress, secret handling, retry/backoff — defer.

Route CHECK relaxation plan

iu_outbound_route_safe_chk must be relaxed to permit ONE specifically approved enabled+dry_run=false route. Options:

  • Preferred: keep the table CHECK; instead add a per-route allowlist — a dot_config key (e.g. iu_core.delivery_live_routes CSV) that fn_iu_route_worker_run consults, plus a partial-unique or trigger guard so only an allowlisted route_code may go dry_run=false. The blanket CHECK stays; the relaxation is per-route, config-gated, reversible.
  • Avoid: dropping iu_outbound_route_safe_chk outright (removes the structural guard for every route).

dry_run=false gate package

A new dedicated kill-switch dot_config 'iu_core.delivery_enabled' (fail-closed) gating fn_iu_route_deliver, independent of the master / worker gates — so delivery can be armed and disarmed without touching event emission or the worker.

Rollback / disable package (must exist before the macro runs)

  • fn_iu_route_deliver rollback = CREATE OR REPLACE back to the RAISE stub.
  • Route -> dry_run=true (or enabled=false).
  • Close iu_core.delivery_enabled.
  • Dead-letter replay (fn_iu_route_dead_letter_replay) for any event delivered in error — already exists.
  • The delivered projection (e.g. iu_tree_change_log) must itself be truncatable / reversible.

Sovereign approval required

dry_run=false is a forbidden action for the current macro family and needs an explicit sovereign macro: backup -> build seam + consumer -> relax CHECK per-route -> arm delivery_enabled -> bounded worker run -> verify -> disable. Blast radius is strictly larger than dry-run; treat as a separate gated macro.

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/v0.6-iu-core-structure-event-tree-autocut-worker-scale-open-goal/06-delivery-seam-next-step.md