@open-everywhere/core 0.1.0

package/agent/webhooks/config.ts

@@ -0,0 +1,556 @@
+// Webhook-trigger configuration — config-as-code, the admin console for the generic
+// inbound-webhook surface (the third leg of the trigger triad: manual mention, cron
+// routines, webhooks). Mirrors memory/config/domains.ts's shape: a static array the app
+// declares, validated once at load, read through the app-config seam (access/config.ts)
+// so core never imports app data directly.
+//
+// ⭐ ONE HOOK CLASS, TWO SHAPES OF CONSEQUENCE (OPE-224). `target` + `instruction` are OPTIONAL and
+// travel TOGETHER, which is the whole of the difference:
+//
+//   • FUSED (both present) — the hook fires ONE Slack surface with ONE standing instruction, and it
+//     ALSO emits into the event plane. That standing unattended prompt is reviewable intent, which
+//     is why the declaration lives in a diff.
+//   • EMIT-ONLY (both absent) — an ingress and nothing else. The accepted delivery goes to
+//     `admitTrigger` (routines/ingress.ts) and what HAPPENS is decided downstream by `event`
+//     routines, which are member-gated and card-armed. Its merit is COMPOSABILITY: the ingress can
+//     exist before anyone has decided what it should cause, the consequences can be changed later
+//     without touching the ingress, and several routines can hang off one door.
+//
+// ONE OF THE TWO ALONE IS REFUSED, never silently ignored (`assertWebhooksValid`): a target with no
+// instruction has nothing to say when it fires, and an instruction with no target has nowhere to say
+// it. Either way the author believed something false about what they declared.
+//
+// A FUSED hook is still ONE target: a hook id maps to exactly one Slack surface and one dispatch
+// instruction. Fan-out is the emit-only shape's job — a routine per surface subscribing to one hook
+// IS that fan-out, decided by whoever cares — so widening this to `targets: string[]` would be a
+// config shape change here and never a rethink of the gate/dispatch below.
+//
+// EMPTY BY DEFAULT — deploying with no hooks declared means POST /webhooks/<any-id>
+// always 404s. Give a hook a body here to make it live.
+//
+// THERE IS EXACTLY ONE HOOK CLASS (OPE-224). A hook may name `broker: "db"` so an operator arms its
+// secret through the one-shot reveal route with no redeploy and no value in the diff, which is the
+// only property a second, chat-created class ever offered.
+
+import { reservedRefNamespace } from "../credentials/reserved-refs.js";
+import { describeReadableBy, readableByDefects, type ReadableBy } from "../access/read-grant.js";
+import { webhookReach } from "./achievability.js";
+import { WEBHOOK_AUTH_GRADES, type WebhookAuthGrade } from "./verifier.js";
+import type { Domain } from "../memory/domain.js";
+
+/**
+ * 🔴 THE POSTURE AXIS (OPE-159) — the risk this design was previously not modelling at all.
+ *
+ * Tommy, 2026-07-27: *"if you just used a webhook's existence to trigger a flow then even if it
+ * could be exposed somehow it'd be low risk as it's just a trigger, but if you're acting on the
+ * info in a webhook without verifying it is correct then it's riskier."*
+ *
+ *   • `trigger-only`    — the payload is DISCARDED before anything reaches the model. Only the
+ *                         subscribing routine's OWN member-authored prompt runs. A leaked secret
+ *                         buys "cause a known prompt to run", and nothing else.
+ *   • `content-bearing` — the payload enters the prompt as untrusted data. This is the ONLY
+ *                         behaviour that existed before OPE-159 (webhooks/dispatch.ts).
+ *   • `projection`      — NAMED FIELDS ONLY (OPE-214). The delivery is normalized and exactly the
+ *                         declared keys are rendered; everything else — the raw body, the entity
+ *                         pointer, the actor handle — is dropped exactly as `trigger-only` drops it.
+ *
+ * This is also the honest answer to "why is a cron fine at member tier but a webhook is not?" — it
+ * is NOT the ingress. A cron's prompt is member-authored, in-channel, witnessed and FIXED. A
+ * webhook's prompt is too. The delta is that a content-bearing hook's PAYLOAD is authored by an
+ * outside party on every fire, forever: recurring unattended untrusted-content injection. That
+ * delta exists ONLY for `content-bearing`, which is why the tier table splits on it and not on the
+ * ingress.
+ *
+ * ⭐ WHY `projection` IS A THIRD MEMBER AND NOT A FLAG ON `content-bearing` (OPE-214). Posture is
+ * ONE axis — *how much of an outside party's bytes may reach the model* — and the three values are
+ * points on it (none / named fields / everything). A boolean beside `content-bearing` would make the
+ * question two-dimensional, and every consumer that switches on posture would then have to remember
+ * to consult the second dimension. Every such consumer in this tree is a total map or a switch, so a
+ * third member is a compile error at each of them; a forgotten flag is silence.
+ *
+ * 🔴 `projection` IS NOT A WEAKENING OF `trigger-only`, AND THE ORDERING THAT MAKES THAT TRUE IS IN
+ * `routines/event-model.ts` `normalizeDelivery`: redaction is tested FIRST and returns, so a
+ * delivery carrying both declarations is redacted and projects nothing. A posture whose purpose is
+ * keeping payloads away from humans cannot have a back door, and the back door a third posture could
+ * have opened is exactly "the projection ran anyway".
+ *
+ */
+export type WebhookPosture = "trigger-only" | "content-bearing" | "projection";
+
+export const WEBHOOK_POSTURES: readonly WebhookPosture[] = ["trigger-only", "content-bearing", "projection"] as const;
+
+export interface WebhookHook {
+  /** URL path segment — the hook fires at `POST /webhooks/<id>`. Url-safe token. */
+  readonly id: string;
+  /**
+   * WHICH SIGNATURE SCHEME authenticates this hook's deliveries — the key into the verifier
+   * registry (webhooks/verifier.ts). `"oe-standard-webhook"` is our own contract, for senders we configure;
+   * a vendor's source (`"github"`, `"notion"`, …) verifies in THAT VENDOR's scheme, which is
+   * what lets one generic ingress take a third-party system's webhooks unmodified.
+   *
+   * DECLARED, NEVER SNIFFED. The scheme is a property of the CONFIGURED SENDER, not of the
+   * request: letting the request pick (by "whichever signature header is present") would hand
+   * the attacker verifier selection, and with verifiers of differing strength registered that
+   * is a downgrade primitive. See webhooks/verifier.ts's module doc.
+   *
+   * REQUIRED — there is no default. An unregistered source is a fail-closed 401 naming the
+   * registered set (a source whose provider bundle is de-selected registers nothing, so its
+   * hooks stop authenticating rather than silently falling back to another scheme).
+   */
+  readonly source: string;
+  /**
+   * Reference(s) to this hook's shared HMAC secret — a POINTER, never the value
+   * (exactly `Connection.secretRef`'s rule, access/bundle.ts:85-99). What a ref
+   * NAMES depends on {@link broker}: for `"env"` it is the env var name, for `"db"`
+   * the stored-credential ref. Resolved through `getSecretVia` (webhooks/secrets.ts).
+   *
+   * ORDERED, CURRENT FIRST. A second (or third) entry is a ROTATION OVERLAP: the
+   * new key goes in at index 0, the outgoing one stays at index 1 until every sender
+   * has moved, then the entry is deleted. Deliveries verify against each key in
+   * order, so both are live during the overlap — the shape Stripe's endpoint-secret
+   * rotation also uses.
+   *
+   * ONE ORDERED LIST, NOT A SECOND `previousSecretRef` FIELD. Two fields would mean
+   * two code paths, and the previous-key path is the one that never runs until the
+   * day it must. With a list, N=1 and N=2 execute identical code, so every
+   * single-key test also covers the rotation path.
+   *
+   * No resolvable ref at index 0 ⇒ no keys ⇒ the delivery is rejected fail-closed
+   * (gate.ts). A missing ref at index >0 is NORMAL (the rotation finished and the
+   * old var was deleted) and is simply dropped.
+   */
+  readonly secretRef: string | readonly string[];
+  /**
+   * HOME broker every ref above resolves through (`"env"` | `"db"` | any registered
+   * name — access/credentials.ts registerBroker). REQUIRED: there is no selected
+   * default and no absent-means-env convenience, and an unregistered name FAILS
+   * CLOSED at `getSecretVia` rather than guessing (a coincidental value from the
+   * wrong broker is worse than a clear error). Stamp env-backed hooks `broker: "env"`.
+   *
+   * ONE broker for the WHOLE hook, deliberately: a rotation must not silently move
+   * custody homes mid-flight. Moving a hook from `env` to `db` is a separate,
+   * deliberate edit, not something a second ref can smuggle in.
+   *
+   * (Required here, unlike `Connection.broker` which is optional in the TYPE only so
+   * a never-resolved fixture connection needn't carry one. Every declared hook DOES
+   * resolve — a hook whose secret never resolves is a hook that always 401s.)
+   */
+  readonly broker: string;
+  /**
+   * Fully-qualified `slack/TEAM/CHANNEL` surface this hook posts into.
+   *
+   * ⭐ OPTIONAL, AND PAIRED WITH {@link instruction} (OPE-224). Absent (with `instruction` absent
+   * too) ⇒ this hook is EMIT-ONLY: it has no declared fire at all, and the accepted delivery's only
+   * consequence is the event-plane emission every hook already makes. See the module header.
+   * Present-without-`instruction` is REFUSED at validation, not defaulted.
+   */
+  readonly target?: string;
+  /**
+   * What the agent should DO when this fires, in NL — the analogue of a routine's
+   * `prompt`. Combined with a wake preamble + the untrusted-wrapped payload
+   * (webhooks/dispatch.ts renderWebhookMessage) into the turn's message.
+   *
+   * ⭐ OPTIONAL, AND PAIRED WITH {@link target} (OPE-224).
+   */
+  readonly instruction?: string;
+  /**
+   * ⭐ WHICH SURFACES MAY READ THIS HOOK'S EVENTS (OPE-209) — the ENTIRE confidentiality decision
+   * for this ingress, and the only authorization field on it.
+   *
+   * REQUIRED. NO DEFAULT. Absence is a compile error, and that is the point rather than strictness
+   * for its own sake: an implicit default is how the zero-domain trap (OPE-206) happened — a hook
+   * whose read grant was DERIVED from where it was created, which in a domainless channel derived to
+   * nothing and refused every routine forever with no chat-visible signal. A required field cannot
+   * be omitted into that state, and `assertWebhooksValid` refuses an empty list at import time.
+   *
+   * SHAPE: `access/bundle.ts`'s `Scope` — the vocabulary the deployer already writes bindings in.
+   * `{ level: "org" }` means EVERY domain in the org (org scope already matches every request, which
+   * is why there is no `ALL_DOMAINS` sentinel); `{ level: "domain", domain: "payments" }` names one.
+   * COMBINED BY UNION — may-read if ANY entry matches. See `access/read-grant.ts` for why the shape
+   * is shared with bundles but the combining rule deliberately is not.
+   *
+   * WHAT IT DOES NOT DO. It does not decide what a routine ACTS on — that is the routine's own
+   * filter, written by the person who cares, in a different language. And it is not an ISOLATION
+   * mechanism: ten teams that must not see each other's data need ten integrations, not one hook
+   * with a clever grant (read-grant.ts's header, doctrine 1).
+   */
+  readonly readableBy: ReadableBy;
+  /**
+   * ⭐ HOW MUCH OF THE PAYLOAD MAY REACH THE MODEL (OPE-214). See {@link WebhookPosture} for the axis.
+   *
+   * ABSENT ⇒ `content-bearing`, via {@link configHookPosture}.
+   *
+   * 🔴 AND THE DEFAULT IS DELIBERATELY *NOT* THE SAFE-BY-DEFAULT ONE — the one place that argument
+   * loses, for a reason specific to this class. A config declaration is not half-specified: it is a
+   * reviewed diff, read whole by a human, where an absent field is a fact about WHEN the file was
+   * written and not about what its author wanted. Defaulting those to `trigger-only` would silently
+   * stop every already-deployed hook from seeing the payload it was written to read — no error, no
+   * log, a product that quietly does less. That is the self-inflicted-outage failure mode this tree
+   * refuses elsewhere (webhooks/dispatch.ts's audience floor, `rotationOverlapMs`), and safety that
+   * arrives as an unannounced behaviour change is not safety.
+   *
+   * The half-specified case is answered where it actually occurs: `declare_webhook` makes posture an
+   * explicit, required choice, so nothing NEW is created without someone deciding.
+   */
+  readonly posture?: WebhookPosture;
+  /**
+   * The field keys a `projection` hook renders — REQUIRED when {@link posture} is `"projection"` and
+   * REFUSED otherwise (a key list that does nothing is a declaration whose author believed something
+   * false about it).
+   *
+   * They are `EventNormalizer` field keys — the normalizer's flattening of the payload
+   * (`routines/event-model.ts`), which is the layer that already knows what a delivery contains.
+   * Whether a named key is one the source's normalizer can actually produce is NOT decidable here:
+   * normalizers register at startup and this file validates at module import, the same ordering that
+   * makes {@link source} registration a delivery-time refusal rather than an import-time one. It is
+   * checked at `declare_webhook` propose time instead, where the registry is live.
+   */
+  readonly project?: readonly string[];
+  /**
+   * ⭐⭐ THE WEAKEST AUTHENTICATION THIS HOOK IS WILLING TO ACCEPT (OPE-203). The ladder, and what is
+   * deliberately NOT on it, is {@link import("./verifier.js").WebhookAuthGrade}; the enforcement is
+   * `webhooks/gate.ts`, which is the one place a declared source is resolved to a verifier.
+   *
+   * 🔴 DECLARED, NEVER INFERRED — the same rule, for the same reason, as {@link source}. A strength
+   * read off what a delivery happens to CARRY is a downgrade primitive: the sender picks the grade by
+   * choosing what to send. Here both inputs are ours (this field, and the registered verifier's
+   * `signedTimestamp`), so a hook's floor is the same on every delivery it will ever take.
+   *
+   * WHAT DECLARING ONE BUYS, concretely. Naming a source silently decides a replay posture today:
+   * `source: "github"` means no signed timestamp, therefore no single-use dedupe
+   * (`webhooks/replay-dedupe.ts`), and NOTHING anywhere says so. `authFloor: "signed-fresh"` turns
+   * that silence into a fail-closed 401 that names the mismatch, on the first delivery, forever —
+   * so a hook that was written believing it had replay defence cannot quietly not have it.
+   *
+   * ABSENT ⇒ NO FLOOR, i.e. exactly what every hook did before this field existed — and, as with
+   * {@link posture}, the default is deliberately NOT the strict one. A floor of `"signed"` by default
+   * would silently kill the local-dev hatch for every hook that had not opted out, which is a
+   * behaviour change arriving as an unannounced outage; the lever for turning the hatch off is
+   * `webhooks.allowUnverified` itself, which an operator turns off deliberately. Absence here is a fact
+   * about when the declaration was written, not a claim that any strength is acceptable.
+   *
+   * ⚠️ WHETHER THE DECLARED FLOOR IS ACHIEVABLE IS NOT CHECKED HERE. Achievability compares the floor
+   * to the REGISTERED verifier for the source, and verifiers register at startup while this file
+   * validates at module import — the same ordering that makes {@link source} registration and
+   * {@link project} key validity delivery-time and propose-time questions rather than import-time
+   * ones. `assertWebhooksValid` checks only that the value is a grade on the ladder.
+   */
+  readonly authFloor?: WebhookAuthGrade;
+}
+
+/**
+ * A hook that carries BOTH halves of a declared fire — the only shape `fireWebhook` accepts.
+ *
+ * Expressed as a narrowing of {@link WebhookHook} rather than as a second interface so there is
+ * still exactly ONE hook type: an emit-only hook is not a different kind of thing, it is this thing
+ * with no declared fire. Everything security-bearing (the gate, the secret resolution, `readableBy`,
+ * the posture, the replay dedupe) reads the WIDE type and therefore cannot diverge between them.
+ */
+export type FusedWebhookHook = WebhookHook & { readonly target: string; readonly instruction: string };
+
+/**
+ * ⭐ THE ONE PLACE "does this hook have a declared fire?" IS ASKED (OPE-224) — a type guard rather
+ * than a `hook.target &&` at each site, for the reason {@link configHookPosture} is a function: the
+ * pairing is a DECISION (`assertWebhooksValid` refuses one without the other), and a decision spread
+ * across N call sites is N places it can be spelled differently. It tests BOTH fields even though
+ * validation guarantees they agree, because a hook can reach the ingress from the overlay path and
+ * from a test fixture as well as from a validated registry, and the fail-safe direction for an
+ * un-validated hook is "no declared fire" — an emit-only delivery, not a half-rendered prompt.
+ */
+export function isFusedHook(hook: WebhookHook): hook is FusedWebhookHook {
+  return typeof hook.target === "string" && hook.target.length > 0 && typeof hook.instruction === "string" && hook.instruction.trim().length > 0;
+}
+
+/**
+ * THE ONE PLACE A CONFIG HOOK'S POSTURE IS DERIVED (OPE-214) — absent ⇒ `content-bearing`.
+ *
+ * A function rather than a `??` at each site for the same reason `hookReadableBy` is one: the
+ * absence rule is a decision, and a decision spread across N call sites is N places it can be
+ * spelled differently. Every consumer that asks "what may this hook disclose" goes through here.
+ */
+export function configHookPosture(hook: Pick<WebhookHook, "posture">): WebhookPosture {
+  return hook.posture ?? "content-bearing";
+}
+
+/**
+ * ⭐ THE DISCLOSURE FRAGMENT a config hook's posture contributes to a {@link TriggerDelivery} — the
+ * SINGLE translation from "what posture is this" to "what may be rendered", spread by both
+ * consequences a config hook now has (OPE-208): its own declared fire (`webhooks/dispatch.ts`) and
+ * its emission into the event-routing plane (`channels/webhooks.ts`).
+ *
+ * 🔴 ONE POSTURE VALUE PRODUCES AT MOST ONE FIELD, WHICH IS WHY `redactPayload` AND `project` CAN
+ * NEVER CO-OCCUR ON A CONFIG-BORNE DELIVERY. `normalizeDelivery` enforces the precedence anyway
+ * (redaction first, and it returns), so the guarantee holds even for a delivery this function did
+ * not build — belt here, braces there, and the braces are the load-bearing half.
+ *
+ * Returned as a spreadable fragment rather than as a posture the caller switches on, so a future
+ * fourth posture is added HERE and every ingress inherits it, instead of being added to a switch
+ * each ingress keeps its own copy of.
+ */
+export function configHookDisclosure(hook: Pick<WebhookHook, "posture" | "project">): {
+  readonly redactPayload?: true;
+  readonly project?: readonly string[];
+} {
+  switch (configHookPosture(hook)) {
+    case "trigger-only":
+      return { redactPayload: true };
+    case "projection":
+      // An absent/empty list cannot reach here on a VALIDATED hook (assertWebhooksValid refuses it),
+      // and if it somehow does the answer is the narrow one: withhold, never widen to the raw body.
+      return hook.project && hook.project.length > 0 ? { project: hook.project } : { redactPayload: true };
+    case "content-bearing":
+      return {};
+  }
+}
+
+/**
+ * Identity helper for readability + type inference, matching defineDomain/defineBundle.
+ *
+ * GENERIC IN THE ARGUMENT (OPE-224) so the literal's own shape SURVIVES the call. Now that `target`
+ * and `instruction` are optional, a `WebhookHook`-returning signature would widen every declaration
+ * to "might be emit-only" — so a hook that plainly declares both would stop being accepted by
+ * `fireWebhook`, which takes {@link FusedWebhookHook}, and every caller would need a cast to say
+ * something the literal already said. The constraint still rejects anything that is not a hook.
+ */
+export function defineWebhook<T extends WebhookHook>(hook: T): T {
+  return hook;
+}
+
+/**
+ * The hook's secret refs as an ORDERED list, current first — the single normalisation
+ * seam for `secretRef`'s `string | string[]` union. Everything downstream (validation,
+ * resolution, the rejection message) reads the list, so the one-ref and two-ref cases
+ * are the same code path from here on.
+ *
+ * Takes the structural MINIMUM rather than a whole `WebhookHook` (OPE-150), so the gate can resolve
+ * secrets for any hook-shaped subject without that subject growing fields it has no meaning for.
+ */
+export function hookSecretRefs(hook: Pick<WebhookHook, "secretRef">): readonly string[] {
+  return typeof hook.secretRef === "string" ? [hook.secretRef] : hook.secretRef;
+}
+
+const ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate the webhook registry at load (fail loud on a misconfiguration, same posture
+ * as assertDomainsValid/assertBundlesValid): unique, url-safe ids; every field present;
+ * `target` is a well-formed `slack/TEAM/CHANNEL` triple. Webhook targets stay
+ * Slack-only today — a config string can name a channel id up front, but not e.g. a
+ * Teams conversation reference, which only exists once captured off an inbound turn.
+ * ROUTINES fire into Slack/Discord/Teams because they capture the full
+ * adapter target from the live surface binding at creation
+ * (schedules/dispatch.ts resolveTarget).
+ *
+ * ⭐ AND SINCE OPE-215 IT ALSO ASKS WHETHER THE DECLARATION IS *ACHIEVABLE*, not merely well-formed
+ * — doctrine 6, "nothing validates that a declared trigger's consequences are achievable from where
+ * it will fire". Two things become checkable the moment `deps.domains` is supplied: whether the read
+ * grant names domains that exist, and whether the hook's own target channel could host a routine
+ * that reads it. Before this, a hook could name a domain nobody declared and fail silently at every
+ * fire, forever.
+ *
+ * 🔴 THE TWO STRENGTHS ARE NOT INTERCHANGEABLE, and neither is a security boundary — fire time is
+ * still the only belt (`webhooks/achievability.ts`'s header):
+ *   • an `impossible` finding THROWS, joining the fail-loud rules above. It is decidable and
+ *     certainly wrong, so the diff can be fixed while a human is reading it.
+ *   • an `unreachable` finding WARNS. It is decidable and probably wrong but legitimately
+ *     constructible, and a boot failure over a probably is a self-inflicted outage.
+ *   • an UNDECIDABLE check says nothing at all. `deps.domains` is optional precisely because this
+ *     validator runs at module import, where the app-config seam may not be armed — and "we could
+ *     not ask" must never become a refusal.
+ */
+export interface WebhookValidationDeps {
+  /**
+   * The deployment's memory domains, for the achievability sweep (OPE-215). OMITTED ⇒ the sweep is
+   * INERT: every reachability question goes unasked and nothing is reported. The app passes
+   * `loadDomains()`; a caller validating a candidate overlay in a tool passes the live registry.
+   */
+  readonly domains?: readonly Domain[];
+  /** Where an `unreachable` finding is reported. Injected so a test can capture it, and so the sweep
+   *  never assumes a console exists. */
+  readonly warn?: (message: string) => void;
+}
+export function assertWebhooksValid(hooks: readonly WebhookHook[], deps: WebhookValidationDeps = {}): void {
+  const seen = new Set<string>();
+  for (const h of hooks) {
+    if (!h.id || !ID_RE.test(h.id)) {
+      throw new Error(`webhook hook id ${JSON.stringify(h.id)} must be a non-empty url-safe token ([a-zA-Z0-9_-]+)`);
+    }
+    if (seen.has(h.id)) throw new Error(`duplicate webhook hook id "${h.id}"`);
+    seen.add(h.id);
+    // source: REQUIRED and non-blank. Whether it is REGISTERED is checked at RESOLUTION, not
+    // here — verifiers register at startup (core's own at module load, a provider's from its
+    // register fn) while this validator runs at module import, so an unknown source has to fail
+    // closed later (webhooks/gate.ts), loudly, naming the registered set.
+    if (!h.source || !h.source.trim()) {
+      throw new Error(
+        `webhook "${h.id}" is missing source — name the signature scheme its sender uses (\`source: "oe-standard-webhook"\` for a sender you configure, or a vendor's source like "github"); there is no default`,
+      );
+    }
+    // secretRef: a NON-EMPTY ordered list of non-blank refs. An empty list (or a blank
+    // entry inside one) is a hook that can never authenticate anything — caught here, at
+    // import time, rather than as a mystery 401 in production.
+    const refs = hookSecretRefs(h);
+    if (refs.length === 0) {
+      throw new Error(`webhook "${h.id}" has an empty secretRef list — it needs at least one ref (current key first)`);
+    }
+    for (const [i, ref] of refs.entries()) {
+      if (typeof ref !== "string" || !ref.trim()) {
+        throw new Error(`webhook "${h.id}" secretRef[${i}] is blank — each entry must name where the shared secret lives (a ref, never the value)`);
+      }
+      // RESERVED REF NAMESPACES (OPE-150). `hook:`/`oe-oauth:`/`notion-handshake:` hold secret
+      // material the HOST minted or captured for itself; a declaration pointing at one would be
+      // reading the OAuth adapter's token or a vendor's handshake key. `makeDbCredentialBroker`
+      // refuses these at RESOLUTION too — this is the build-time half, so the mistake is caught
+      // where a human can still fix it in the diff.
+      //
+      // 🔴 THE LIST STAYS AS-IS EVEN THOUGH NOTHING MINTS `hook:` ANY MORE (OPE-224). It is
+      // documented additive-only because removing a prefix WIDENS what the outbound resolver will
+      // accept, and a leftover row from a pre-collapse deployment must not become egress-resolvable.
+      const reserved = reservedRefNamespace(ref);
+      if (reserved) {
+        throw new Error(
+          `webhook "${h.id}" secretRef[${i}] is in the reserved "${reserved}" namespace — that namespace holds secret material this ` +
+            `deployment minted or captured for itself (an OAuth token, a vendor handshake key). Point at your own ref instead.`,
+        );
+      }
+    }
+    if (new Set(refs).size !== refs.length) {
+      throw new Error(`webhook "${h.id}" repeats a secretRef — a rotation overlap lists DISTINCT refs (current first, then the outgoing one)`);
+    }
+    // broker: REQUIRED and non-blank. Registration is checked at RESOLUTION, not here — a
+    // broker registers at startup (register-adapters.ts) and this validator runs at module
+    // import, so an unregistered name has to fail closed later (webhooks/secrets.ts), loudly.
+    if (!h.broker || !h.broker.trim()) {
+      throw new Error(`webhook "${h.id}" is missing broker — name the ONE home its secretRef(s) resolve through (\`broker: "env" | "db" | ...\`); there is no default`);
+    }
+    // ⭐ `target` AND `instruction` IMPLY EACH OTHER, IN BOTH DIRECTIONS (OPE-224) — and neither
+    // direction is tidiness. A target with no instruction fires a channel with nothing to say; an
+    // instruction with no target says it nowhere. Both are declarations whose author believed a
+    // consequence was being armed when none was, and neither is discoverable by watching the hook
+    // work: the ingress still authenticates, still accepts, and still emits into the event plane, so
+    // the only symptom is a room that never hears anything.
+    //
+    // BOTH ABSENT is the EMIT-ONLY shape and is entirely legitimate — the consequences live in
+    // `event` routines instead. It is refused nowhere.
+    const hasTarget = h.target !== undefined;
+    const hasInstruction = h.instruction !== undefined && h.instruction.trim().length > 0;
+    if (hasTarget !== hasInstruction) {
+      throw new Error(
+        hasTarget
+          ? `webhook "${h.id}" declares a target (${JSON.stringify(h.target)}) but no instruction — a fired channel with nothing to say. Add the instruction, or drop the target to declare an EMIT-ONLY hook whose consequences are decided by \`event\` routines.`
+          : `webhook "${h.id}" declares an instruction but no target — there is nowhere for it to run. Add the "slack/TEAM/CHANNEL" target, or drop the instruction to declare an EMIT-ONLY hook whose consequences are decided by \`event\` routines.`,
+      );
+    }
+    if (h.target !== undefined) {
+      const parts = h.target.split("/");
+      if (parts.length !== 3 || parts[0] !== "slack" || !parts[1] || !parts[2]) {
+        throw new Error(`webhook "${h.id}" target must be a fully-qualified "slack/TEAM/CHANNEL" surface, got ${JSON.stringify(h.target)}`);
+      }
+    }
+    // readableBy: REQUIRED, NON-EMPTY, and every entry a well-formed Scope. The type already makes
+    // absence a compile error; this catches the JSON/overlay path (webhooks/hooks-codemod.ts) where
+    // there is no compiler, and it is where the zero-domain trap (OPE-206) stops being reachable.
+    // The error NAMES what the grant would mean, so a reviewer reading a fail-loud boot log sees the
+    // consequence and not just the shape.
+    const grantDefects = readableByDefects(h.readableBy);
+    if (grantDefects.length > 0) {
+      throw new Error(
+        `webhook "${h.id}" has an invalid readableBy (which surfaces may read this hook's events — there is no default):\n` +
+          grantDefects.map((d) => `  ${d}`).join("\n") +
+          `\n  as written it would grant: ${describeReadableBy(h.readableBy)}`,
+      );
+    }
+    // POSTURE (OPE-214). The TYPE already restricts it; this catches the JSON/overlay path
+    // (webhooks/hooks-codemod.ts), which has no compiler. An unknown value must NOT fall through to
+    // the `content-bearing` default — a typo'd `"trigger_only"` silently disclosing the whole
+    // payload is the exact inversion this field exists to prevent.
+    if (h.posture !== undefined && !WEBHOOK_POSTURES.includes(h.posture)) {
+      throw new Error(
+        `webhook "${h.id}" has an unknown posture ${JSON.stringify(h.posture)} — how much of the payload may reach the model is ${WEBHOOK_POSTURES.join(" | ")}. ` +
+          `Omit it for "content-bearing" (what every config hook did before the field existed).`,
+      );
+    }
+    // `project` and `posture: "projection"` IMPLY EACH OTHER, in both directions, and both
+    // directions are a real mistake rather than tidiness. A projection with no keys renders nothing
+    // forever while looking configured; a key list on any other posture is a declaration whose
+    // author believed a narrowing was happening when the whole body (or none of it) was going
+    // through. Neither can be discovered by watching the hook work.
+    const posture = configHookPosture(h);
+    if (posture === "projection") {
+      if (!h.project || h.project.length === 0) {
+        throw new Error(
+          `webhook "${h.id}" declares posture "projection" but no \`project\` keys — a projection with nothing to project renders no payload at all, which is what posture "trigger-only" is for. Name the normalizer field keys to render, or change the posture.`,
+        );
+      }
+      for (const [i, key] of h.project.entries()) {
+        if (typeof key !== "string" || !key.trim()) {
+          throw new Error(`webhook "${h.id}" project[${i}] is blank — each entry names one normalizer field key to render`);
+        }
+      }
+      if (new Set(h.project).size !== h.project.length) {
+        throw new Error(`webhook "${h.id}" repeats a \`project\` key — the list is rendered in declaration order, so a repeat would print one field twice`);
+      }
+    } else if (h.project !== undefined) {
+      throw new Error(
+        `webhook "${h.id}" sets \`project\` but its posture is "${posture}" — the key list is only read under posture "projection". As written it narrows nothing: ` +
+          (posture === "trigger-only" ? "a trigger-only hook renders no payload at all." : "a content-bearing hook renders the WHOLE body."),
+      );
+    }
+    // AUTH FLOOR (OPE-203). Same posture as POSTURE above, and for the same reason: the TYPE
+    // restricts it, this catches the JSON/overlay path (webhooks/hooks-codemod.ts) which has no
+    // compiler. An unknown value must NOT fall through to "no floor" — a typo'd `"signed_fresh"`
+    // silently accepting deliveries the author meant to refuse is the exact inversion this field
+    // exists to prevent, and it inverts SILENTLY because a floor that is never met looks identical
+    // to a floor that was never declared.
+    //
+    // Only membership of the ladder is checkable here. Whether the floor is ACHIEVABLE for this
+    // hook's source needs the verifier registry, which is not armed at module import — see the
+    // field's own doc, and `webhooks/gate.ts` for where it IS asked.
+    if (h.authFloor !== undefined && !WEBHOOK_AUTH_GRADES.includes(h.authFloor)) {
+      throw new Error(
+        `webhook "${h.id}" has an unknown authFloor ${JSON.stringify(h.authFloor)} — the weakest acceptance a hook will take is ${WEBHOOK_AUTH_GRADES.join(" | ")}. ` +
+          `Omit it for no floor (what every config hook did before the field existed).`,
+      );
+    }
+    // ── ACHIEVABILITY (OPE-215) ───────────────────────────────────────────────────────────────
+    // Runs LAST, and only over a hook whose SHAPE already passed: a reachability sentence about a
+    // hook with a malformed target would be noise on top of the real error. Inert unless the caller
+    // supplied a domain registry.
+    const reach = webhookReach(h, deps.domains);
+    if (reach.impossible.length > 0) {
+      throw new Error(
+        `webhook "${h.id}" declares a consequence that can never happen:\n` +
+          reach.impossible.map((d) => `  ${d}`).join("\n") +
+          `\n  This is refused rather than warned because it is decidable now and no later state makes it match.`,
+      );
+    }
+    for (const warning of reach.unreachable) {
+      // NOT a throw: see the type's doc. `console.warn` by default so a boot log shows it, and
+      // injectable so a caller with a better channel (a PR body, a chat refusal) can take it.
+      (deps.warn ?? ((m: string) => console.warn(m)))(`[open-everywhere:webhooks] "${h.id}": ${warning}`);
+    }
+  }
+}
+
+/**
+ * 🔴 WHICH *OTHER* DECLARED HOOKS NAME `ref` (OPE-224) — the guard anything that WRITES a hook's
+ * secret must consult first.
+ *
+ * `secretRef` is an INDIRECTION, so N hooks pointing at ONE ref is already representable — a
+ * deliberate shape for a vendor that signs every subscription with one app credential. Anything that
+ * WRITES a hook's secret (the one-shot arm/rotate route) would, under that shape, silently re-key
+ * every other hook sharing the ref: integrations nobody asked to break, dying with no card, no audit
+ * row of their own and no error anyone can trace back. So a writer asks this FIRST and refuses by
+ * name rather than assuming refs are private.
+ *
+ * THE REGISTRY IS THE AUTHORITY HERE, not a naming convention: the deployer wrote both declarations,
+ * so the only truthful answer to "does anything else authenticate with this key" is to read them.
+ */
+export function hooksSharingSecretRef(hooks: readonly WebhookHook[], hookId: string, ref: string): readonly string[] {
+  return hooks.filter((h) => h.id !== hookId && hookSecretRefs(h).includes(ref)).map((h) => h.id);
+}
+
+/** Look up a hook by its path id, or undefined — the 404 case is "no hook found". */
+export function findWebhook(hooks: readonly WebhookHook[], id: string): WebhookHook | undefined {
+  return hooks.find((h) => h.id === id);
+}