@open-everywhere/core 0.1.0

package/agent/routines/event-authz.ts

@@ -0,0 +1,268 @@
+// "CAN" — the AUTHORIZATION half of event routing (OPE-163 part 3c).
+//
+// THE RULE, in its strongest form:
+//
+//   A routine may be triggered by a delivery iff the delivery proves a NON-EMPTY scope path AND the
+//   delivery is READ-granted for the effective access of EVERY partition the fire touches — and its
+//   cadence is separately bounded.
+//
+// 🔴 "READ-GRANTED" HAS TWO IMPLEMENTATIONS AND THEY ARE MUTUALLY EXCLUSIVE (OPE-209):
+//   • the HOOK'S OWN DECLARED GRANT (`NormalizedEvent.readableBy`), when the ingress declared one —
+//     config, coarse, admin-reviewed, union-combined (`access/read-grant.ts`). This is the whole
+//     confidentiality decision for every hook OE itself declares, and it short-circuits the adapter;
+//   • the SOURCE'S REGISTERED GRANT ADAPTER, for a vendor ingress that declares none — the rest of
+//     this header describes that path, which is unchanged.
+// Everything below about scope paths, partitions and cadence applies to both.
+//
+// 🔴 THE ADAPTER CHOOSES WHICH STEP IS AUTHORITATIVE; CORE ONLY REQUIRES A NON-EMPTY PATH. This
+// header used to say the rule was "grants READ on the INNERMOST SCOPE STEP the delivery proves", and
+// {@link innermostScope}'s own doc said it was "what the read grant is evaluated against". Both were
+// wrong about shipped code, in the same direction: `checkEventReadGrant` calls `innermostScope`
+// ONLY as a non-emptiness predicate and then passes `ev.scope` — the WHOLE path — to
+// `grantsRead`. GitHub's adapter picks the `container` step out of it and refuses everything else,
+// because `repoAllowed` is defined over exactly that string; a vendor whose permission model sits
+// at another level would pick another step, and core would be none the wiser. Read this file as
+// "prove SOME container, then ask the vendor's own adapter", never as an innermost-step rule.
+//
+// WHY THE READ GRANT IS THE RIGHT UNIT. The trigger is strictly LESS informative than the fetch it
+// authorizes. If a domain may read `acme/web` at will, learning "something under acme/web changed"
+// tells it nothing it could not have polled for — and OE ALREADY SHIPS THAT POLL, ungated: the
+// `watch` trigger kind is a cron'd read of exactly the same data, authorized by nothing but the read
+// grant. Gating the event-driven form more tightly than the poll it optimises would be incoherent.
+// Event-triggering is a LATENCY OPTIMISATION ON AN ALREADY-GRANTED POLL.
+//
+// WHY THE SCOPE STEP AND NOT THE ENTITY. Phrasing the rule over the impacted entity under-authorizes
+// in two ways that matter and cannot be patched: you cannot fetch a DELETED entity (and "someone
+// deleted the prod runbook" is the alert people actually want), and many events have NO entity at
+// all (a push, a heartbeat). `grantsRead` therefore takes the SCOPE PATH — which is in the delivery
+// and survives both — and never a fetch result.
+//
+// 🔴 WHAT THIS RULE DOES *NOT* SAY, stated out loud so it is not read as a complete story:
+//
+//   • IT AUTHORIZES CONTENT, NOT CADENCE. An admin grants a repo so a human can ask about PRs; this
+//     rule converts that grant into a standing subscription that can wake a model thousands of
+//     times. Cadence is bounded separately, never here: the fan-out's per-routine budget gate
+//     (`scopeOverBudget` in routines/ingress.ts — per matched routine, per delivery, OPE-275), the
+//     per-delivery fan-out cap, and the arming approval on `create_routine`.
+//   • IT SAYS NOTHING ABOUT AUDIENCE FIT. A domain can hold a repo grant while the ROOM the routine
+//     reports into is the wrong audience for the content (a security issue title carrying a customer
+//     id, rendered into #general). The grant model has no answer and inventing one here would be
+//     wrong; `access/audience-floor.ts` + `access/connector-disclosure.ts` are the right long-term
+//     home. Separately ticketed.
+//   • IT IS EVALUATED NOW, ABOUT AN EVENT THAT HAPPENED THEN. A grant issued after the event lets a
+//     routine learn about a change it was not entitled to observe at the time. Marginal, but real —
+//     which is why `occurredAt` is carried on the normalized event and into the fire preamble, so the
+//     question is at least answerable.
+//
+// 🔴 THE COLLISION THIS FILE EXISTS TO SURVIVE — READ BEFORE ADDING A `RoutineReport` ARM.
+// The read grant is a property of a DOMAIN. The report target is a ROOM. Today they coincide, for
+// one contingent reason only: routines are surface-owned and fire back into their own surface, so
+// there is exactly one partition in play. The moment `RoutineReport` gains an arm that names its own
+// destination, this rule would silently authorize DELIVERY INTO A DIFFERENT ROOM on the strength of
+// the OWNING domain's grant. {@link eventGrantPartitions} is the forcing function: it is EXHAUSTIVE
+// over `RoutineReport`, so a new arm does not compile until its author has decided which partition(s)
+// the grant must hold on, and {@link checkEventReadGrant} takes a LIST and requires EVERY member to
+// grant. No dead runtime guard is shipped for a shape that does not exist yet — the constraint is
+// carried by the type system, where it cannot rot.
+
+import { getConfig } from "../access/config.js";
+import { resolveAccess, type EffectiveAccess, type ResolveRequest } from "../access/resolver.js";
+import { scopeGrantsRead } from "../access/read-grant.js";
+import type { Partition } from "../memory/partition.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+import { innermostScope, type NormalizedEvent, type ScopeStep } from "./event-model.js";
+import { webhookScheme } from "./scheme-name.js";
+import { routinePartition } from "./partition.js";
+import type { Routine } from "./routine.js";
+
+/**
+ * One source's answer to "does this effective access grant READ over this scope path?".
+ *
+ * PURE — no I/O, no ctx, no fetch. That is what lets the check run on the fire path (where there is
+ * no session) at the cost of a config read, and it is what keeps the rule expressible for a deleted
+ * entity. The per-vendor dimension is real and unavoidable — GitHub scopes by repo, a Linear
+ * workspace token is self-scoping, a Notion connector grant covers the workspace — so it is a
+ * registry, exactly like `EntityActionAdapter.checkAccess`, rather than an if-ladder in core.
+ */
+export interface EventScopeGrant {
+  /** Registry key — the same `source` the normalizer registered under, which since OPE-198 S2 is
+   *  the delivery's SCHEME rather than the receiving hook's name. Identical for every source that
+   *  ships today; the distinction is what lets one grant adapter serve N hooks on one contract. */
+  readonly source: string;
+  /** Set ⇒ routed through `admitProviderRegistration`; a de-selected bundle registers nothing and
+   *  every event on that source then fails closed with `no-grant-adapter`. */
+  readonly provider?: string;
+  grantsRead(scope: readonly ScopeStep[], access: EffectiveAccess): boolean;
+}
+
+const GRANTS = new Map<string, EventScopeGrant>();
+
+export function registerEventScopeGrant(grant: EventScopeGrant): boolean {
+  if (grant.provider !== undefined && !admitProviderRegistration(grant.provider, "event-scope-grant")) return false;
+  GRANTS.set(grant.source, grant);
+  return true;
+}
+
+export function eventScopeGrant(source: string | undefined): EventScopeGrant | undefined {
+  return source === undefined ? undefined : GRANTS.get(source);
+}
+
+export function registeredEventGrantSources(): readonly string[] {
+  return [...GRANTS.keys()].sort();
+}
+
+/** Test seam — forget every registered grant adapter. */
+export function resetEventScopeGrantsForTest(): void {
+  GRANTS.clear();
+}
+
+/** Why a matched routine was not authorized. Closed set; `refused` names the partition that said no. */
+export type EventGrantVerdict =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "no-grant-adapter" | "no-scope" | "unresolvable" | "refused"; readonly partition?: string };
+
+export interface EventGrantDeps {
+  /** Injected access resolution — the live default reads the registered app config. */
+  readonly resolve?: (p: Partition) => EffectiveAccess;
+}
+
+/** A session-free ResolveRequest for a partition. The key finding that makes the fire path cheap:
+ *  answering "can" needs NO session context — `ResolveRequest` is six plain fields, and every one
+ *  of them is derivable from the routine's stored surfaceKey plus deployer-owned config. */
+export function requestForPartition(p: Partition): ResolveRequest {
+  return {
+    mode: "channel",
+    platform: p.platform,
+    workspace: p.workspace,
+    channel: p.surface,
+    domains: getConfig().domainsForSurface({ workspaceKey: p.workspaceKey, surface: p.surface }),
+  };
+}
+
+/**
+ * The LIVE access resolution for a partition — the default `deps.resolve` of {@link checkEventReadGrant}.
+ *
+ * EXPORTED (OPE-212) so the delivery-history read gate can call the SAME function rather than
+ * hand-roll a second "what may this surface see" resolution. That symmetry is the whole authorization
+ * argument on the read side: if a routine on this partition could have been FIRED by a hook, this
+ * partition may READ that hook's history — which is only literally true while both gates go through
+ * this function and `scopeGrantsRead`. A private copy in control/delivery-history.ts would be a
+ * second security posture nobody would notice diverging, which is exactly what `readableBy` was
+ * reinstated to end (access/read-grant.ts rule 1).
+ */
+export function resolveAccessForPartition(p: Partition): EffectiveAccess {
+  const cfg = getConfig();
+  return resolveAccess(requestForPartition(p), cfg.loadBundles(), cfg.loadBindings(), cfg.pluginRegistry, cfg.loadConnectorCredentials?.() ?? []);
+}
+
+/**
+ * EVERY partition a fire of this routine touches, and therefore every partition whose domain must
+ * grant read on the event's scope.
+ *
+ * EXHAUSTIVE over `RoutineReport` on purpose — see the header. Adding an arm that names its own
+ * destination MUST come with a decision here; the `never` assignment below is what refuses to
+ * compile until it does.
+ */
+export function eventGrantPartitions(r: Routine): readonly Partition[] {
+  const own = routinePartition(r);
+  const report = r.report;
+  if (report === undefined) return [own];
+  switch (report.kind) {
+    // `silent` names no destination of its own — it REMOVES the post rather than redirecting it —
+    // so the owning partition is still the only one in play.
+    case "silent":
+      return [own];
+    // `surface` (OPE-148) DOES name a destination of its own — the domain's configured
+    // `reportChannel` — so the event's payload will be rendered into a room the owning partition's
+    // grant says nothing about. BOTH partitions must grant, which is exactly what this function
+    // returning two of them achieves (the caller ANDs over the list, so adding one can only ever
+    // make the verdict stricter).
+    //
+    // This is not belt-and-braces. `assertReportChannels` (memory/domain.ts) constrains the report
+    // channel to the SAME domain, and a domain's rooms do share an access bundle — so today the two
+    // grants are the same grant and this arm changes no live verdict. It is here because the
+    // co-membership is a CONFIG LINT, enforced at boot on a config file, and this is a fail-closed
+    // authorization check on an event payload: the check must not be load-bearing on the lint
+    // having run, or a hand-edited row, a migrated one, or a future arm that relaxes the
+    // same-domain rule silently authorizes delivery into a room on a different domain's grant.
+    case "surface":
+      return [own, routinePartition({ org: r.org, surfaceKey: report.surfaceKey })];
+    // THE FORCING FUNCTION. A new `RoutineReport` arm makes this assignment fail to compile, which
+    // is the whole point: the author is stopped at exactly the moment they would otherwise have
+    // shipped a report target whose partition nobody checked the read grant against. It lives in
+    // `default:` rather than after the switch so that it stays a COMPILE error as arms are added
+    // — once every arm returns, code after the switch is unreachable and `report` narrows to
+    // `never`, which makes the guard fail to compile for the wrong reason (and tempts the next
+    // person to delete it). It DID its job on the OPE-148 arm above.
+    default: {
+      const exhaustive: never = report;
+      throw new Error(
+        `unhandled RoutineReport kind "${String((exhaustive as { kind?: unknown }).kind)}" — a report arm that names its OWN destination must contribute ` +
+          "that destination's partition here, or the event read-grant check would authorize delivery into a room on the " +
+          "strength of a different domain's grant.",
+      );
+    }
+  }
+}
+
+/**
+ * THE CHECK. AND over partitions: every one must grant, so adding a partition can only ever make the
+ * verdict stricter. Fail-closed at every step — an unregistered source, an empty scope path, a
+ * config that will not load, and an outright refusal all return `ok: false`, and none of them throw.
+ *
+ * Returning rather than throwing follows `access/provider-selection.ts`'s "REFUSE, DON'T THROW"
+ * doctrine, and it matters more here than usual: this runs inside a fan-out loop over N routines,
+ * where a throw would take out the fires of every OTHER matching routine as collateral.
+ */
+export function checkEventReadGrant(
+  ev: NormalizedEvent,
+  partitions: readonly Partition[],
+  deps: EventGrantDeps = {},
+): EventGrantVerdict {
+  // ⭐⭐ TWO RULES, AND WHICH ONE APPLIES IS DECIDED BY THE INGRESS, NOT BY THE EVENT (OPE-209).
+  //
+  //   • A HOOK THAT DECLARED ITS OWN READ GRANT (`ev.readableBy`, stamped by `normalizeDelivery`
+  //     from the hook's config declaration or stored row) is authorized by THAT AND NOTHING ELSE.
+  //     `readableBy` is the entire confidentiality decision for such a hook: config, coarse,
+  //     admin-reviewed, many-domains-permitted, unioned (`access/read-grant.ts`).
+  //   • A VENDOR INGRESS that declares none (the native GitHub fan-out, a queue consumer) is
+  //     authorized by its SOURCE's registered grant adapter, over the scope path the verifier makes
+  //     the sender authoritative over. Unchanged.
+  //
+  // 🔴 THEY DO NOT COMPOSE, AND THAT IS THE POINT. Running both would mean a per-scheme rule could
+  // re-authorize an event whose own declaration refused it — a second mechanism quietly widening the
+  // first, which is exactly the drift `readableBy` was reinstated to end. A declared grant therefore
+  // short-circuits the adapter lookup entirely, including the `no-grant-adapter` refusal: a hook
+  // speaking a contract with no grant adapter is fully authorized by its declaration, and needing a
+  // per-scheme adapter as well would make the declaration decorative.
+  const declared = ev.readableBy;
+  const adapter = declared ? undefined : eventScopeGrant(webhookScheme(ev));
+  if (!declared && !adapter) return { ok: false, reason: "no-grant-adapter" };
+  // A delivery that proves NO container at all cannot be authorized by a scope rule. Refusing is
+  // the only fail-closed reading: treating an empty path as "matches any grant" would make a
+  // normalizer bug an authorization bypass. Applies to BOTH rules — a declared grant answers "who
+  // may read", never "is this event well-formed enough to route".
+  if (!innermostScope(ev.scope)) return { ok: false, reason: "no-scope" };
+  if (partitions.length === 0) return { ok: false, reason: "unresolvable" };
+  const resolve = deps.resolve ?? resolveAccessForPartition;
+  for (const p of partitions) {
+    let access: EffectiveAccess;
+    try {
+      access = resolve(p);
+    } catch {
+      // Matches grantedForCtx's explicit "override-store failure must fail CLOSED".
+      return { ok: false, reason: "unresolvable", partition: p.surfaceKey };
+    }
+    let granted: boolean;
+    try {
+      // An EMPTY declared list refuses here rather than falling through to the adapter — see
+      // `scopeGrantsRead`. That is what makes the zero-domain trap (OPE-206) a stated refusal
+      // naming the partition instead of a missing scope step nothing mentions.
+      granted = declared ? scopeGrantsRead(declared, access) : adapter!.grantsRead(ev.scope, access);
+    } catch {
+      return { ok: false, reason: "unresolvable", partition: p.surfaceKey };
+    }
+    if (!granted) return { ok: false, reason: "refused", partition: p.surfaceKey };
+  }
+  return { ok: true };
+}

