03 · cut.* heartbeat caller — fn_cut_heartbeat_ping

Goal

After mig 052 the only heartbeat tick for the cut pipeline was a single dieu45_phase3_pilot row (Phase 3 pilot trace). The iu_outbound_default PG_worker marker remained stale since 2026-05-22 (§15.5 silent gap). For batch/high-frequency cutting we need:

• a stable executor identity for the cut pipeline operator;
• an idiomatic ping function reachable from the operator workflow;
• strict protection of the legacy iu_outbound_default marker from false-heal (per [[feedback-protect-legacy-silent-passive-heartbeat-from-false-heal]]).

Design choice

External-operator-ping wrapper (HC-pattern, Option B-equivalent) — a thin SECURITY DEFINER function over the primitive fn_queue_heartbeat_tick. The primitive remains permissive (it's a generic UPSERT); the wrapper adds the policy.

Surface

public.fn_cut_heartbeat_ping(
  p_executor_name text,
  p_executor_kind text DEFAULT 'external_worker',
  p_status        text DEFAULT 'ok',
  p_metadata      jsonb DEFAULT '{}'::jsonb
) RETURNS jsonb
SECURITY DEFINER
SET search_path = public, pg_temp;

Granted to workflow_admin only.

Policy (top to bottom)

pre-check	refusal mode	example
p_executor_name non-empty	RAISE	'fn_cut_heartbeat_ping: p_executor_name required'
p_executor_name = 'iu_outbound_default'	JSON {refused:true, reason:'protected_legacy_silent_passive'} (NOT RAISE)	preserves §15.5 marker; no false-heal
p_executor_kind ∈ 7-vocab (DOT/Agent/Hermes/Codex/PG_worker/external_worker/future_Kestra_adapter)	RAISE	MOT excluded by design
p_status ∈ {ok,warn,error}	RAISE	matches queue_heartbeat CHECK
dot_config.queue.heartbeat.enabled = 'true'	JSON {skipped:true}	gate-off respected; no silent write
else	invoke fn_queue_heartbeat_tick	metadata augmented with ping_origin, ping_function, ping_actor, ping_at

Refusal style for iu_outbound_default is intentionally JSON-return (not RAISE) so the caller observes a clear refusal-with-reason rather than an exception that could mask a deeper problem. The downstream tick is never invoked, so the legacy row's last_tick_at never advances from the wrapper.

Audit pin

Every wrapper-driven tick carries metadata:

{
  "ping_origin":   "cut_pipeline_caller",
  "ping_function": "fn_cut_heartbeat_ping",
  "ping_actor":    "<current_setting('app.actor', true) or 'cut_pipeline_operator_external'>",
  "ping_at":       "<now()>"
}

These keys never collide with the §11.5 metadata-denylist (no body/content/raw/vector/embedding/secret/token/password/ssn/personal_data). This makes it possible to distinguish wrapper-driven ticks from primitive fn_queue_heartbeat_tick direct calls (Phase 2 pattern) when auditing queue_heartbeat.metadata.

Proofs

proof	input	expected	actual
PC.1	('iu_outbound_default','PG_worker','ok','{}')	{refused:true, reason:'protected_legacy_silent_passive'}	match
PC.2	('cut_pipeline_operator_test','external_worker','ok',{phase:'053_proof'})	tick OK, ticks_total=1	match
PC.3	bad executor_kind = 'MOT_invalid'	RAISE not in 7-vocab	match
PC.4	bad status = 'garbled'	RAISE not in {ok,warn,error}	match
PC.5	post-tick queue_heartbeat row exists	row visible	confirmed
E.3 LIVE	('cut_pipeline_operator','external_worker','ok',{mig:'053',phase:'E'})	tick OK, row written	confirmed (durable)
E.4	post-E.3 read-back	3 rows: cut_pipeline_operator, dieu45_phase3_pilot, iu_outbound_default	confirmed
D31.2	re-test PC.1 post-COMMIT	refused=true	confirmed
D31.3	re-test PC.3	RAISE 7-vocab error	confirmed

State at exit

executor_name	kind	status	age	role
cut_pipeline_operator	external_worker	ok	0s (newly ticked)	cut pipeline external caller
dieu45_phase3_pilot	external_worker	ok	~2h	Phase 3 pilot trace
iu_outbound_default	PG_worker	warn	~101h (frozen 2026-05-22)	§15.5 legacy silent marker, protected

Notes & open items

• CF-2: this is a manually-invokable function; no automated caller is yet wired. The actual cut pipeline operator process (Agent / Codex / external script) must call SELECT public.fn_cut_heartbeat_ping(...) at end-of-cycle to advance cut_pipeline_operator's last_tick.
• CF-4: iu_outbound_default remains stale. This pack does not close the §15.5 silent gap durably — Phase 3C (HC pattern Option B for fn_iu_route_worker_run wrapper) remains the proposed closure path.
• Naming convention: cut pipeline executors SHOULD be named cut_pipeline_operator_<scope> (e.g. cut_pipeline_operator_dieu37, cut_pipeline_operator_batch_2026q2) so that one stale row does not silence another.