T-023 — Automations engine v1: spend-cap rules, trigger/condition/action
T-023 — Automations engine v1: spend-cap rules, trigger/condition/action
Frozen spec for the T-023 build (base main → head of the build). The flagship automation the market expects: pause the ad when spend crosses the cap — implemented per docs/42-automation-architecture.md §2 (the pre-drawn research design), sandbox-only executors.
Decisions
- Scope (Q1): scopeType campaign + account (adset reserved); all four
trigger types ship — metricThreshold, spendCap (fires once), schedule
(UTC dayparting, start==end means full-day), event (manual fire via
POST /v1/rules/{id}/fireuntil the trigger bus wires it). Account-scope campaign actions are notify-only in v1. - Implementer — approvals: rule approvals live in
rule_actionswith statepending_approval(GET/v1/rules/approvals, POST.../confirm|/dismiss), NOT a second approvals table — deviation from the docs/42 §2.2 sketch recorded; the unified queue is T-028's concern and T-035's workflow_approvals stays untouched. Confirm executes exactly the captured payload; never re-evaluates. - Implementer — worker claim: the tick writes
last_evaluated_atbefore evaluating (SQLite single-writer is the lock);idem_key = ruleId|windowStart|actionTypeis UNIQUE so a crash between execute and commit replays into a skip; worker ticks 15s, wired inservices/api/cmd/adpilot/main.go. - Implementer — TS surface contract:
apps/web-next/etc/web-next.api.mdis generated bynpm run api:report(api-extractor) fromapps/web-next/lib/index.tsand committed — it is the TypeScript contract the review-kit surface gate diffs (the gate refuses with no committed report). - Implementer — migration:
services/api/internal/store/migrations/0007_automations.sql(0006 was taken by the parallel session's T-037).
Surface-area deltas
services/api/internal/domain/automations.go— the closed rule schema and whitelists, the pureEvaluateConditions(no I/O, deterministic),ComputeWindowMetrics(division-by-zero → 0 → false),ScheduleWindowOpenwith overnight wrap,ClampShiftBudget(±20 max, account ceiling).services/api/internal/store/automations.go— rule/run/action CRUD, theidem_keyUNIQUE replay guard, due-scan, daily-cap count.services/api/internal/api/handlers_automations.go— CRUD + simulate (zero side effects) + run history + fire + approvals;EvaluateDueRuleswith cooldown, maxActionsPerDay, consecutiveEvals hysteresis, expiry; sandbox executors (pause/resume/shiftBudget mutate the local campaign store under the same guardrails as the PATCH handlers; notify/tag/audit-only webhookOut stub; regenerateCreative delegates to the sandbox generator).services/api/internal/api/server.go— 11 new rule routes; zero existing routes touched.apps/web-next/app/rules/page.tsx+apps/web-next/lib/api.ts+apps/web-next/lib/types.ts+apps/web-next/lib/demo.ts— the operator page (plain-language builder, simulate, run history, approvals) and the client + demo-engine parity.apps/web-next/app/layout.tsx— nav link.services/api/cmd/adpilot/main.go— worker wiring.- Tests:
services/api/internal/domain/automations_test.go(whitelists, metrics fold, decision fn, dayparting, clamp) andservices/api/internal/api/automations_test.go(CRUD/validation, simulate purity, worker fire + pause, guards, approval round-trip, ceiling clamp, spendCap-once, manual fire + schedule). - Docs/tooling rows:
apps/web-next/.gitignore,apps/web-next/api-extractor.json,apps/web-next/lib/index.ts,apps/web-next/etc/web-next.api.md,apps/web-next/package.json,apps/web-next/package-lock.json, and the card filestasks/00-backlog/T-023-automations-engine.md/tasks/10-in-progress/T-023-automations-engine.md.
Verification
Go gates: go test ./... in services/api (6/6 packages; 13 new test
functions). Web gate: npm run build in apps/web-next (strict tsc). Live
E2E on :8090: rule created → simulate explains → the real 15s worker fired →
campaign paused → run history "fired"; a shiftBudget rule with
requiresApproval queued pending, budget untouched at 40, confirm applied 48,
double-confirm 422.
Out of scope
Real ad-platform calls (sandbox rule; a real executor implements the same dispatch behind a credentials-gated card), the NL rule parser (T-028), the unified approvals table (T-028), outbound webhook delivery (T-027).