package/agent/routines/event-match.ts

@@ -0,0 +1,200 @@
+// The SUBSCRIPTION MATCH LANGUAGE (OPE-163 part 3b, re-based on jq by OPE-210) — "CAN this delivery
+// trigger this routine?", answered by ONE jq predicate, evaluated identically on every source.
+//
+// 🔴 WHAT CHANGED, AND THE ARGUMENT THAT DID *NOT* SURVIVE. This module used to evaluate a
+// declared-key clause language (`{all:[{key,in:[…]}], under:[…]}`) whose entire justification was
+// create-time validation against a closed key vocabulary. That justification was wrong: the property
+// comes from HAVING A SCHEMA, not from the syntax, and given a schema jq paths validate just as
+// well. The code already conceded it — `EventNormalizer.matchKeysOpen` exists precisely because for
+// a category-(b) contract the key space belongs to the SENDER, so the membership check never ran for
+// the case that motivates flexible filtering at all. **Do not reintroduce declared match keys on the
+// grounds that a path language loses validation.** It does not.
+//
+// The evaluator itself is `routines/jq-filter.ts` — read its header for the sandbox properties, the
+// measured resource bounds, and the three fidelity gaps.
+//
+// TWO EVALUATIONS, DELIBERATELY ASYMMETRIC:
+//
+//   CREATE TIME ({@link validateSubscription}, plus the async compile probe `jq-filter.probeFilter`
+//   that `create_routine` runs alongside it) is the PRIMARY GATE and it THROWS, so `create_routine`
+//   refuses and the model reads exactly what was wrong. Everything knowable up front is checked
+//   here — unregistered source, an expression that is not a usable predicate, one that never
+//   narrows. This is what kills the SILENT-NO-OP class: `computeNextRun` returns null for `event`,
+//   so nothing ever revisits the row and a typo'd subscription would sit `active` forever, matching
+//   nothing, with nothing anywhere saying so.
+//
+//   FIRE TIME ({@link evaluateSubscription}) NEVER THROWS. Every way a filter can fail — a parse
+//   error, an unknown function, an iteration limit, an expression that yields a string instead of a
+//   boolean, a source whose normalizer is no longer registered — is reported as `invalid`, which the
+//   fan-out turns into NO MATCH plus an audit row, and explicitly does NOT count as a routine
+//   failure: config drift is not the routine's fault, and a strike here would let one config change
+//   3-strike-disable a whole fleet through lifecycle.ts. The rejected alternative was to fire anyway
+//   on a "no valid filter = all events" reading, which turns a config typo into a fire-hose.
+//
+// FAIL-CLOSED IS STRUCTURAL, NOT REMEMBERED. `JqOutcome` has no arm that carries both a reason and a
+// match, so there is no way to write a caller that fires on a broken filter. The only path to
+// `{match:true}` is jq printing exactly `true` on exit 0.
+//
+// ONE RULE REVERSES TODAY'S DEFAULT. The old matcher read `if (!t.match) return true` — an event
+// routine with no filter subscribed to EVERYTHING its source emitted. {@link validateSubscription}
+// REFUSES a filter that narrows by nothing whenever the source can prove a `container`. "Subscribe
+// to every event in this whole tenant" has to be spelled out, not defaulted into — because the read
+// grant authorizes the CONTENT and says nothing about the VOLUME, and volume is the attack.
+//
+// ⚠️ AND THE JQ VERSION OF THAT RULE IS SYNTACTIC, WHICH IS WEAKER — SAY SO RATHER THAN PRETEND.
+// Over a structural clause list, "does this narrow by scope?" was decidable. Over a free-form
+// expression it is not, so {@link narrowsScope} asks whether the expression REFERENCES a scope
+// anchor at all. `.scope.container == "acme/web"` passes and `true` is refused, which is the case
+// the rule was written for; `(.scope.container | length) > 0` also passes and matches everything,
+// which it should not. That is an ERGONOMIC gate, and it is not the boundary: the boundary is the
+// fire-time read grant in `routines/event-authz.ts`, which was already the only enforcement there
+// has ever been (see the "there is one belt" note at its single call site in ingress.ts).
+//
+// The reversal is CREATE-time only. Stored rows written before it keep their meaning at fire time:
+// an existing filter-less subscription still matches its source's events. Retro-actively muting live
+// subscriptions would be a silent, invisible behaviour change on exactly the routines nobody is
+// looking at.
+//
+// COST. One jq evaluation per candidate routine per delivery, ~0.3–0.6 ms on a fresh interpreter.
+// That is cheap enough that there is no pre-index and no declared-key pre-filter: at this price
+// there is no expensive matcher to protect. The real per-delivery cost is the CANDIDATE-SET SIZE.
+
+import { eventNormalizer, registeredEventSources, storedFilter, type EventNormalizer, type NormalizedEvent } from "./event-model.js";
+import { assertFilterShape, evaluateJqFilter, filterDocument } from "./jq-filter.js";
+import { webhookScheme } from "./scheme-name.js";
+import type { Routine, RoutineTrigger } from "./routine.js";
+
+/** Is a stored trigger an event subscription? Narrowing helper, so callers don't re-spell the tag. */
+export function isEventTrigger(t: RoutineTrigger): t is Extract<RoutineTrigger, { kind: "event" }> {
+  return t.kind === "event";
+}
+
+// THE STORED-SHAPE READER LIVES IN `event-model.ts`, NOT HERE, and the reason is the same
+// dependency argument that put the filter TYPE there: `routine.ts` renders a trigger through
+// `describeFilter`, and describing must produce exactly what evaluating will run. Keeping the
+// reader in the leaf lets both callers share it without `routine.ts` importing the evaluator that
+// imports `routine.ts`. Re-exported so the evaluator's own importers have one place to reach for.
+export { storedFilter } from "./event-model.js";
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Does this expression reference a scope anchor? The jq form of the mandatory-narrowing rule — a
+ * SYNTACTIC approximation of a question that was structurally decidable before, and the module
+ * header says plainly what that costs.
+ *
+ * Two things count, because both are legitimate ways to name where a subscription is scoped:
+ * the by-kind scope projection (`.scope.container`, or the ordered `.scopePath`), and a clause on
+ * one of the normalizer's declared {@link EventNormalizer.scopeKeys} (GitHub's `repo`), in either
+ * jq spelling — `.fields.repo` or `.fields["repo"]`.
+ */
+export function narrowsScope(expression: string, n: EventNormalizer): boolean {
+  if (/\.scope(Path)?\b/.test(expression)) return true;
+  for (const k of n.scopeKeys) {
+    const key = escapeRe(k);
+    if (new RegExp(String.raw`\.fields\s*(?:\.${key}\b|\[\s*"${key}"\s*\])`).test(expression)) return true;
+  }
+  return false;
+}
+
+/**
+ * CREATE-TIME validation, STATIC half. THROWS with copy naming what is legal — the house refusal
+ * pattern (`entity-actions.ts`, `channel-read.ts`). The half that has to RUN the expression lives in
+ * `jq-filter.ts` (`probeFilter`), because it is async and this is not; `create_routine` runs both,
+ * and `event-routing-test.ts` asserts both.
+ *
+ * ⚠️ TWO STRINGS, AND THE SECOND ONE IS THE ONE THAT RESOLVES (OPE-198 S2 + OPE-196 S3). `source` is
+ * the routine's declared subscription target — the hook's NAME — and it is what the refusal copy
+ * says, because it is the word the author typed. `scheme` is the registry key the vocabulary is
+ * actually read from. They are the same string for every category-(a) hook; they DIFFER for a
+ * category-(b) hook, where N senders share ONE contract under N distinct handles. Resolving by the
+ * name would refuse every valid (b) subscription with "unknown event source", which is a refusal the
+ * author cannot act on because the thing does exist.
+ */
+export function validateSubscription(source: string, expression: string | undefined, scheme: string = source): void {
+  const n = eventNormalizer(scheme);
+  if (!n) {
+    const known = registeredEventSources();
+    throw new Error(
+      `Unknown event source "${source}"${scheme === source ? "" : ` (it resolves to the "${scheme}" contract, which has no normalizer here)`} — ` +
+        (known.length ? `known sources: ${known.join(", ")}.` : "no event source is registered in this deployment.") +
+        " A subscription to an unknown source can never match anything, so it is refused rather than armed.",
+    );
+  }
+  if (expression !== undefined) assertFilterShape(expression);
+
+  // MANDATORY NARROWING — see the header, including why the jq form of it is weaker than the one it
+  // replaces. Only applies where the source can actually prove a container: a source that proves
+  // nothing narrower than a tenant has no narrowing to demand.
+  //
+  // …AND ONLY WHERE ONE `source` SPANS MANY CONTAINERS (OPE-196 S3). A `scopeHookConstant` contract
+  // derives its whole path from the receiving hook's row, so the subscription's `source` — which
+  // names ONE hook — has already pinned the container before this rule runs. Demanding a
+  // `.scope.container == "<that same hook's name>"` on top would be a restatement, not a narrowing,
+  // and the rule's own justification (the read grant authorizes CONTENT and says nothing about
+  // VOLUME) does not carry: the volume of a (b) hook is the volume of one sender we minted a key for.
+  if (n.scopeKinds.includes("container") && !n.scopeHookConstant) {
+    if (expression === undefined || !narrowsScope(expression, n)) {
+      throw new Error(
+        `A "${source}" subscription must narrow its scope: reference \`.scope.container\` (or another \`.scope.<kind>\`) ` +
+          `or ${n.scopeKeys.length ? n.scopeKeys.map((k) => `\`.fields.${k}\``).join(" / ") : "a scope field"} in the filter, ` +
+          `e.g. \`.scope.container == "acme/web" and .event == "pull_request"\`. ` +
+          "Subscribing to every event in the whole tenant has to be spelled out deliberately, not defaulted into.",
+      );
+    }
+  }
+}
+
+/** Why a stored subscription could not be evaluated — carried into the audit row, never thrown. */
+export type SubscriptionVerdict =
+  | { readonly match: boolean }
+  | { readonly match: false; readonly invalid: string };
+
+/**
+ * FIRE-TIME evaluation of one routine against one delivery. Total: every failure is a verdict, not
+ * an exception, because this runs inside an inbound-delivery loop where a throw would abort the
+ * fan-out for every OTHER matching routine as well.
+ *
+ * ASYNC since OPE-210. The evaluator is `bash.exec`, which is a promise even though the jq step
+ * inside it is synchronous. Callers await it inside a loop they were already awaiting in.
+ */
+export async function evaluateSubscription(routine: Routine, ev: NormalizedEvent): Promise<SubscriptionVerdict> {
+  const t = routine.trigger;
+  if (!isEventTrigger(t)) return { match: false };
+  // MATCHED ON THE **NAME**, WHOLE-STRING (OPE-198 S2 — event-model.ts's asymmetry note). A
+  // subscription names WHICH HOOK, not which contract: matching on the scheme instead would make
+  // every routine on `github` fire for every `github` hook in the org, which is exactly the
+  // per-sender independence the split exists to provide.
+  if (t.source !== ev.source) return { match: false };
+  // …but the REGISTRATION is checked against the **SCHEME**, because the normalizer is the
+  // contract's. Resolving this by `t.source` (the name) is a latent defect the moment name ≠ scheme:
+  // a perfectly valid subscription would report `invalid` because no normalizer is registered under
+  // the org's handle for the contract. Equal strings today; correct either way.
+  //
+  // This is now the ONLY fire-time re-validation, and the vocabulary drift it used to also catch —
+  // a `matchKeys` shrink across a deploy — no longer exists as a failure mode, because a jq path is
+  // not checked against a declared key list. What remains is a source whose normalizer has GONE:
+  // a de-selected provider bundle (`admitProviderRegistration`), which must fail closed rather than
+  // evaluate to "no clause matched anything, so it matched".
+  if (!eventNormalizer(webhookScheme(ev))) {
+    return { match: false, invalid: `no normalizer registered for source "${webhookScheme(ev)}"` };
+  }
+  const f = storedFilter(t);
+  // A STORED ROW THIS BUILD CANNOT READ NEVER FIRES (OPE-1145). It is the one case where the
+  // all-events reading below would be actively dangerous: the row was written to NARROW, and
+  // reading its unreadable filter as "no filter" would turn a deletion of two retired languages
+  // into a fire-hose on exactly the subscriptions nobody is looking at. Reported as `invalid`, not
+  // thrown, for the header's reason — one bad row must not abort the fan-out for every other
+  // routine — which also puts it in the audit log as a `routine.skip` a human can find.
+  if (f.kind === "unknown") {
+    return { match: false, invalid: `stored filter shape is unreadable in this build (${f.keys.join(", ")}) — a filter must be jq` };
+  }
+  // A filter-less STORED row keeps its legacy all-events meaning — the create-time reversal is
+  // deliberately not retroactive (see the header).
+  if (f.kind === "none") return { match: true };
+  const outcome = await evaluateJqFilter(f.expression, filterDocument(ev));
+  if ("error" in outcome) return { match: false, invalid: outcome.error };
+  return { match: outcome.match };
+}