Hypersub

1. Purpose

Hypersub is the platform implementation of a Hyperapp's trigger facet — the store a trigger's subscriptions live in. It is Hypernet's subscription store, a platform layer beside Hyperfile, Hyperauth, and Hypervault.

A Hyperapp records the subscriptions a human configures here, and when an event arrives looks them up to know which agents to wake. The store holds them; the Hyperapp matches and wakes.

2. Model

• A subscription is provider-agnostic. (provider, agent, target) → { match_key, config }. target is the wake URL; config is opaque trigger data (which events, an instruction); match_key is an opaque key the Hyperapp builds for lookup.
• Found by match key, not by agent. An event arrives with source-side keys (an installation, a repository) and no agent. So a subscription is looked up by the match key the Hyperapp declared, across agents; the Hyperapp then wakes each matching target.
• Store, not route. Hypersub stores and queries subscriptions; it holds no provider logic. The Hyperapp verifies the delivery, matches, and wakes.

3. Interface

GET    /:provider/matching?key=…   → subscriptions for an event (any agent)
GET    /:provider/one?target=…     → one subscription (prefill)
PUT    /:provider                  → upsert { agentId, target, matchKey, config }
DELETE /:provider?target=…         → remove

Subscriptions are stored in a provider-agnostic table indexed by match key, gated by a service token; a Hyperapp reaches it over a service binding through the @agx-computer/hypersub client — createHypersub({ binding, token, provider }). The GitHub Hyperapp, for example, uses installation/repo as the match key; on a webhook it verifies the signature, resolves subscriptions by that key, and wakes each agent with the trimmed event.

4. Principles

• Provider-agnostic. A subscription is opaque config plus a match key; all provider logic (webhook parsing, matching) lives in the Hyperapp.
• Optional. A Hyperapp may keep its own subscription store; Hypersub is the shared default.
• Waking is the platform's. Hypersub holds routes; starting an agent turn is the platform's wake primitive (see Trigger).