9000x — Piece Event Runtime roadmap

Status: ROADMAP-ONLY (no live event runtime implementation).

Event types (proposed)

Event	Trigger	Required payload
piece_created	fn_iu_create success	iu_id, canonical_address, actor, ts
piece_updated	fn_iu_metadata_refresh / content edit	iu_id, version_seq, actor, ts
piece_split	fn_iu_piece_split (when shipped)	src_iu_id, child_iu_ids[], actor, ts
piece_merged	fn_iu_piece_merge (when shipped)	dst_iu_id, src_iu_ids[], merge_set_id, actor, ts
piece_retired	fn_iu_retire (mig 026)	iu_id, actor, reason, ts
piece_superseded	fn_iu_supersede (mig 026)	old_iu_id, new_iu_id, actor, reason, ts

Architecture

dot_iu_*  ─►  fn_iu_*  ─►  iu_piece_event (INSERT)
                                  │
                                  ▼
                          route_worker (existing seam)
                                  │
                                  ▼
                          piece_event_handler (new)
                                  │
                                  ▼
                          dead-letter + healthcheck.piece_events

Substrate gaps

1. PG event table. No piece_* event types yet. Proposed mig 029:

   • piece_event_type enum (the 6 types above);
   • public.iu_piece_event(id, event_type, payload_jsonb, created_at, …);
   • per-fn INSERT inside fn_iu_create, fn_iu_retire, fn_iu_supersede, and the future fn_iu_piece_split / fn_iu_piece_merge.

2. Route worker spec. The existing cutter_agent/iu_core/route_worker.py is general-purpose; a piece_event_handler.py would register:

   • piece_created → audit-only;
   • piece_split → enqueue Qdrant re-onboarding for children + retire of src vectors (via the 9000x driver's --rollback-on-actor pattern);
   • piece_merged → onboarding for dst + retire of src vectors;
   • piece_retired / piece_superseded → enqueue vector retire.

3. Dead-letter + healthcheck. Add an 8th surface piece_events to cutter_agent/iu_core/healthcheck.py (counts pending / failed / replayed_24h). Add public.iu_piece_event_dead_letter for events the handler refuses.

Out of scope for this macro

• No PG triggers added.
• No new event tables created.
• No modification to VectorPoint.payload() to embed actor (would unlock filter-based rollback but requires modifying vector_sync.py and re-onboarding existing 149 points — deferred to a future macro).

Carry-forward when ready

1. Mig 029: event types + table.
2. Mig 030: insert hooks inside fn_iu_{create,retire,supersede} + new fn_iu_piece_{split,merge}.
3. piece_event_handler.py + register on route_worker.
4. Add piece_events surface to healthcheck.py.
5. (Optional) add actor to VectorPoint.payload() + re-onboard 149 pts to unlock filter-based rollback.