@exponential_app/engine 0.0.0-stage → 0.1.0

package/dist/types/emcp/fixtures/automations.json

@@ -0,0 +1,521 @@
+{
+  "$comment": "#VAPP-220 (eApps A1, docs/spec/apps.md §7.1, decisions §18.2/§18.4): AN APP'S AUTOMATIONS. A package lists them in `automations: [{name, on, run, sponsor?}]`; the SERVER BROKER runs them on the PUBLISHED package only (V1), unattended, as the automation's SPONSOR. ONE TRIGGER RUNS ONE BINDING: no chains, no branches, no loops; anything with judgement goes to an agent (A2). THE FORMAT: `name` matches `limits.namePattern`, at most `limits.nameMax`, unique in the app; at most `limits.maxAutomations` automations (more = `{index: null, code: tooMany}` first; not a list = `{index: null, code: list}` alone). `on` holds EXACTLY ONE of `triggerKinds` (else `on`, which stops that automation's checks): `schedule` = `{cron, tz?}`: a 5-field cron (`minute hour day-of-month month day-of-week`, the agents' trigger cron: `*`, lists, ranges, steps, month and weekday names), read in `tz` (an IANA zone) or else the TEAM time zone; a cron that is not 5 fields of `cronFieldPattern`, a minute or hour field that does not parse (0-59, 0-23) or a blank `tz` = `schedule`; the minutes of a day it fires on (minute × hour, circular over the day) closer than `limits.minScheduleGapMinutes` apart = `scheduleTooOften`. `record` = `{kind, op}`: `kind` one the manifest declares (else `kind`), `op` one of `recordTriggerOps` (else `on`). `event` = a team event NAME (the agents' event triggers' stream: the server's `issue.created`, `pr.merged`, `session.ended`… or any `events_emit` name) matching `limits.eventPattern`, at most `limits.eventMax` (else `event`). `sponsor` (optional) = a member's email (a string holding `@`, else `sponsor`). `run` = an `exposes`-style run (exposes.json: exactly one of `records`, `action`, `upstream`, the same codes: `run`, `kind`, `action`, `destructive`, `ownerOnly`, `upstream`); an action reaching an app (`exponential_apps_*`) = `chain` (an automation never reaches an app, its own included, through the apps noun). TEMPLATES: every string of `run` may hold `${record.<path>}` (a record trigger only: the record's data + `id`; on delete, the data it had), `${event.<path>}` (an event trigger only: the event's payload + `name`) and `${firedAt}` (every trigger: the run's ISO instant); any other `${…}`, or a root the trigger does not carry, = `template`. Resolution = exposes.json's `resolveArgs` over the input `{record?, event?, firedAt}` after `toInputTemplates` rewrites each root to `${input.<root>…}` (`resolveCases`). VALIDATION = `validateAutomations(list, {kinds, upstreams})` → every `{index, code}` in order (`validateCases`, codes = `errors`). MATCHING (`matchCases`): a record write or an event names the automations it fires, in package order: a record trigger whose kind and op equal the write's, an event trigger whose name equals the event's; a schedule is never matched here (the watchdog tick finds the latest due minute since the last check, the agents' `latestCronMatch`, caught up once after downtime, never twice). LOOP GUARD: a write or event caused BY an automation run (`fromAutomation: true`: the run's records write, the events its action emits) fires NOTHING, so an automation never triggers another one or itself. SPONSOR (C23, `sponsorCases`): `resolveSponsor({declared, publishedBy, members})` where `members` = the team's current members `{id, email, role, level}` (`level` = the member's app access, Settings › MCP Access: `none` | `read` | `write`). The publisher = the member whose id = `publishedBy` (the member who published the running version). No `declared` sponsor → the sponsor is the publisher. A `declared` email naming someone other than the publisher is honoured only when the publisher is a team `owner` (an owner may delegate; a member never makes an automation act as someone else) → else `sponsorNotAllowed`. A sponsor who is not (or no longer) a member, or no publisher at all = `sponsorGone`; a sponsor whose level is not `write` = `sponsorReadOnly`. Any of those PAUSES the automation (it does not run; the app's owners get ONE notification per pause) until a publish resolves it. RATE: at most `limits.runsPerMinute` runs per app per rolling minute (the app's `automation:*` audit rows of the last 60 s); a run over the cap is not started and is audited `rateLimited` (`rateCases`). AUDIT (`auditCases`): every run (and every refusal) = one `mcp_calls` row (audit.json) with `user_id` = the sponsor (a paused run: the publisher, else the app's creator), `app_id` = the app, `client_id` = `clientPrefix` + name, `tool` = `automationTool(run)`: `records.<op>:<kind>`, the action name, or `<upstream>/<tool>`; its writes read \"via <app>\" (§9.3). The app's Settings › Automations lists each automation with its trigger, its newest audit row (last run, last failure) and the runs dropped in the last 24 h (#VAPP-255, its `rateLimited` rows; a dropped run is not retried), from those rows. AGENT HAND-OFF (#VAPP-236, A2, spec §7.3): `run` may be exposes.json's `agent` form `{agent, prompt, device?}` (the same checks and codes: `agent`, `prompt`, `run`); its `prompt` holds the trigger's templates (`${record.<path>}`, `${event.<path>}`, `${firedAt}`, checked like every run string) and the server renders exposes.json's `agentBrief` over the input `{record?, event?, firedAt}` (after `toInputTemplates`), `source` = `automation <name>`, `ref` = `{kind, id}` of a record trigger's record; it runs as the SPONSOR through `sessions.send {agentId}` (the sponsor's conversation with that agent), the session reading `via <app>`, under exposes.json's hand-off cap as well as `limits.runsPerMinute`; its audit `tool` = `agent:<slug>` (`auditCases`). AGENT LOOP GUARD (`matchCases` with `byAgent`): a record write or an event caused from inside an AGENT's session tree (the acting agent of the causing session's root: its conversation agent, else the agent that started it) carries that agent's slug as `byAgent`; it never fires an automation whose run hands off to THAT agent, so an agent an automation woke never re-triggers it (nor any other hand-off to itself); every other automation still fires. INBOUND WEBHOOKS (#VAPP-237, A3, spec §7.2, §12.3, decision C22): `on: {webhook: {name}}` = the server's `POST` at `webhook.path` (`{appId}` = the app's id, `{name}` = the hook name). `name` matches `limits.namePattern`, at most `limits.nameMax`, unique among the app's webhook automations (else `webhook`); templates read `${event.<path>}` and `${firedAt}` (`templateRoots.webhook`), the event = `{hook: <name>, body: <the parsed JSON body>}`, so `${event.body.data.customer}` (`webhookEvent`). A delivery MATCHES (`matchCases` with `{webhook: name}`) the automations on that hook name. THE SECRET: one per hook (app + name), `webhook.secretPrefix` + base64url (no padding) of `webhook.secretBytes` random bytes, minted by a team OWNER on the app's Settings (shown ONCE, copyable; minting again = ROTATE: the old one stops at once), stored only vault-sealed (vault.json `ev1`, slot `app_hooks.secret_ciphertext.<row id>`), never synced, re-sealed by the vault sweep. A hook without a secret refuses every delivery (`unknownHook`). THE SIGNATURE (`signatureCases`): header `webhook.header` = `t=<unix seconds>,v1=<lowercase hex HMAC-SHA256(secret, \"<t>.\" + the raw body bytes as UTF-8)>` (`webhookSignature`; several `v1=` may ride along, any one matching counts; whitespace around parts is ignored; another key is ignored). VERIFICATION (`verifyCases`, `verifyWebhook({header, body, bytes, secret, now, seen})`), in this order, the first failure answers: the body over `webhook.bodyMax` bytes = `tooLarge`; no header = `missingSignature`; a header without exactly one `t` (1-12 digits) or without a `v1` of 64 lowercase hex characters = `badSignature`; `|now - t|` over `webhook.toleranceSeconds` = `stale`; no `v1` equal (constant time) to the HMAC = `badSignature`; the matching `v1` (the NONCE) already in the hook's nonce cache (`seen`: every accepted nonce of the last 2 × `toleranceSeconds`) = `replayed`; a body that is not JSON = `notJson`; else `{ok, nonce, body}` (the body parsed only after the signature verified). Each refusal answers its `webhook.httpStatus` (a verified delivery: 202 with the run's status). RATE: at most `webhook.callsPerMinute` deliveries per hook per rolling minute (its audit rows), over it = 429 `rateLimited`, NOT audited (a flood never fills the audit table). AUDIT: every delivery under the cap = one `mcp_calls` row `client_id = automation:<name of each matched automation>` like every run; a refused one (signature, window, replay, size, JSON) is audited `denied` with the code as `error` under the hook's first automation, as the publisher (else the app's creator). The run itself is A1's (`runAutomation`: the sponsor, the app cap, the published package).",
+  "limits": {
+    "namePattern": "^[a-z][a-z0-9_]*$",
+    "nameMax": 40,
+    "maxAutomations": 16,
+    "minScheduleGapMinutes": 15,
+    "eventPattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
+    "eventMax": 128,
+    "runsPerMinute": 30,
+    "clientPrefix": "automation:"
+  },
+  "triggerKinds": ["schedule", "record", "event", "webhook"],
+  "recordTriggerOps": ["create", "update", "delete"],
+  "cronFieldPattern": "^[A-Za-z0-9*,/-]+$",
+  "templateRoots": { "schedule": ["firedAt"], "record": ["record", "firedAt"], "event": ["event", "firedAt"], "webhook": ["event", "firedAt"] },
+  "sponsorStates": ["sponsorGone", "sponsorReadOnly", "sponsorNotAllowed"],
+  "errors": ["list", "tooMany", "shape", "name", "duplicate", "on", "schedule", "scheduleTooOften", "kind", "event", "sponsor", "template", "chain", "run", "action", "destructive", "ownerOnly", "upstream", "agent", "prompt", "webhook"],
+  "validateCases": [
+    {
+      "name": "the spec's three automations are valid",
+      "context": { "kinds": ["rotation", "request"], "upstreams": ["stripe"] },
+      "automations": [
+        { "name": "monday_rotation", "on": { "schedule": { "cron": "0 8 * * MON" } }, "run": { "records": { "op": "upsert", "kind": "rotation", "data": { "at": "${firedAt}" } } } },
+        { "name": "notify_approver", "on": { "record": { "kind": "request", "op": "create" } }, "run": { "action": "exponential_comments_create", "args": { "userId": "${record.approver}", "text": "${record.title}" } } },
+        { "name": "merged", "on": { "event": "pr.merged" }, "sponsor": "lead@acme.test", "run": { "upstream": "stripe", "tool": "create_note", "args": { "text": "${event.title}" } } }
+      ],
+      "expected": []
+    },
+    {
+      "name": "a schedule in its own zone, every quarter hour",
+      "context": { "kinds": [], "upstreams": [] },
+      "automations": [{ "name": "tick", "on": { "schedule": { "cron": "*/15 9-17 * * mon-fri", "tz": "Europe/Vienna" } }, "run": { "action": "exponential_comments_create", "args": { "text": "tick" } } }],
+      "expected": []
+    },
+    {
+      "name": "not a list",
+      "context": { "kinds": [], "upstreams": [] },
+      "automations": { "name": "x" },
+      "expected": [{ "index": null, "code": "list" }]
+    },
+    {
+      "name": "names: pattern, duplicate, not an object",
+      "context": { "kinds": ["a"], "upstreams": [] },
+      "automations": [
+        { "name": "Bad-Name", "on": { "record": { "kind": "a", "op": "create" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "ok", "on": { "record": { "kind": "a", "op": "create" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "ok", "on": { "record": { "kind": "a", "op": "update" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        "nope"
+      ],
+      "expected": [
+        { "index": 0, "code": "name" },
+        { "index": 2, "code": "duplicate" },
+        { "index": 3, "code": "shape" }
+      ]
+    },
+    {
+      "name": "on: none, two, an unknown record op",
+      "context": { "kinds": ["a"], "upstreams": [] },
+      "automations": [
+        { "name": "none", "on": {}, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "two", "on": { "event": "pr.merged", "record": { "kind": "a", "op": "create" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "op", "on": { "record": { "kind": "a", "op": "upsert" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } }
+      ],
+      "expected": [
+        { "index": 0, "code": "on" },
+        { "index": 1, "code": "on" },
+        { "index": 2, "code": "on" }
+      ]
+    },
+    {
+      "name": "schedules: four fields, a bad hour, a blank zone, every minute, every five minutes, two close minutes across midnight",
+      "context": { "kinds": [], "upstreams": [] },
+      "automations": [
+        { "name": "s1", "on": { "schedule": { "cron": "0 8 * *" } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s2", "on": { "schedule": { "cron": "0 25 * * *" } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s3", "on": { "schedule": { "cron": "0 8 * * *", "tz": " " } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s4", "on": { "schedule": { "cron": "* * * * *" } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s5", "on": { "schedule": { "cron": "*/5 8 * * *" } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s6", "on": { "schedule": { "cron": "5,55 0,23 * * *" } }, "run": { "action": "exponential_comments_create" } },
+        { "name": "s7", "on": { "schedule": "0 8 * * *" }, "run": { "action": "exponential_comments_create" } }
+      ],
+      "expected": [
+        { "index": 0, "code": "schedule" },
+        { "index": 1, "code": "schedule" },
+        { "index": 2, "code": "schedule" },
+        { "index": 3, "code": "scheduleTooOften" },
+        { "index": 4, "code": "scheduleTooOften" },
+        { "index": 5, "code": "scheduleTooOften" },
+        { "index": 6, "code": "schedule" }
+      ]
+    },
+    {
+      "name": "an undeclared trigger kind, a bad event name, a sponsor that is no email",
+      "context": { "kinds": ["a"], "upstreams": [] },
+      "automations": [
+        { "name": "k", "on": { "record": { "kind": "b", "op": "create" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "e", "on": { "event": "PR Merged" }, "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } },
+        { "name": "p", "on": { "event": "pr.merged" }, "sponsor": "danny", "run": { "records": { "op": "upsert", "kind": "a", "data": {} } } }
+      ],
+      "expected": [
+        { "index": 0, "code": "kind" },
+        { "index": 1, "code": "event" },
+        { "index": 2, "code": "sponsor" }
+      ]
+    },
+    {
+      "name": "templates: a root the trigger lacks, an unknown root, input",
+      "context": { "kinds": ["a"], "upstreams": [] },
+      "automations": [
+        { "name": "t1", "on": { "schedule": { "cron": "0 8 * * *" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": { "x": "${record.x}" } } } },
+        { "name": "t2", "on": { "event": "pr.merged" }, "run": { "records": { "op": "upsert", "kind": "a", "data": { "x": "${now}" } } } },
+        { "name": "t3", "on": { "record": { "kind": "a", "op": "create" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": { "x": "by ${input.x}" } } } },
+        { "name": "t4", "on": { "record": { "kind": "a", "op": "delete" } }, "run": { "records": { "op": "upsert", "kind": "a", "data": { "was": "${record.id}", "at": "${firedAt}" } } } }
+      ],
+      "expected": [
+        { "index": 0, "code": "template" },
+        { "index": 1, "code": "template" },
+        { "index": 2, "code": "template" }
+      ]
+    },
+    {
+      "name": "runs: the exposes codes, and no chaining through the apps noun",
+      "context": { "kinds": ["a"], "upstreams": ["stripe"] },
+      "automations": [
+        { "name": "r1", "on": { "event": "x" }, "run": { "records": { "op": "delete", "kind": "a", "id": "1" } } },
+        { "name": "r2", "on": { "event": "x" }, "run": { "records": { "op": "upsert", "kind": "zz", "data": {} } } },
+        { "name": "r3", "on": { "event": "x" }, "run": { "action": "exponential_issues_delete", "args": { "id": "${event.issueId}" } } },
+        { "name": "r4", "on": { "event": "x" }, "run": { "action": "exponential_apps_records_upsert", "args": {} } },
+        { "name": "r5", "on": { "event": "x" }, "run": { "upstream": "github", "tool": "comment" } },
+        { "name": "r6", "on": { "event": "x" }, "run": { "records": { "op": "upsert", "kind": "a" }, "action": "exponential_issues_create" } },
+        { "name": "r7", "on": { "event": "x" }, "run": { "action": "nope" } }
+      ],
+      "expected": [
+        { "index": 0, "code": "destructive" },
+        { "index": 1, "code": "kind" },
+        { "index": 2, "code": "destructive" },
+        { "index": 3, "code": "chain" },
+        { "index": 4, "code": "upstream" },
+        { "index": 5, "code": "run" },
+        { "index": 6, "code": "action" }
+      ]
+    },
+    {"name": "an agent hand-off on a record create, and its refusals", "context": {"kinds": ["request"], "upstreams": []}, "automations": [{"name": "route_request", "on": {"record": {"kind": "request", "op": "create"}}, "run": {"agent": "triage", "prompt": "Route the request ${record.title} (filed ${firedAt})."}}, {"name": "bad_agent", "on": {"event": "pr.merged"}, "run": {"agent": "Triage", "prompt": "", "device": "phone"}}, {"name": "bad_root", "on": {"schedule": {"cron": "0 9 * * *"}}, "run": {"agent": "triage", "prompt": "Daily: ${record.title}"}}], "expected": [{"index": 1, "code": "agent"}, {"index": 1, "code": "prompt"}, {"index": 1, "code": "run"}, {"index": 2, "code": "template"}]},
+    {"name": "webhooks: a valid hook, a bad name, a hook used twice, a root it does not carry", "context": {"kinds": ["payment"], "upstreams": []}, "automations": [{"name": "stripe_paid", "on": {"webhook": {"name": "stripe"}}, "run": {"records": {"op": "upsert", "kind": "payment", "data": {"customer": "${event.body.data.customer}", "at": "${firedAt}"}}}}, {"name": "bad_hook", "on": {"webhook": {"name": "Stripe-Hook"}}, "run": {"records": {"op": "upsert", "kind": "payment", "data": {}}}}, {"name": "twice", "on": {"webhook": {"name": "stripe"}}, "run": {"records": {"op": "upsert", "kind": "payment", "data": {}}}}, {"name": "no_record", "on": {"webhook": {"name": "github"}}, "run": {"records": {"op": "upsert", "kind": "payment", "data": {"x": "${record.id}"}}}}, {"name": "not_object", "on": {"webhook": "stripe"}, "run": {"records": {"op": "upsert", "kind": "payment", "data": {}}}}], "expected": [{"index": 1, "code": "webhook"}, {"index": 2, "code": "webhook"}, {"index": 3, "code": "template"}, {"index": 4, "code": "webhook"}]}
+  ],
+  "tooManyCase": { "count": 17, "expected": [{ "index": null, "code": "tooMany" }] },
+  "matchCases": [
+    {
+      "name": "a record create fires the create automations of its kind, in order",
+      "automations": [
+        { "name": "a", "on": { "record": { "kind": "request", "op": "create" } } },
+        { "name": "b", "on": { "record": { "kind": "request", "op": "update" } } },
+        { "name": "c", "on": { "record": { "kind": "other", "op": "create" } } },
+        { "name": "d", "on": { "event": "request.create" } },
+        { "name": "e", "on": { "schedule": { "cron": "0 8 * * *" } } },
+        { "name": "f", "on": { "record": { "kind": "request", "op": "create" } } }
+      ],
+      "trigger": { "record": { "kind": "request", "op": "create" } },
+      "fromAutomation": false,
+      "expected": ["a", "f"]
+    },
+    {
+      "name": "an event fires the automations on its name",
+      "automations": [
+        { "name": "a", "on": { "event": "pr.merged" } },
+        { "name": "b", "on": { "event": "pr.opened" } },
+        { "name": "c", "on": { "record": { "kind": "pr", "op": "create" } } }
+      ],
+      "trigger": { "event": "pr.merged" },
+      "fromAutomation": false,
+      "expected": ["a"]
+    },
+    {
+      "name": "LOOP GUARD: an automation's own write fires nothing (not even itself)",
+      "automations": [{ "name": "a", "on": { "record": { "kind": "request", "op": "create" } } }],
+      "trigger": { "record": { "kind": "request", "op": "create" } },
+      "fromAutomation": true,
+      "expected": []
+    },
+    {
+      "name": "LOOP GUARD: an event an automation's action emitted fires nothing",
+      "automations": [{ "name": "a", "on": { "event": "issue.created" } }],
+      "trigger": { "event": "issue.created" },
+      "fromAutomation": true,
+      "expected": []
+    },
+    {
+      "name": "a malformed entry is skipped, never fired",
+      "automations": [{ "name": "a" }, "x", { "name": "b", "on": { "event": "pr.merged" } }],
+      "trigger": { "event": "pr.merged" },
+      "fromAutomation": false,
+      "expected": ["b"]
+    },
+    {"name": "AGENT LOOP GUARD: an agent's own write never fires a hand-off to it", "automations": [{"name": "a", "on": {"record": {"kind": "request", "op": "update"}}, "run": {"agent": "triage", "prompt": "x"}}, {"name": "b", "on": {"record": {"kind": "request", "op": "update"}}, "run": {"agent": "review", "prompt": "x"}}, {"name": "c", "on": {"record": {"kind": "request", "op": "update"}}, "run": {"records": {"op": "upsert", "kind": "log", "data": {}}}}], "trigger": {"record": {"kind": "request", "op": "update"}, "byAgent": "triage"}, "fromAutomation": false, "expected": ["b", "c"]},
+    {"name": "AGENT LOOP GUARD: an event from an agent's tree, and a person's write fires all", "automations": [{"name": "a", "on": {"event": "issue.created"}, "run": {"agent": "triage", "prompt": "x"}}, {"name": "b", "on": {"event": "issue.created"}, "run": {"agent": "review", "prompt": "x"}}], "trigger": {"event": "issue.created", "byAgent": "triage"}, "fromAutomation": false, "expected": ["b"]},
+    {"name": "no acting agent: every hand-off fires", "automations": [{"name": "a", "on": {"event": "issue.created"}, "run": {"agent": "triage", "prompt": "x"}}], "trigger": {"event": "issue.created", "byAgent": null}, "fromAutomation": false, "expected": ["a"]},
+    {"name": "a webhook delivery fires the automations on its hook", "automations": [{"name": "a", "on": {"webhook": {"name": "stripe"}}}, {"name": "b", "on": {"webhook": {"name": "github"}}}, {"name": "c", "on": {"event": "stripe"}}], "trigger": {"webhook": "stripe"}, "fromAutomation": false, "expected": ["a"]}
+  ],
+  "sponsorCases": [
+    {
+      "name": "no declared sponsor: the publisher",
+      "input": { "declared": null, "publishedBy": "u1", "members": [{ "id": "u1", "email": "ann@acme.test", "role": "member", "level": "write" }] },
+      "expected": { "userId": "u1" }
+    },
+    {
+      "name": "the publisher naming themself",
+      "input": { "declared": "ann@acme.test", "publishedBy": "u1", "members": [{ "id": "u1", "email": "ann@acme.test", "role": "member", "level": "write" }] },
+      "expected": { "userId": "u1" }
+    },
+    {
+      "name": "an owner delegates to another member (emails compare case-blind)",
+      "input": {
+        "declared": "Bob@Acme.test",
+        "publishedBy": "u1",
+        "members": [
+          { "id": "u1", "email": "ann@acme.test", "role": "owner", "level": "write" },
+          { "id": "u2", "email": "bob@acme.test", "role": "member", "level": "write" }
+        ]
+      },
+      "expected": { "userId": "u2" }
+    },
+    {
+      "name": "a member never makes an automation act as someone else",
+      "input": {
+        "declared": "bob@acme.test",
+        "publishedBy": "u1",
+        "members": [
+          { "id": "u1", "email": "ann@acme.test", "role": "member", "level": "write" },
+          { "id": "u2", "email": "bob@acme.test", "role": "owner", "level": "write" }
+        ]
+      },
+      "expected": { "paused": "sponsorNotAllowed" }
+    },
+    {
+      "name": "the publisher left the team",
+      "input": { "declared": null, "publishedBy": "u1", "members": [{ "id": "u2", "email": "bob@acme.test", "role": "owner", "level": "write" }] },
+      "expected": { "paused": "sponsorGone" }
+    },
+    {
+      "name": "nobody published (a deleted account)",
+      "input": { "declared": null, "publishedBy": null, "members": [{ "id": "u2", "email": "bob@acme.test", "role": "owner", "level": "write" }] },
+      "expected": { "paused": "sponsorGone" }
+    },
+    {
+      "name": "the named sponsor is no member",
+      "input": { "declared": "eve@acme.test", "publishedBy": "u1", "members": [{ "id": "u1", "email": "ann@acme.test", "role": "owner", "level": "write" }] },
+      "expected": { "paused": "sponsorGone" }
+    },
+    {
+      "name": "the sponsor's app access is read",
+      "input": { "declared": null, "publishedBy": "u1", "members": [{ "id": "u1", "email": "ann@acme.test", "role": "member", "level": "read" }] },
+      "expected": { "paused": "sponsorReadOnly" }
+    },
+    {
+      "name": "the delegated sponsor's app access is none",
+      "input": {
+        "declared": "bob@acme.test",
+        "publishedBy": "u1",
+        "members": [
+          { "id": "u1", "email": "ann@acme.test", "role": "owner", "level": "write" },
+          { "id": "u2", "email": "bob@acme.test", "role": "member", "level": "none" }
+        ]
+      },
+      "expected": { "paused": "sponsorReadOnly" }
+    }
+  ],
+  "rateCases": [
+    { "runsLastMinute": 0, "allowed": true },
+    { "runsLastMinute": 29, "allowed": true },
+    { "runsLastMinute": 30, "allowed": false },
+    { "runsLastMinute": 31, "allowed": false }
+  ],
+  "resolveCases": [
+    {
+      "name": "a record's fields keep their type when whole, become text inside text",
+      "run": { "action": "exponential_comments_create", "args": { "userId": "${record.approver}", "text": "New request: ${record.title} (${record.hours} h)", "hours": "${record.hours}" } },
+      "input": { "record": { "id": "r1", "approver": "u2", "title": "Leave", "hours": 8 }, "firedAt": "2026-11-03T08:00:00.000Z" },
+      "expected": { "action": "exponential_comments_create", "args": { "userId": "u2", "text": "New request: Leave (8 h)", "hours": 8 } }
+    },
+    {
+      "name": "an event's payload, the instant, a missing field dropped",
+      "run": { "records": { "op": "upsert", "kind": "log", "data": { "pr": "${event.number}", "name": "${event.name}", "at": "${firedAt}", "gone": "${event.nope}" } } },
+      "input": { "event": { "name": "pr.merged", "number": 42 }, "firedAt": "2026-11-03T08:00:00.000Z" },
+      "expected": { "records": { "op": "upsert", "kind": "log", "data": { "pr": 42, "name": "pr.merged", "at": "2026-11-03T08:00:00.000Z" } } }
+    }
+  ],
+  "webhook": {
+    "path": "/api/apps/hooks/{appId}/{name}",
+    "header": "exponential-signature",
+    "secretPrefix": "whsec_",
+    "secretBytes": 32,
+    "toleranceSeconds": 300,
+    "bodyMax": 65536,
+    "callsPerMinute": 60,
+    "errors": [
+      "tooLarge",
+      "missingSignature",
+      "badSignature",
+      "stale",
+      "replayed",
+      "notJson"
+    ],
+    "httpStatus": {
+      "tooLarge": 413,
+      "missingSignature": 401,
+      "badSignature": 401,
+      "stale": 401,
+      "replayed": 409,
+      "notJson": 400,
+      "unknownHook": 404,
+      "rateLimited": 429,
+      "accepted": 202
+    },
+    "secretCases": [
+      {
+        "bytes": "07 x 32",
+        "expected": "whsec_BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc"
+      }
+    ],
+    "signatureCases": [
+      {
+        "secret": "whsec_test",
+        "timestamp": 1762156800,
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "expected": "t=1762156800,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98"
+      },
+      {
+        "secret": "whsec_test",
+        "timestamp": 1762156800,
+        "body": "",
+        "expected": "t=1762156800,v1=1ae5daffdd9e6a360e19c164a3f86bfa982a4e77395154c9c6244aed6a24efa2"
+      }
+    ],
+    "verifyCases": [
+      {
+        "name": "a fresh, signed delivery",
+        "header": "t=1762156800,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": true,
+          "nonce": "65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+          "body": {
+            "id": "evt_1",
+            "amount": 42
+          }
+        }
+      },
+      {
+        "name": "inside the window (300 s late), spaces and an unknown key ignored",
+        "header": " t=1762156800 , v0=abc, v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762157100,
+        "seen": [],
+        "expected": {
+          "ok": true,
+          "nonce": "65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+          "body": {
+            "id": "evt_1",
+            "amount": 42
+          }
+        }
+      },
+      {
+        "name": "a rotated sender: any v1 may match",
+        "header": "t=1762156800,v1=e43cf9f21cc32eba3e38d7c6605ef086fe5115241197400b9b4b543133bba0a3,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156500,
+        "seen": [],
+        "expected": {
+          "ok": true,
+          "nonce": "65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+          "body": {
+            "id": "evt_1",
+            "amount": 42
+          }
+        }
+      },
+      {
+        "name": "too large, checked first",
+        "header": null,
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 65537,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "tooLarge"
+        }
+      },
+      {
+        "name": "no header",
+        "header": null,
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "missingSignature"
+        }
+      },
+      {
+        "name": "no timestamp",
+        "header": "v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "badSignature"
+        }
+      },
+      {
+        "name": "an uppercase signature is malformed",
+        "header": "t=1762156800,v1=65AEC49D19E905035D361C88F7659132FE978E4560B8FC0D40C4A31D6E140D98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "badSignature"
+        }
+      },
+      {
+        "name": "outside the window",
+        "header": "t=1762156800,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762157101,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "stale"
+        }
+      },
+      {
+        "name": "another secret's signature",
+        "header": "t=1762156800,v1=e43cf9f21cc32eba3e38d7c6605ef086fe5115241197400b9b4b543133bba0a3",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "badSignature"
+        }
+      },
+      {
+        "name": "a tampered body",
+        "header": "t=1762156800,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":4200}",
+        "bytes": 28,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "badSignature"
+        }
+      },
+      {
+        "name": "a replay of an accepted delivery",
+        "header": "t=1762156800,v1=65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98",
+        "body": "{\"id\":\"evt_1\",\"amount\":42}",
+        "bytes": 26,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [
+          "65aec49d19e905035d361c88f7659132fe978e4560b8fc0d40c4a31d6e140d98"
+        ],
+        "expected": {
+          "ok": false,
+          "error": "replayed"
+        }
+      },
+      {
+        "name": "signed but not JSON",
+        "header": "t=1762156800,v1=7771cadafebc038179523cf7de66c8a1c5f720554333303851228919187bf388",
+        "body": "not json",
+        "bytes": 8,
+        "secret": "whsec_test",
+        "now": 1762156800,
+        "seen": [],
+        "expected": {
+          "ok": false,
+          "error": "notJson"
+        }
+      }
+    ],
+    "pathCases": [
+      {
+        "appId": "5b0c7f0e-0000-4000-8000-000000000001",
+        "name": "stripe",
+        "expected": "/api/apps/hooks/5b0c7f0e-0000-4000-8000-000000000001/stripe"
+      }
+    ]
+  },
+  "auditCases": [
+    { "name": "monday_rotation", "run": { "records": { "op": "upsert", "kind": "rotation" } }, "clientId": "automation:monday_rotation", "tool": "records.upsert:rotation" },
+    { "name": "notify", "run": { "action": "exponential_comments_create" }, "clientId": "automation:notify", "tool": "exponential_comments_create" },
+    { "name": "note", "run": { "upstream": "stripe", "tool": "create_note" }, "clientId": "automation:note", "tool": "stripe/create_note" },
+    {"name": "route", "run": {"agent": "triage", "prompt": "x"}, "clientId": "automation:route", "tool": "agent:triage"}
+  ]
+}