feat(v1.1.1-triggers): triggers + outbox schema + repos

Migrations 0008-0011 lay down the triggers framework's storage:

- `triggers` + `kv_trigger_details` + `dead_letter_trigger_details`
  (Layout E, design notes §2). Parent table carries common columns
  including `registered_by_principal` — the dispatcher uses this to
  run the trigger as the user that registered it (design notes §4).
- `outbox`: universal async dispatch substrate. KV/cron/pubsub/queue/
  email/dead-letter all write rows in the same shape; the dispatcher
  claims due rows via FOR UPDATE SKIP LOCKED. `reply_to` is the
  NATS-style inbox id for sync HTTP (commit 6) — its presence flags
  "don't retry" per the design.
- `dead_letters`: exact schema from design notes §4 with the four-
  value `resolution` CHECK constraint (`replayed | ignored |
  handled_by_script | handler_failed`) and partial index on
  unresolved rows for the dashboard badge.
- `abandoned_executions`: forensic table for the dispatcher's
  "tried to resolve a dropped inbox" edge case (design notes §3 #9).

Repo surfaces with Postgres impls behind traits so unit tests can
swap in-memory backings:
- `TriggerRepo` — CRUD + the `list_matching_kv` /
  `list_matching_dead_letter` hot paths the dispatcher uses.
  Includes a `collection_matches` helper that handles `*`, `prefix:*`,
  and exact-name globs.
- `OutboxRepo` — insert + claim-due + delete + reschedule.
- `DeadLetterRepo` — insert + get + list + unresolved-count +
  resolve + GC.
- `AbandonedRepo` — insert + GC.

`TriggerConfig::from_env` (new module) follows the existing
`SandboxCeiling` env-loading pattern for `PICLOUD_MAX_TRIGGER_DEPTH`,
`PICLOUD_TRIGGER_RETRY_*`, `PICLOUD_DEAD_LETTER_RETENTION_DAYS`, and
`PICLOUD_ABANDONED_EXECUTIONS_RETENTION_DAYS`.

`Capability::AppManageTriggers(AppId)` and `AppDeadLetterManage(AppId)`
join the enum. Both map onto the existing `Scope::AppAdmin` per the
seven-scope commitment; `role_satisfies` grants them at the
`AppAdmin` per-app role.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-01 21:46:45 +02:00
parent 6b99f74c48
commit 545d863199
11 changed files with 1651 additions and 3 deletions

View File

@@ -0,0 +1,64 @@
-- v1.1.1: Universal trigger outbox — design notes §2.
--
-- One table for every async dispatch in the system. KV/cron/pubsub/
-- queue/email/dead-letter all write rows in this shape; the dispatcher
-- claims due rows with `FOR UPDATE SKIP LOCKED` and routes them to
-- the executor.
--
-- Sync HTTP also writes here (NATS-style inbox, design notes §3) —
-- `reply_to` carries an `inbox_id` that the orchestrator awaits on a
-- oneshot channel. `reply_to.is_some()` is the "don't retry" signal:
-- one attempt, surface the result via the inbox.
--
-- `trigger_id` is a polymorphic reference discriminated by
-- `source_kind`: for `source_kind='http'` it references `routes.id`;
-- otherwise it references `triggers.id`. Polymorphism handled in
-- Rust (the dispatcher); no DB-level FK because Postgres doesn't
-- support polymorphic FKs cleanly. NULL is allowed because direct
-- admin-replay paths may not have a triggering row at all.
--
-- `script_id` denormalized so the dispatcher resolves the target
-- script without an extra round-trip per row.
CREATE TABLE outbox (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
app_id UUID NOT NULL REFERENCES apps(id) ON DELETE CASCADE,
source_kind TEXT NOT NULL
CHECK (source_kind IN ('http', 'kv', 'dead_letter')),
-- Polymorphic — see comment above. No FK constraint.
trigger_id UUID,
-- Pre-resolved at write time so the dispatcher doesn't re-look it up.
script_id UUID,
-- NULL = async (retry per policy). Some(inbox_id) = sync HTTP
-- (never retry; resolve the inbox with the result).
reply_to UUID,
-- ServiceEvent + ExecRequest scaffold serialized as JSONB.
payload JSONB NOT NULL,
-- Forensic field — the principal that triggered the originating
-- event. NOT the execution principal for trigger fan-out (that
-- comes from `triggers.registered_by_principal`).
origin_principal UUID,
-- Trigger-depth as the dispatcher will hand it to the executor.
-- Read out into ExecRequest.trigger_depth at dispatch time.
trigger_depth INT NOT NULL DEFAULT 0,
-- Originating execution id (for audit log grouping). Equals the
-- root for direct invocations; preserved across fan-out chains.
root_execution_id UUID,
attempt_count INT NOT NULL DEFAULT 0,
next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-- Set inside the SELECT FOR UPDATE SKIP LOCKED transaction so
-- the dispatcher can't double-pick a row across concurrent loop
-- iterations.
claimed_at TIMESTAMPTZ,
claimed_by TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
-- Hot index: the dispatcher's `WHERE next_attempt_at <= NOW() AND
-- claimed_at IS NULL` claim query. Partial index keeps the hot set
-- small even if the table grows large.
CREATE INDEX idx_outbox_due
ON outbox (next_attempt_at)
WHERE claimed_at IS NULL;
CREATE INDEX idx_outbox_app ON outbox (app_id);