feat(stateful-templates): journey + docs + concurrency fix; email deferred (M5.6)

- 0063: partial unique index on (app_id, materialized_from) + ON CONFLICT DO
  NOTHING in the reconciler, so a materialized copy is idempotent under
  concurrent reconciles (two parallel app-creates no longer duplicate a copy).
- stateful_templates journey: a group cron template + a descendant app → a
  materialized cron copy in `pic triggers ls --app`; re-apply is a NoOp.
- docs (§4.5 + CLAUDE.md): cron+queue materialization implemented; group EMAIL
  templates deferred (per-descendant inbound-secret reseal needs the master key
  threaded through the hooks + a secret-ref schema) and cleanly rejected at
  apply for now, alongside a `materialized` ls column.

Completes the v1.2 near-term batch (M1-M5, cron+queue); group email is the one
scoped follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-07-01 21:54:34 +02:00
parent ddb3589c49
commit aa5bb3e8cc
7 changed files with 164 additions and 8 deletions

View File

@@ -390,10 +390,23 @@ Two distinct constraints:
> matches its own triggers **plus** ancestor-group templates in one query, the handler running under the
> firing app's `app_id` (the Phase-4 boundary). **That walk is the isolation boundary**: a
> sibling-subtree app never sees the template (pinned by `tests/group_trigger_templates.rs`). Authoring
> is `[[triggers.kv]]` (etc.) on a `[group]`; read-only `pic triggers ls --group`. **Deferred:** the
> **stateful** kinds (cron `last_fired_at`, queue advisory-lock, email sealed secret) need per-app rows
> → materialization, rejected on a `[group]`; per-app opt-out / cross-owner dedup (a descendant
> re-declaring an identical trigger double-fires — "overlapping triggers coexist").
> is `[[triggers.kv]]` (etc.) on a `[group]`; read-only `pic triggers ls --group`.
>
> **Stateful templates via MATERIALIZATION (✅, M5 — cron + queue).** The stateful kinds can't resolve
> live (each needs a per-app row: cron `last_fired_at`, the queue one-consumer advisory lock), so a group
> `[[triggers.cron]]` / `[[triggers.queue]]` template is **materialized** into an app-owned copy per
> descendant — `materialized_from = template.id` (`0062`) — by `materialize::rematerialize_stateful_templates`.
> That reconciler (all-apps `app_chain` CTE ⋈ group-owned stateful templates, a precise create/delete diff
> that preserves `last_fired_at`) runs full-live at the route-rebuild chokepoints: apply (single + tree),
> app create/delete, group reparent. The dispatch paths are **unchanged** — the scheduler + queue consumer
> gained `AND t.app_id IS NOT NULL`, so a group TEMPLATE is never dispatched directly; only its per-app
> copies are. A queue copy is **skipped-with-warning** when the app already fills that queue's consumer
> slot (the one-consumer invariant). Pinned by `tests/stateful_templates.rs` + the `stateful_templates`
> journey. **Deferred:** **email** templates (per-descendant inbound-secret resolution + resealing needs
> the master key threaded through the materialization hooks + a nullable-ciphertext / secret-ref schema —
> a bounded follow-up; a `[group]` email template is cleanly rejected at apply for now); a per-app
> `materialized` column in `pic triggers ls --app`; cross-owner dedup (a descendant re-declaring an
> identical trigger double-fires — "overlapping triggers coexist").
>
> **Shipped — group ROUTE templates (live, inherited).** The same live model, adapted to routes. A
> `[group]` declares a `[[routes]]` template binding a group-owned endpoint; `routes` gained a