@open-everywhere/core 0.1.0

package/agent/routines/event-model.ts

@@ -0,0 +1,744 @@
+// The EVENT MODEL (OPE-163 part 3a) — the vendor-neutral shape every external delivery is
+// normalized into, plus the per-source NORMALIZER REGISTRY that produces it.
+//
+// WHY A SCOPE PATH AND NOT AN "IMPACTED ENTITY". The obvious model is `{ entity }` — the thing
+// this happened to — and it is wrong in two ways that matter, both discovered by asking what the
+// AUTHORIZATION rule (event-authz.ts) can actually stand on:
+//
+//   1. YOU CANNOT FETCH A DELETED ENTITY. "someone deleted the prod runbook" is exactly the alert
+//      people want, and it is precisely the event whose entity no longer exists. An authorization
+//      rule phrased over a fetch result cannot express it at all.
+//   2. MANY EVENTS HAVE NO ENTITY. A `push`, a billing `invoice.payment_failed`, a heartbeat.
+//
+// Both are fixed by the same move: the unit is the ordered, outermost-first CONTAINER PATH the
+// delivery itself proves — never the entity. The path survives a deletion because it is in the
+// delivery, and it is present for entity-less events. `pointer` is then a strictly optional
+// convenience for a later re-fetch, not the load-bearing field.
+//
+// THE WHOLE PATH IS THE UNIT, NOT ONE CHOSEN STEP OF IT. This paragraph used to name the "innermost
+// provable scope step" as the unit, and downstream that hardened into a claim `event-authz.ts` never
+// implemented: the read-grant check passes the ENTIRE path to the source's grant adapter and only
+// requires that it is non-empty. Which step is authoritative is a per-vendor answer the adapter
+// gives (GitHub: `container`, because that is what a GitHub grant is written over). Core carries the
+// path; the adapter reads whichever end of it its vendor's permission model lives at.
+//
+// THE KIND VOCABULARY IS CLOSED AT FIVE. It matches the deepest vendor shape in the tree (Notion:
+// workspace → teamspace → database/page-parent → page → block) and goes no deeper. A vendor with
+// fewer levels yields a SHORTER path, which makes matching COARSER — never wrongly narrower — so no
+// design here depends on any vendor's real subscription topology.
+//
+// PURE REGISTRY LEAF — the `webhooks/verifier.ts` / `credentials/home.ts` posture. Types, a Map and
+// a handful of functions. No crypto, no store, no eve, no vendor strings. Normalizer
+// IMPLEMENTATIONS live with the code that owns the vendor's payload shape.
+//
+// RESOLUTION IS BY THE DELIVERY'S DECLARED SOURCE, NEVER SNIFFED — the same doctrine, for the same
+// reason, as the verifier registry it sits behind: sniffing hands the sender normalizer selection,
+// and with N normalizers of differing scope depth that is a live under-scoping primitive (pick the
+// normalizer that proves the SHALLOWEST path and the read-grant check gets correspondingly weaker).
+//
+// 🔴🔴 THE SCHEME/NAME ASYMMETRY (OPE-198 S2) — READ THIS BEFORE "FIXING" THE MISMATCH BELOW.
+//
+// Two different strings are in play on every delivery, and the code deliberately uses a DIFFERENT
+// one at each of two adjacent steps:
+//
+//   1. THE NORMALIZER IS RESOLVED BY **SCHEME** — `normalizeDelivery` looks up
+//      `eventNormalizer(webhookScheme(d))`, and so does `declaredDeliveryId`. The scheme names the
+//      CONTRACT (whose payload shape this is), and the payload shape is what a normalizer knows.
+//   2. THE EMITTED EVENT CARRIES **NAME** IN `source` — `normalizeDelivery` stamps
+//      `source = d.source` over whatever the normalizer put there, and `event-match.ts` compares
+//      that whole-string against the routine's declared `trigger.source`. The name is WHICH HOOK,
+//      and "which hook" is what a subscription means.
+//   3. THE SCOPE GRANT IS RESOLVED BY **SCHEME** again (`event-authz.ts`), for reason (1)'s reason:
+//      whose permission model applies is a property of the contract, not of our handle for it.
+//
+// So `eventNormalizer(ev.source)` and `eventScopeGrant(ev.source)` are BOTH WRONG even though both
+// compile and both pass every test today — today every hook has `scheme === name`, so the two
+// strings are equal and the bug is invisible. It becomes a live defect the moment two hooks share a
+// scheme under distinct handles, which is the entire point of the split: ONE contract, MANY senders,
+// EACH INDEPENDENTLY SUBSCRIBABLE. Collapsing the asymmetry in either direction destroys one half of
+// that (resolve the normalizer by name ⇒ only one hook per contract can ever route; match by scheme
+// ⇒ every routine on a contract fires for every sender of it).
+//
+// The derivation itself lives in ONE place, `routines/scheme-name.ts`; read its header for why the
+// name is spelled `source` and why `scheme` absent means `scheme = source`.
+
+import { admitProviderRegistration } from "../access/provider-selection.js";
+import { webhookScheme } from "./scheme-name.js";
+// SHAPE ONLY. `access/bundle.ts`'s `Scope` addresses OE SURFACES and is authoritative because the
+// deployer declared it in config; this module's own `ScopeStep` addresses VENDOR ENTITIES and is
+// authoritative only insofar as the vendor signed the delivery. The two vocabularies stay separate
+// (OPE-217) — importing one type here is not a step towards merging them, and a `Scope` must never
+// become expressible as a `ScopeStep` or vice versa.
+import type { Scope } from "../access/bundle.js";
+
+/**
+ * Vendor-neutral CLASS of container. CLOSED — five levels, ordered OUTERMOST-FIRST. A normalizer
+ * populates whichever levels its delivery actually proves; gaps are allowed (GitHub has no
+ * `group`), REPEATS and INVERSIONS are not (see {@link normalizedEventDefect}).
+ */
+export type ScopeKind = "tenant" | "group" | "container" | "entity" | "sub";
+
+/** The five kinds in outermost-first order — the ordering the scope path must respect. */
+export const SCOPE_KINDS: readonly ScopeKind[] = ["tenant", "group", "container", "entity", "sub"] as const;
+
+export interface ScopeStep {
+  readonly kind: ScopeKind;
+  /** The vendor's OWN id. OPAQUE — core never parses it, only compares it. */
+  readonly id: string;
+  /** Human label. UNTRUSTED (attacker-authored: a repo name, a page title). Never matched on. */
+  readonly label?: string;
+}
+
+/** Where to re-fetch authoritative state, for the payload-as-pointer posture. */
+export interface EntityPointer {
+  /** The same runtime dispatch key `EntityRef` uses (channels/entity-actions.ts). */
+  readonly platform: string;
+  readonly id: string;
+  /** TERMINAL event ⇒ the entity is gone, so hydration MUST NOT be required. Set by the
+   *  normalizer off the vendor's own delete signal, never inferred from a failed fetch. */
+  readonly gone?: boolean;
+}
+
+/** ≤16 matchable scalars, each ≤200 chars — see {@link FIELD_VALUE_MAX} for why truncation, not
+ *  rejection, is the right failure mode for an over-long value. */
+export const FIELDS_MAX_KEYS = 16;
+export const FIELD_VALUE_MAX = 200;
+
+/**
+ * ONE normalized external event. Everything downstream of normalization — the filter evaluator, the
+ * read-grant check, the fire preamble — sees only this. No `Request`, no headers, no raw body.
+ */
+export interface NormalizedEvent {
+  /** WHICH HOOK this came from — the NAME, and what a routine's `trigger.source` is matched
+   *  whole-string against (`event-match.ts`). Stamped by {@link normalizeDelivery} from the
+   *  delivery's own declared name, so a normalizer cannot decide which subscriptions it answers.
+   *
+   *  ⚠️ It used to be documented as "the registry key", and that is now {@link scheme}'s job — see
+   *  the module header's asymmetry note before resolving anything through this field. */
+  readonly source: string;
+  /** WHICH CONTRACT this is — the registry key the normalizer and the scope grant were resolved
+   *  through. ABSENT ⇒ {@link source} (routines/scheme-name.ts's absence rule), which is what keeps
+   *  a hand-built event and every pre-split stored shape correct. Always stamped in practice by
+   *  {@link normalizeDelivery}; go through `webhookScheme(ev)` rather than reading it raw. */
+  readonly scheme?: string;
+  /** The vendor's event name, VERBATIM (never re-spelled into a house vocabulary — a rename layer
+   *  is a second thing to keep in sync and buys nothing the filter cannot already express). */
+  readonly event: string;
+  readonly action?: string;
+  /** OUTERMOST-FIRST container path. May be EMPTY (a source that proves no container at all —
+   *  which the read-grant check then refuses, fail-closed, rather than treating as "anywhere"). */
+  readonly scope: readonly ScopeStep[];
+  /** Who caused it, when {@link EventNormalizer.resolvesActor} says the payload can say. CARRIED,
+   *  NOT YET CONSUMED (OPE-192) — the only code that touches it is {@link redactEvent}, which strips
+   *  it, because a vendor handle is attacker-chosen prose. It was documented as load-bearing for a
+   *  self-trigger guard that does not exist; it is not, and no filter may key on it (a normalizer
+   *  puts the actor in `fields` if it wants it matchable — GitHub's `sender`). */
+  readonly actor?: { readonly id?: string; readonly handle?: string };
+  /** The MATCHABLE scalars. A filter may only name a key the normalizer DECLARED in
+   *  {@link EventNormalizer.matchKeys}; extra keys here are carried for rendering, not matching. */
+  readonly fields: Readonly<Record<string, string>>;
+  readonly deliveryId?: string;
+  /** ISO, per the SOURCE — not our receive time. Distinct on purpose: a fire's preamble carries
+   *  both, so "this says 'PR opened' about an already-merged PR" is diagnosable. */
+  readonly occurredAt?: string;
+  /** CODE-RENDERED one-liner. Contains attacker-authored substrings (a PR title), so it is only
+   *  ever emitted through `access/untrusted.ts`'s fence — never into a trusted position. */
+  readonly summary: string;
+  readonly pointer?: EntityPointer;
+  /**
+   * OPE-159 — this delivery was REDACTED to its bare occurrence: the ingress declared a
+   * `trigger-only` posture, so nothing payload-derived reaches the model. `summary` is a fixed
+   * code-rendered line, `pointer` is gone (nothing is fetched), and no renderable payload field
+   * survives. `fields` and `scope` are KEPT and are still matched on — a filter's output is a
+   * boolean, not text, so filtering never puts an outside party's bytes in front of the model.
+   *
+   * Set by {@link normalizeDelivery} from {@link TriggerDelivery.redactPayload}, never by a
+   * normalizer: a normalizer authors the payload projection, so letting it declare its own
+   * redaction would put the guarantee in the hands of the thing being guarded against.
+   */
+  readonly redacted?: boolean;
+  /**
+   * OPE-214 — this delivery was NARROWED to the listed field keys: the ingress declared a
+   * `projection` posture, so {@link summary} was rebuilt from exactly these keys and every other
+   * payload-derived renderable was dropped. The keys are the INGRESS's declaration (config), never
+   * the payload's.
+   *
+   * MUTUALLY EXCLUSIVE WITH {@link redacted}, structurally: `normalizeDelivery` tests redaction
+   * FIRST and returns, and `redactEvent` strips this field, so no event can ever carry both. A
+   * projected event is still payload-bearing — the values are an outside party's bytes, just fewer
+   * of them — so it takes the same taint stamp and the same untrusted fence a `content-bearing`
+   * delivery does. It is NOT a second flavour of redaction and no consumer may read it as one.
+   */
+  readonly projected?: readonly string[];
+  /**
+   * OPE-209 — the hook's declared read grant, STAMPED here from {@link TriggerDelivery.readableBy}
+   * and never authored by a normalizer, for the identical reason {@link redacted} is not: a
+   * normalizer reads attacker-controlled bytes, so it must not be able to state the rule that
+   * decides who may read the result.
+   *
+   * Present ⇒ `routines/event-authz.ts` decides by this ALONE. Absent ⇒ the source's
+   * `EventScopeGrant` adapter decides (the vendor-ingress path). Empty ⇒ refuse.
+   */
+  readonly readableBy?: readonly Scope[];
+}
+
+/**
+ * A transport-free delivery. THE seam: no `Request`, no URL, no method, no queue ARN, no
+ * visibility timeout — "core params never encode hosting topology", applied to ingress. A queue
+ * consumer synthesises `headers` from message attributes and lands on exactly this shape.
+ */
+export interface TriggerDelivery {
+  /** The NAME of the hook (or native ingress) this arrived on. DECLARED by the ingress that received
+   *  it (from config), never sniffed off the payload. Becomes {@link NormalizedEvent.source}. */
+  readonly source: string;
+  /** The SCHEME — the registry key the normalizer is resolved through (OPE-198 S2). DECLARED by the
+   *  ingress from the same configuration and with the same unspoofability property as {@link
+   *  source}. ABSENT ⇒ {@link source}, so every existing ingress — the native GitHub fan-out
+   *  included — is correct without being touched. */
+  readonly scheme?: string;
+  /** LOWERCASED header names. Already-verified metadata — verification happens upstream. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** The raw body bytes as received. */
+  readonly body: string;
+  readonly deliveryId?: string;
+  readonly receivedAt: string;
+  /**
+   * OPE-159 — the ingress declares this delivery's payload must NOT reach the model
+   * (`trigger-only`, `webhooks/config.ts`'s `posture`). Declared by the INGRESS from its own
+   * configuration,
+   * exactly like {@link source}, and never read off the payload: the whole property is that an
+   * outside party cannot influence whether their own bytes get rendered.
+   *
+   * Applied in {@link normalizeDelivery} — i.e. once, at the ONE place every transport's delivery
+   * becomes a routable event — rather than at each render site. A render-site check would have to
+   * be repeated at every future site, and the failure mode of forgetting one is silent.
+   */
+  readonly redactPayload?: boolean;
+  /**
+   * OPE-214 — the ingress declares that only THESE field keys may be rendered (`projection`,
+   * webhooks/config.ts). Declared by the INGRESS from its own configuration with exactly the same
+   * unspoofability property {@link redactPayload} has: a sender cannot name its own keys, because
+   * the list is not in the payload at all.
+   *
+   * 🔴 IT IS SUBORDINATE TO {@link redactPayload}, NEVER A PEER. `normalizeDelivery` tests redaction
+   * first and returns, so a delivery carrying both projects nothing. That ordering is the whole
+   * reason a third posture is safe to add: `trigger-only` exists to keep payloads away from humans,
+   * and an ordering that let a projection run alongside it would be precisely the back door. The
+   * ingress derives both from ONE posture value (`configHookDisclosure`) so the pair cannot
+   * disagree in the first place; the ordering is what makes that a property of the code rather than
+   * of every caller remembering.
+   *
+   * An EMPTY list is treated as "no projection declared" — not as "project nothing". A hook that
+   * wants nothing rendered says `trigger-only`, which is a posture with a name, a card line and a
+   * test; an empty key list reaching this field means a declaration went wrong upstream, and the
+   * validator refuses it there (`assertWebhooksValid`).
+   */
+  readonly project?: readonly string[];
+  /**
+   * ⭐ THE CAPTURE WINDOW'S DEADLINE for the hook that received this delivery (OPE-211 + OPE-184
+   * Half 2) — ISO-8601, and ABSENT MEANS DO NOT CAPTURE. `webhooks/capture-window.ts` holds the
+   * argument; `routines/ingress.ts` is the one consumer.
+   *
+   * Declared by the INGRESS from the stored row, exactly like {@link redactPayload} and
+   * {@link readableBy}, and for the identical reason: whoever holds the sending secret must not be
+   * able to arm retention of their own bytes. A delivery cannot carry this field inbound — it is not
+   * read from the body or the headers anywhere, and there is no path that would.
+   *
+   * 🔴 IT IS SUBORDINATE TO {@link redactPayload} IN THE SAME WAY {@link project} IS. A trigger-only
+   * hook can hold no open window, the declaration helper refuses the combination, and the capture
+   * itself refuses again on the normalized event's `redacted` stamp. The rule that a posture built
+   * to keep payloads away from humans has no storage back door is worth three refusals.
+   */
+  readonly captureUntil?: string;
+  /**
+   * ⭐ THE HOOK'S READ GRANT (OPE-209, replacing OPE-196's single `ownerDomain`) — declared by the
+   * ingress from the hook's own declaration (config file or stored row), and never re-derived from
+   * anything a delivery carries.
+   *
+   * ⭐ WHY IT IS ON THE DELIVERY AND NOT LOOKED UP BY THE NORMALIZER. A normalizer is handed exactly
+   * one {@link TriggerDelivery} and is pure — it has no store, no config and no org. So the only way
+   * an authorization fact can be DECLARATION-DERIVED rather than PAYLOAD-DERIVED is for the ingress
+   * that holds the declaration to state it here. {@link redactPayload} is the precedent, and it is
+   * the same shape of fact: an ingress-declared, non-transport constraint on what a delivery may
+   * cause, applied once at {@link normalizeDelivery}'s seam rather than re-derived downstream.
+   *
+   * 🔴 IT IS THE ENTIRE CONFIDENTIALITY DECISION FOR A HOOK-BORNE EVENT. `routines/event-authz.ts`
+   * evaluates it (union, `access/read-grant.ts`) against each candidate partition's resolved access,
+   * INSTEAD OF the source's `EventScopeGrant` adapter — a hook that declares its own grant does not
+   * also get a per-scheme rule inventing one. A sender cannot move its own events into another
+   * domain: it never touches this field, because it is not in the payload at all.
+   *
+   * ABSENT/EMPTY is legal and FAILS CLOSED, not open — `scopeGrantsRead` refuses both. No caller may
+   * read absence as "any domain".
+   *
+   * Vendor ingresses (the native GitHub fan-out, a queue consumer) leave it unset — their scope comes
+   * from a namespace the VERIFIER makes the sender authoritative over, which is a different rule and
+   * still runs through the source's grant adapter. See `routines/event-authz.ts` for the invariant
+   * that governs which of the two applies.
+   */
+  readonly readableBy?: readonly Scope[];
+}
+
+// --- the match language: the ONE stored shape, and what an unreadable row does -------------------
+//
+// The shape and its reader live HERE, not in event-match.ts, for one structural reason:
+// `routines/routine.ts` stores a filter on the `event` trigger and must import its type, while
+// event-match.ts imports the Routine type to evaluate one. Putting the type AND the reader in the
+// leaf breaks that cycle at the value level, not just the type level — which is what lets
+// `describeFilter` render exactly what the evaluator will run without importing the evaluator.
+//
+// 🔴 A SUBSCRIPTION FILTER IS A **jq EXPRESSION** (OPE-210), AND IT IS THE ONLY SHAPE THIS BUILD
+// READS. Two retired languages used to be readable beside it — the OPE-163 declared-key
+// `{all, under}` filter and the pre-OPE-163 exact-equality `match` record, both compiled to jq at
+// read time. OPE-1145 deleted them after a live-store census counted ZERO rows carrying either, so
+// there was no migration to write. Do not add a second language; add jq.
+//
+// 🔴 AND THE DELETION IS LOUD, NOT SILENT. Dropping the two compiler branches alone would have made
+// a row that still carries one read as `jq` ABSENT — which is the legacy "no filter" reading, i.e.
+// EVERY event from that source. A deletion that turns a narrow subscription into a fire-hose is the
+// worst possible failure mode, so {@link storedFilter} reports an unreadable row as its own arm
+// instead, SEPARATE from "no filter" and carrying no expression to evaluate.
+
+/** The stored filter a subscription carries, structurally — so this leaf can read and render one
+ *  without importing `routine.ts`'s `RoutineTrigger` (which imports this file). ONE field: the two
+ *  retired languages that used to sit beside it were deleted by OPE-1145. */
+export interface StoredSubscription {
+  /** ⭐ A jq predicate over `jq-filter.ts`'s `EventFilterDocument`. ABSENT means "no filter", which
+   *  fire time honours as all-events and create time refuses ({@link storedFilter}'s `none` arm). */
+  readonly jq?: string;
+}
+
+/** Every key an `event` trigger may carry. Anything else on a stored row is a shape this build does
+ *  not understand — a pre-OPE-1145 `filter` / `match`, or a hand-edit — and {@link storedFilter}
+ *  refuses to guess at it. `kind` and `source` are on the trigger beside the filter, so they are
+ *  listed here rather than stripped by every caller. */
+const KNOWN_SUBSCRIPTION_KEYS: readonly string[] = ["kind", "source", "jq"];
+
+/**
+ * WHAT A STORED SUBSCRIPTION SAYS — three arms, and the third one is why this is a function.
+ *
+ * `unknown` IS ITS OWN ARM, NOT A FLAVOUR OF `none`. It carries no expression, so a caller cannot
+ * evaluate it by accident, and it never collapses into the all-events reading by omission. What
+ * TypeScript does NOT do is force a new caller to handle it: `StoredFilter` is a plain union with no
+ * exhaustiveness check, so `f.kind === "jq" ? … : fire()` compiles and would re-open the fire-hose.
+ * That is weaker than `JqOutcome`, where the non-error arm carries the match value itself. So the
+ * guarantee here is the TEST, not the type: `event-routing-test.ts` pins all three surfaces (fire,
+ * render, store), and each pin goes red when its arm is dropped. A new reader of a stored
+ * subscription belongs in that test.
+ *
+ * `unknown` is deliberately keyed on the row's EXTRA KEYS rather than on a known list of retired
+ * spellings: a hand-edited row inventing `where:` is exactly as unreadable as a surviving `match:`,
+ * and naming the keys is what makes the refusal actionable in an audit row.
+ */
+export type StoredFilter =
+  | { readonly kind: "jq"; readonly expression: string }
+  | { readonly kind: "none" }
+  | { readonly kind: "unknown"; readonly keys: readonly string[] };
+
+export function storedFilter(t: StoredSubscription): StoredFilter {
+  const row = t as Readonly<Record<string, unknown>>;
+  // `!== undefined` and not `in`: an object literal built as `{...(x ? {jq: x} : {})}` never carries
+  // an explicit undefined, but a hand-built one can, and an explicitly-undefined key is an ABSENT
+  // field in every JSON round-trip. Refusing it would be a loud failure on a row that means nothing.
+  const keys = Object.keys(row)
+    .filter((k) => !KNOWN_SUBSCRIPTION_KEYS.includes(k) && row[k] !== undefined)
+    .sort();
+  if (keys.length > 0) return { kind: "unknown", keys };
+  return t.jq ? { kind: "jq", expression: t.jq } : { kind: "none" };
+}
+
+/**
+ * One-line human rendering of a subscription — `list_routines`, the CLI, and the arming approval
+ * card all go through it, so what a human APPROVES and what the evaluator RUNS are the same
+ * sentence. Lives here (a leaf over the filter type) rather than with the evaluator so
+ * `routines/routine.ts` can render a trigger without importing the evaluator that imports it.
+ *
+ * AN UNREADABLE ROW DESCRIBES ITSELF AS ONE, and says it will never fire — which is exactly what
+ * `evaluateSubscription` then does with it. That is the renderer's standing invariant ("a stored
+ * row must never DESCRIBE itself differently from how it behaves") applied to the one case the
+ * OPE-1145 deletion creates.
+ */
+export function describeFilter(source: string, t: StoredSubscription): string {
+  const f = storedFilter(t);
+  if (f.kind === "unknown") {
+    return `on ${source} event, but its stored filter shape is UNREADABLE here (${f.keys.join(", ")}) — it can never fire`;
+  }
+  return `on ${source} event${f.kind === "none" ? " (EVERY event from this source)" : ` where ${f.expression}`}`;
+}
+
+// --- the normalizer registry -------------------------------------------------------------------
+
+/** One system's payload→NormalizedEvent translation, plus the DECLARATIONS that make a filter
+ *  naming this source validatable before it is ever stored. */
+export interface EventNormalizer {
+  /** Registry key = exactly what a routine declares as its `source`. */
+  readonly source: string;
+  /** Set ⇒ this entry belongs to a provider BUNDLE and registration routes through
+   *  `admitProviderRegistration`, so a de-selected provider contributes nothing and every routine
+   *  naming that source then fails closed at resolution. Core's own leave it UNSET. */
+  readonly provider?: string;
+  /** The ONLY `fields` keys a filter may name. Rendered into `create_routine`'s refusal copy, so a
+   *  typo'd key is refused with the legal set named — the house pattern.
+   *
+   *  When {@link matchKeysOpen} is set this list stops being exhaustive and becomes the RESERVED
+   *  subset — the keys the contract itself always emits — which is still what the refusal copy and
+   *  the tool description quote. */
+  readonly matchKeys: readonly string[];
+  /**
+   * 🔴 THE KEY SPACE IS THE SENDER'S, NOT THE CONTRACT'S (OPE-196 / S3) — so a create-time
+   * closed-vocabulary check is NOT EXPRESSIBLE for this source, and saying so is better than
+   * pretending a list is complete.
+   *
+   * Set ONLY by a CATEGORY-(b) contract: one where OE defines the envelope and the caller fills it
+   * in (`webhooks/oe-standard-webhook.ts`). Its envelope carries a `fields` bag whose KEYS are chosen
+   * by whoever wrote the sender — `status`, `branch`, `severity` — and no static declaration in this
+   * tree can know them. A vendor contract (category (a)) has a payload shape we read from the
+   * vendor's docs, so its `matchKeys` genuinely IS closed and this field stays absent.
+   *
+   * WHAT IT COSTS, HONESTLY. `validateSubscription`'s membership check is what kills the
+   * SILENT-NO-OP class (a typo'd key sitting `active` forever, matching nothing). For an open
+   * source that check cannot run, so a typo IS possible. Three things bound it and none of them is
+   * this field: the clause SHAPE, the caps and the key GRAMMAR are still enforced; the sender and the
+   * routine author are the same org (a (b) hook's secret was minted for them); and `list_routines`
+   * renders the filter through `describeFilter`, so the typo is legible. It is a real, named
+   * regression in one direction, taken because the alternative — a hook declaring its own field
+   * vocabulary at creation — is the payload-extraction design this arc deliberately killed.
+   *
+   * ABSENT ⇒ CLOSED, which is what makes every shipped source unchanged.
+   */
+  readonly matchKeysOpen?: boolean;
+  /** The subset of {@link matchKeys} that IDENTIFY A SCOPE (GitHub: `repo`). Used by the
+   *  mandatory-narrowing rule: a filter must narrow by SOMETHING, either an `under` selector or a
+   *  clause on one of these. Without it "subscribe to this whole tenant" is the accidental default. */
+  readonly scopeKeys: readonly string[];
+  /** Which scope kinds this source can ever prove — an `under` naming any other kind is refused at
+   *  create time, because it could never match and would sit `active` forever matching nothing. */
+  readonly scopeKinds: readonly ScopeKind[];
+  /**
+   * ⭐ THE SCOPE PATH IS DERIVED ENTIRELY FROM THE RECEIVING HOOK'S ROW, NEVER FROM THE PAYLOAD
+   * (OPE-196 / S3) — the §2 invariant of the webhook-ingress plan, declared as a reviewed field
+   * rather than argued in prose.
+   *
+   * 🔴 THIS IS NOT A GENERAL RULE AND MUST NOT BE SET "TO BE SAFE". The rule the plane actually
+   * enforces is: *scope may be derived from the payload only to the extent the VERIFIER makes the
+   * sender authoritative over that namespace.* GitHub's signature proves GitHub sent it, and GitHub
+   * IS authoritative about which repo an event came from — so `routines/github-normalizer.ts`
+   * correctly derives its whole path from `repository.full_name` and correctly leaves this UNSET. A
+   * sender holding a secret WE minted is authoritative over exactly one fact — WHICH HOOK IT IS —
+   * and over no external namespace, so its path is row-derived and this is set.
+   *
+   * TWO CONSEQUENCES, both of which is why it is a field and not a comment:
+   *   1. `event-match.ts` skips the MANDATORY-NARROWING rule for such a source. That rule exists
+   *      because one vendor `source` spans a whole tenant's containers, so "subscribe to everything"
+   *      must be spelled out. Here the subscription's `source` names ONE HOOK and the path below
+   *      `container` is that hook's own, so naming it IS the narrowing — demanding a second
+   *      `under: {container: <the hook's own name>}` would be ceremony, and ceremony that buys
+   *      nothing is how a control gets routed around.
+   *   2. It is directly TESTABLE: two deliveries with wildly different bodies on one hook must
+   *      produce byte-identical scope paths. A claim about a payload boundary that no assertion can
+   *      contradict is the failure class this tree has a name for.
+   */
+  readonly scopeHookConstant?: boolean;
+  /**
+   * Can this source's payload identify the ACTOR who caused the event? A REVIEWED DECLARATION OF A
+   * VENDOR PROPERTY — declared rather than inferred so the answer is a decision someone made while
+   * reading the vendor's payloads, not a guess.
+   *
+   * 🔴 NOTHING READS IT (OPE-192). It used to be documented as "load-bearing for the future
+   * self-trigger guard"; that guard does not exist and has no design, so the claim described a
+   * control that was not there — the failure class this tree has a name for. Setting it either way
+   * changes no behaviour today. Answer it honestly for your source anyway: the day a guard against
+   * OE's own writes re-triggering OE is built, this is the field that says which sources it can
+   * stand on, and a retrofitted answer would be a guess about payloads nobody was looking at.
+   */
+  readonly resolvesActor: boolean;
+  /**
+   * The LOWERCASED header name this source carries its own idempotency key in, when it has one
+   * (GitHub: `x-github-delivery`). Absent ⇒ this source offers no delivery id and the durable
+   * replay dedupe simply does not run for it — never a synthesised one (see
+   * {@link TriggerDelivery.deliveryId}).
+   *
+   * ⭐ WHY THIS IS ON THE NORMALIZER AND NOT ON `WebhookVerifier` (OPE-201). `keyOrigin` and
+   * `signedTimestamp` are the precedent for a DECLARED per-source fact, and they live on the
+   * verifier because they are facts about the SIGNATURE SCHEME. A delivery-id header is not: it is a
+   * fact about the vendor's DELIVERY ENVELOPE, the same family as the event-name header the
+   * normalizer already owns privately (`routines/github-normalizer.ts`'s `EVENT_HEADER`). Two
+   * structural reasons settle it:
+   *
+   *   1. THE CONSUMER RESOLVES NORMALIZERS, NEVER VERIFIERS. The id is spent by `admitTrigger`, the
+   *      transport-free seam, whose whole point is that a queue receive or an EventBridge
+   *      invocation lands on it too. Those never touch a `WebhookVerifier`, so a fact homed there
+   *      would be unreachable from the plane that uses it.
+   *   2. THE NORMALIZER ALREADY TREATS `d.deliveryId` AS ITS OWN. It reads it and stamps it onto
+   *      {@link NormalizedEvent.deliveryId}, so declaring the header anywhere else would put the
+   *      name and its only reader in two modules.
+   *
+   * DECLARED DATA, NOT INFERRED — there is deliberately no "try a list of likely header names".
+   * Only the VALUE comes from the sender (it always did: the native GitHub route reads the same
+   * header straight off the request); the NAME is a reviewed field, exactly as `source` is.
+   */
+  readonly deliveryIdHeader?: string;
+  /** `null` = an event we do not model (a `ping`) — the ingress 200s and ignores it. MUST NOT
+   *  throw: a broken normalizer must not be able to 500 an ingress (see {@link normalizeDelivery}). */
+  normalize(d: TriggerDelivery): NormalizedEvent | null;
+}
+
+const NORMALIZERS = new Map<string, EventNormalizer>();
+
+/**
+ * Register (or replace) the normalizer for one source. A normalizer carrying `provider` is routed
+ * through the provider-selection gate first. Returns whether the row landed.
+ */
+export function registerEventNormalizer(normalizer: EventNormalizer): boolean {
+  if (normalizer.provider !== undefined && !admitProviderRegistration(normalizer.provider, "event-normalizer")) return false;
+  NORMALIZERS.set(normalizer.source, normalizer);
+  return true;
+}
+
+/** The normalizer for `source`, or undefined when none is registered. NEVER a fallback to another
+ *  source's normalizer — resolution is by declared source, and a miss is a refusal. */
+export function eventNormalizer(source: string | undefined): EventNormalizer | undefined {
+  return source === undefined ? undefined : NORMALIZERS.get(source);
+}
+
+/**
+ * The delivery id THIS SCHEME declares it carries, read out of an ingress's own headers (OPE-201).
+ *
+ * ⚠️ THE PARAMETER IS THE **SCHEME**, NOT THE HOOK'S NAME (OPE-198 S2). A delivery-id header is a
+ * fact about the vendor's delivery envelope — i.e. about the contract — so it is keyed the same way
+ * the normalizer that declares it is. Callers pass `webhookScheme(hook)`; passing `.source` happens
+ * to work today only because every hook has `scheme === name`.
+ *
+ * The one supported way for an ingress to obtain a {@link TriggerDelivery.deliveryId} from a
+ * request it received. Returns undefined for an unregistered scheme, a scheme that declares no
+ * {@link EventNormalizer.deliveryIdHeader}, and an absent or blank header value alike — all three
+ * are "this delivery has no id", which {@link TriggerDelivery.deliveryId} already models as
+ * not-deduped rather than dropped.
+ *
+ * `headers` must already be LOWERCASE-KEYED, matching {@link TriggerDelivery.headers}.
+ *
+ * ⚠️ EVERY INGRESS THAT HOLDS REAL HEADERS SHOULD CALL THIS. The derivation is deliberately NOT
+ * folded into `admitTrigger`: `TriggerDelivery`'s invariant is that every field on it was DECLARED
+ * by the ingress that received the delivery, and the id is not derivable at that seam anyway —
+ * `routines/github-fanout.ts` synthesises a two-field header bag and passes its id explicitly, so a
+ * central derivation would silently find nothing there while looking like it covered everything.
+ */
+export function declaredDeliveryId(scheme: string, headers: Readonly<Record<string, string>>): string | undefined {
+  const header = eventNormalizer(scheme)?.deliveryIdHeader;
+  if (!header) return undefined;
+  const value = headers[header.toLowerCase()];
+  return value ? value : undefined;
+}
+
+/** Every registered source, sorted — for refusal copy and tool descriptions. */
+export function registeredEventSources(): readonly string[] {
+  return [...NORMALIZERS.keys()].sort();
+}
+
+/** Test seam: forget every registered normalizer (mirrors resetWebhookVerifiersForTest). */
+export function resetEventNormalizersForTest(): void {
+  NORMALIZERS.clear();
+}
+
+/** The id of the scope step of this kind, or undefined. The path holds AT MOST ONE step per kind
+ *  ({@link normalizedEventDefect} enforces it), which is what makes a selector on an INNER kind
+ *  imply containment in every outer one — i.e. what makes `under` a genuine prefix test. */
+export function scopeIdOf(scope: readonly ScopeStep[], kind: ScopeKind): string | undefined {
+  return scope.find((s) => s.kind === kind)?.id;
+}
+
+/**
+ * The INNERMOST step the delivery proved.
+ *
+ * 🔴 NOT "what the read grant is evaluated against" — which is what this comment used to say, and it
+ * was wrong. `checkEventReadGrant` calls this function purely as a NON-EMPTINESS PREDICATE (an empty
+ * path cannot be authorized by a scope rule) and then hands the grant adapter the WHOLE path. Which
+ * step is authoritative is 100% the adapter's choice: GitHub's grant reads the `container` step and
+ * explicitly refuses a delivery that proves only a `tenant`. Core requires that the path is
+ * non-empty; it has no opinion about which end of it matters.
+ */
+export function innermostScope(scope: readonly ScopeStep[]): ScopeStep | undefined {
+  return scope.length > 0 ? scope[scope.length - 1] : undefined;
+}
+
+/**
+ * Structural defects a NormalizedEvent must not have, or null. Returned rather than thrown so the
+ * caller can refuse the delivery without a broken normalizer being able to 500 an ingress.
+ *
+ * The ordering/uniqueness rule is not tidiness. A scope test reads as a PREFIX test but is
+ * IMPLEMENTED as kind-keyed lookup ({@link scopeIdOf}, and the `.scope.<kind>` projection a filter
+ * sees), and those two coincide only while the path is a strictly increasing sequence of distinct
+ * kinds. A normalizer emitting `[container:a, container:b]` would silently make
+ * `.scope.container == "a"` match an event inside `b`.
+ */
+export function normalizedEventDefect(ev: NormalizedEvent): string | null {
+  if (!ev.source) return "empty source";
+  if (!ev.event) return "empty event name";
+  let last = -1;
+  for (const step of ev.scope) {
+    const rank = SCOPE_KINDS.indexOf(step.kind);
+    if (rank < 0) return `unknown scope kind "${String(step.kind)}"`;
+    if (rank <= last) return `scope path is not strictly outermost-first (repeated or inverted "${step.kind}")`;
+    if (!step.id) return `scope step "${step.kind}" has an empty id`;
+    last = rank;
+  }
+  if (Object.keys(ev.fields).length > FIELDS_MAX_KEYS) return `more than ${FIELDS_MAX_KEYS} match fields`;
+  return null;
+}
+
+/**
+ * Normalize one delivery through the registered normalizer for its DECLARED source.
+ *
+ * Returns null — never throws — for every "we can't route this" case, so an ingress 200s-and-ignores
+ * uniformly: unregistered source, an event the normalizer doesn't model, a normalizer that threw,
+ * or a structurally defective result. A `reason` sink is offered instead of a throw because the
+ * caller wants to AUDIT the difference between "not modelled" (routine) and "broken" (a bug), and a
+ * thrown error on a per-delivery path is how a serverless ingress turns a bad payload into a 500.
+ *
+ * Over-long field values are TRUNCATED to {@link FIELD_VALUE_MAX} rather than rejected: values that
+ * are matched on are ids (short), values that are long are prose (titles), and dropping a whole
+ * delivery because someone wrote a long PR title would be a self-inflicted outage.
+ */
+export function normalizeDelivery(d: TriggerDelivery, onReject?: (reason: string) => void): NormalizedEvent | null {
+  // BY SCHEME (see the module header's asymmetry note) — the contract owns the payload shape.
+  const scheme = webhookScheme(d);
+  const n = eventNormalizer(scheme);
+  if (!n) {
+    onReject?.(`no normalizer registered for source "${scheme}" (registered: ${registeredEventSources().join(", ") || "none"})`);
+    return null;
+  }
+  let ev: NormalizedEvent | null;
+  try {
+    ev = n.normalize(d);
+  } catch (err) {
+    onReject?.(`normalizer for "${scheme}" threw: ${String(err)}`);
+    return null;
+  }
+  if (!ev) return null; // unmodelled — the routine case, not a defect
+  // THE DEFECT CHECK RUNS ON THE NORMALIZER'S OWN OUTPUT, BEFORE THE STAMP BELOW. Deliberate: the
+  // stamp would overwrite an empty `source` with the ingress's declared name and thereby HIDE a
+  // broken normalizer that the pre-split code refused. Checking first keeps that refusal exactly as
+  // it was.
+  const defect = normalizedEventDefect(ev);
+  if (defect) {
+    onReject?.(`normalizer for "${scheme}" produced a defective event: ${defect}`);
+    return null;
+  }
+  const fields: Record<string, string> = {};
+  for (const [k, v] of Object.entries(ev.fields)) fields[k] = v.length > FIELD_VALUE_MAX ? v.slice(0, FIELD_VALUE_MAX) : v;
+  // ⭐ THE STAMP. `source` is forced to the INGRESS'S declared name and `scheme` to the resolved
+  // registry key — a normalizer emits its own registry key today (`GITHUB_EVENT_SOURCE`), which is
+  // right for a one-hook-per-scheme world and silently wrong the moment two hooks share a scheme.
+  // Doing it here rather than asking every normalizer to echo `d.source` makes "the event names the
+  // hook it arrived on" a property of ONE function instead of a convention N adapters must keep.
+  // A no-op today: the normalizer's key IS the delivery's declared source for every shipped source.
+  // `readableBy` joins the stamp for the same reason `source` and `scheme` do: it is the INGRESS's
+  // fact about its own declaration, and stamping it in one place is what stops it from being a
+  // convention N normalizers have to keep. `redactEvent` spreads the event, so it survives redaction
+  // — as it must: a `trigger-only` hook is still readable only by what its declaration says.
+  const out: NormalizedEvent = { ...ev, fields, source: d.source, scheme, ...(d.readableBy ? { readableBy: d.readableBy } : {}) };
+  // 🔴 REDACTION IS TESTED FIRST AND RETURNS (OPE-214). `trigger-only` must keep meaning
+  // trigger-only, so the arm that projects NOTHING wins over the arm that projects SOMETHING,
+  // unconditionally and by control flow rather than by the two never co-occurring. They should never
+  // co-occur — one posture value derives both (webhooks/config.ts `configHookDisclosure`) — but "an
+  // invariant nothing enforces" is how a posture whose whole purpose is keeping payloads away from
+  // humans grows a back door. `scripts/webhook-runtime-test.ts` (§6) sets BOTH on a hand-built
+  // delivery and asserts the result is redacted, projects nothing, and cannot smuggle a projected
+  // key past redaction — which is the only form of that claim an assertion can contradict. (The
+  // pointer used to name `event-routing-test.ts`, which contains no such assertion; a pointer to the
+  // wrong test is worse than none, because it makes the guard look covered.)
+  if (d.redactPayload) return redactEvent(out, d.source);
+  if (d.project && d.project.length > 0) return projectEvent(out, d.source, d.project);
+  return out;
+}
+
+/**
+ * OPE-159 — strip every payload-derived RENDERABLE from a normalized event, keeping only what is
+ * MATCHED on. The `trigger-only` posture, made concrete.
+ *
+ * WHAT SURVIVES, AND WHY: `fields` and `scope` stay, because a filter evaluates to a boolean and a
+ * boolean is not text — matching on the payload never puts an outside party's bytes in front of the
+ * model. `event`/`action` stay for the same reason (they are what filters key on).
+ *
+ * WHAT GOES, AND WHY EACH ONE: `summary` is replaced with a line built ONLY from `source`, which
+ * the INGRESS declared from its own configuration — not one byte of it is payload-derived, so a
+ * holder of a leaked secret cannot get a single character of their own choosing in front of the
+ * model. `pointer` is dropped, which is what makes "no fetch happens" structural rather than a
+ * convention: with no pointer, `routines/ingress.ts` never enters its hydration arm at all.
+ * `fields.url` is dropped because it is the one field that is RENDERED as well as matchable
+ * (ingress.ts reads `ev.fields["url"]` into the prompt), so leaving it would be a hole in exactly
+ * the property this function exists to provide. `actor` goes because a handle is attacker-chosen
+ * prose on several vendors.
+ *
+ * The result is that a leaked `trigger-only` secret buys exactly one thing: causing a known,
+ * member-authored, human-approved prompt to run. That is the same authority a cron already has.
+ */
+export function redactEvent(ev: NormalizedEvent, declaredSource: string): NormalizedEvent {
+  const { url: _url, ...fields } = ev.fields as Record<string, string>;
+  // `projected` is stripped alongside `pointer`/`actor` (OPE-214). It cannot be set on the way in —
+  // `normalizeDelivery` returns from the redaction arm before the projection arm runs — but this
+  // function is exported and callable on any event, and a redacted event that still ADVERTISED a
+  // projection would describe a disclosure that did not happen. Stripping it here means "redacted"
+  // and "projected" are mutually exclusive on the RESULT no matter who calls this.
+  const { pointer: _pointer, actor: _actor, projected: _projected, ...rest } = ev;
+  return {
+    ...rest,
+    fields,
+    summary: `${declaredSource} webhook fired (payload withheld — this hook is trigger-only)`,
+    redacted: true,
+  };
+}
+
+/**
+ * OPE-214 — narrow a normalized event to the NAMED fields. The `projection` posture, made concrete,
+ * and deliberately the same SHAPE of function as {@link redactEvent}: one pure rewrite, applied once
+ * at `normalizeDelivery`'s seam, so no render site has to remember a posture.
+ *
+ * WHY IT EXISTS. Before it, the choice was binary — the model sees an entire third-party payload, or
+ * it sees nothing — so any hook that needed ONE field had to disclose all of them. That is
+ * over-disclosure forced by the vocabulary rather than chosen by anyone.
+ *
+ * WHAT SURVIVES, AND WHY EACH ONE.
+ *   • `fields` and `scope` stay WHOLE, exactly as they do under redaction, and for the identical
+ *     reason: a filter evaluates to a BOOLEAN, and a boolean is not text. Narrowing the matchable
+ *     key space to the rendered one would silently break every subscribed routine's filter — a
+ *     projection is a RENDER-time narrowing, not a routing change.
+ *   • `fields.url` is the one exception, and it is an exception because `routines/ingress.ts` reads
+ *     it straight into the prompt. It is therefore RENDERED as well as matchable, so it survives
+ *     only when it is NAMED — the same carve-out `redactEvent` makes, for the same reason, and the
+ *     place a "keep everything matchable" shortcut would have left a hole in exactly the property
+ *     this function exists to provide.
+ *   • `event` / `action` stay: vendor event names, already survivors of redaction.
+ *
+ * WHAT GOES: `summary` is REBUILT from the named keys only (never the normalizer's own prose, which
+ * is where a title or a commit message lives); `pointer` is dropped, which is what makes "no fetch
+ * happens" structural — with no pointer `routines/ingress.ts` never enters its hydration arm, and a
+ * hydrated entity is the whole payload by another route; `actor` goes because a handle is
+ * attacker-chosen prose.
+ *
+ * 🔴 THE RESULT IS STILL UNTRUSTED. The projected values ARE an outside party's bytes — fewer of
+ * them, chosen by us, but not sanitised — so the fire stays TAINTED and the summary still goes
+ * through `access/untrusted.ts`. A projection bounds VOLUME, not trust.
+ *
+ * `keys` is the ingress's declared list; a key the delivery did not carry is simply absent from the
+ * rendering rather than rendered as empty, so a sender cannot tell which keys were declared by
+ * varying what it sends.
+ */
+function projectEvent(ev: NormalizedEvent, declaredSource: string, keys: readonly string[]): NormalizedEvent {
+  const { url: _url, ...matchable } = ev.fields as Record<string, string>;
+  const url = ev.fields["url"];
+  const fields = keys.includes("url") && url !== undefined ? { ...matchable, url } : matchable;
+  const { pointer: _pointer, actor: _actor, ...rest } = ev;
+  // Rendered in DECLARATION order, not delivery order: the declaration is the reviewed artefact, so
+  // two deliveries of one hook read the same way and a diff of the prompt is a diff of the payload.
+  const shown = keys.filter((k) => ev.fields[k] !== undefined).map((k) => `${k}: ${ev.fields[k]}`);
+  return {
+    ...rest,
+    fields,
+    summary:
+      shown.length > 0
+        ? `${declaredSource} webhook fired — ${shown.join("; ")}`
+        : `${declaredSource} webhook fired (none of this hook's projected fields were present in the delivery)`,
+    projected: keys,
+  };
+}