@open-everywhere/core 0.1.0

package/dist/agent/routines/ingress.js

@@ -0,0 +1,703 @@
+// ingress — `admitTrigger`, THE single transport-agnostic entry point into the event-routing plane
+// (OPE-179, S6 of the plane designed in OPE-163).
+//
+// WHAT THIS IS, IN ONE SENTENCE: every event source — an HTTP webhook today, an SQS consumer, an
+// EventBridge target, a Vercel queue, a poller tomorrow — verifies its own credentials in its own
+// transport's terms, then hands core exactly one {@link TriggerDelivery} and gets back exactly one
+// {@link TriggerReport}. Verification → routing → grant → hydration → fire is then IDENTICAL for all
+// of them, because there is only one copy of it and it lives below this line.
+//
+// 🔴 THE PROPERTY THAT MAKES IT A SEAM AND NOT A FUNCTION CALL: nothing transport-shaped crosses it.
+// No `Request`, no URL, no method, no status code, no queue ARN, no visibility timeout, no ack token
+// ("core params never encode hosting topology", applied to ingress — the same rule that keeps
+// surface identity out of core tool params). A queue consumer synthesises `headers` from message
+// attributes and lands on the same shape the HTTP route builds from real headers. The ONE
+// transport-shaped thing crosses OUTWARD: {@link TriggerReport}, so a queue consumer can decide
+// delete-vs-redrive from a value core computed without knowing a queue exists.
+//
+// WHY THE SEAM IS *HERE* AND NOT AT THE ROUTE. Verification genuinely IS per-transport — an HMAC
+// header, SQS IAM, an EventBridge invocation identity and a JWKS-backed JWT have nothing in common
+// but their conclusion — so it stays UPSTREAM, enforced the way `webhooks/gate.ts` already is. What
+// must NOT be per-transport is everything after it: dedupe, normalization, the declarative filter,
+// the read grant, the audience floor, hydration, the fan-out cap, the fire. A second ingress that
+// re-implemented any of those would be a second security posture nobody would notice diverging.
+//
+// EXTRACTED VERBATIM FROM `routines/github-fanout.ts`, which is now a thin GitHub-shaped ADAPTER
+// over this module (build a TriggerDelivery, call admitTrigger). Every comment below was written
+// against a live defect and is kept with the code it explains — OPE-139/143/144/145/163/166/178/180
+// all landed as arms of this loop.
+//
+// A DECLARED HOOK'S DELIVERY COMES THROUGH HERE AS A **SECOND** CONSEQUENCE, NEVER INSTEAD OF ITS
+// OWN (OPE-208/209). Its DECLARED fire is authorized by an operator's merged code declaration
+// (id → target → instruction), not by a subscription filter over a normalized event, so there is
+// nothing here for that fire to be routed BY and `webhooks/dispatch.ts` fires it directly.
+// `channels/webhooks.ts`'s `emitConfigHookEvent` hands the SAME accepted delivery to `admitTrigger`
+// as well, where routines subscribe to the hook's **id** and are authorized by the hook's own
+// `readableBy`. Two independent consequences from one delivery, neither replacing the other — and it
+// is what makes `readableBy` load-bearing on a declared hook rather than declared and unread.
+//
+// 🔴 A HOOK WHOSE `source` NAMES A BARE SIGNATURE SCHEME CAN HAVE NO NORMALIZER AT ALL — a scheme
+// describes how bytes were SIGNED and says nothing about what they mean, so there is no payload
+// shape to normalize. That is expressed as an OUTCOME rather than a gate: such a delivery simply
+// routes nothing and the reason is recorded on the audit row as `routingReason`. Expressing it as an
+// outcome is what let declared hooks join this seam without softening anything.
+//
+// ⭐⭐ THE DIVIDING LINE IS "DOES SOMETHING OWN THIS PAYLOAD'S SHAPE", not "generic vs vendor"
+// (OPE-196). For a contract where WE DEFINE THE PAYLOAD SHAPE and the caller implements it
+// (`webhooks/oe-standard-webhook.ts`) the normalizer is ours to write, so such a hook DOES route
+// here, exactly like a vendor one.
+import { bridgeConfirmChannelInternal } from "../channels/slack-bridge.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { resolveRoutineTarget } from "../schedules/routine-dispatch.js";
+import { mintWakeId } from "../channels/unified-window.js";
+import { taintedFireAttrs } from "../access/taint-signal.js";
+import { listAllRoutines } from "./store.js";
+import { routineFireAttributes } from "./fire-auth.js";
+import { recheckFireCreator } from "./fire-creator.js";
+import { routinePartition } from "./partition.js";
+import { routineFireHalted } from "./fire-halt.js";
+import { scopeOverBudget } from "../spend/check.js";
+import { getSettings } from "../settings/settings.js";
+import { divertTriggeredFire, runFireSeatKey } from "./fire-window.js";
+import { auditRoutineFireLost, auditRoutineSkip } from "./fire-audit.js";
+import { foldRoutineOutcome } from "./outcome-fold.js";
+import { eventPrompt } from "./events.js";
+import { preFireFallback, runPreFire } from "./pre-fire.js";
+import { normalizeDelivery } from "./event-model.js";
+import { evaluateSubscription, isEventTrigger, storedFilter } from "./event-match.js";
+import { stampSubscriptionMatch } from "./match-stamp.js";
+import { captureDocument } from "../webhooks/capture-window.js";
+import { CAPTURE_MAX_DELIVERIES } from "../operational/store.js";
+import { checkEventReadGrant, eventGrantPartitions } from "./event-authz.js";
+import { announceFireWithheld, checkFireDisclosure, } from "./fire-disclosure.js";
+import { hydratePointer, newHydrationMemo, renderHydratedEntity, } from "./entity-read.js";
+function log(msg) {
+    console.log(`[open-everywhere:routines] ${msg}`);
+}
+// A single delivery can match an unbounded number of event routines, and the fan-out loop is
+// SEQUENTIAL inside ONE background task — every fire is awaited before the next starts. So the real
+// failure mode is not a concurrency burst (as it is for the clock dispatcher) but an
+// unbounded-DURATION background task: the platform cuts the function off part-way and the TAIL of
+// the match set silently never fires, with nothing anywhere saying so.
+//
+// The cap mirrors the clock dispatcher's DEFAULT_MAX_CONCURRENCY (schedules/dispatch.ts) — same
+// default, same "positive integer or fall back" parsing — but its overflow handling is DIFFERENT on
+// purpose. The clock leg can DEFER: it leaves nextRunAt untouched so the routine stays due and is
+// re-claimed next tick. An `event` trigger has no such "later" — computeNextRun returns nothing for
+// it (routines/schedule.ts only computes clock kinds) and the delivery is gone once acked. So an
+// over-cap event fire is a genuine DROP, and the only honest thing to do is make it VISIBLE: every
+// over-cap match writes a `routine.skip` audit row (reason `fanout_cap`) naming the routine, the
+// event and the cap. Silently-not-firing and deliberately-skipping must never look the same from
+// the outside.
+//
+// The row lives in the SHARED routine-forensics vocabulary (routines/fire-audit.ts) — one action,
+// with `reason` carrying the difference, rather than a second skip vocabulary per leg (OPE-145).
+// Two properties of it are load-bearing:
+//   • the write is THROTTLED (one row per routine+reason per hour, with a carried `suppressed`
+//     count). This leg is driven by INBOUND DELIVERIES, not by our own clock, so an unthrottled
+//     per-delivery write into an append-only, hash-chained, per-org-serialised table is an
+//     audit-write amplifier — exactly the defect webhooks/reject-audit.ts was created to fix;
+//   • the UNWIRED case is audited too (reason `unresolved_target`), not log-only: log-only means a
+//     Discord/Teams event routine whose target went stale silently never fires again.
+function eventMaxFanOut() {
+    return getSettings().routines.eventMaxFanout;
+}
+/** Replay-dedupe window for one delivery id. Matches the inbound-webhook dedupe TTL the
+ *  Slack/Teams fronts use (10 min) — comfortably longer than any vendor redelivery window. */
+export const DELIVERY_DEDUPE_TTL_MS = 10 * 60_000;
+/** Bound on the delivery id REPORTED back to the transport for the audit row ({@link TriggerReport}).
+ *  The value is sender-supplied and therefore unbounded; the same rule webhooks/reject-audit.ts
+ *  applies to a caller-supplied hook id applies to anything a caller can put in a permanent row. */
+export const DELIVERY_ID_MAX_CHARS = 200;
+/**
+ * Dedupe-key namespace for one delivery, so a vendor delivery id can never collide with an inbound
+ * Slack event id or an outbound postOnce key in the shared `event_dedupe` table.
+ *
+ * 🔴 SOURCE-SCOPED (OPE-179), and it must stay that way: `admitTrigger` is open to any transport, so
+ * two sources whose id spaces overlap (a UUID from a queue, a numeric id from a poller) would
+ * otherwise silently suppress each other's deliveries. Changing this prefix resets the dedupe window
+ * ONCE, for at most {@link DELIVERY_DEDUPE_TTL_MS}, at the deploy that lands it — the same class of
+ * event this guard already fails OPEN on (a store outage — see {@link liveMarkSeen}), because dedupe
+ * prevents an annoyance, not a security hole.
+ */
+export function deliveryDedupeKey(source, deliveryId) {
+    return `trigger:${source}:${deliveryId}`;
+}
+// Durable replay dedupe. FAIL-OPEN on a store error, the same posture (and for the same reason) as
+// slack-front.ts's liveMarkEventSeen: dedupe prevents an annoyance (a double fire), not a security
+// hole, so a store outage must never swallow genuine deliveries.
+let warnedDedupeStore = false;
+async function liveMarkSeen(org, key, atIso, ttlMs) {
+    try {
+        return await getOperationalStore().markEventSeen(org, key, atIso, ttlMs);
+    }
+    catch (err) {
+        if (!warnedDedupeStore) {
+            warnedDedupeStore = true;
+            console.warn(`[open-everywhere:routines] durable delivery dedupe unavailable — replays may double-fire: ${String(err)}`);
+        }
+        return true;
+    }
+}
+/** What a skipped subscription HOLDS, for the audit row's `filter` field. Three stored readings, and
+ *  the third one must not borrow either of the other two's words: an unreadable row is neither an
+ *  expression nor "no filter", so it names its offending keys instead. */
+function auditFilterText(t) {
+    const f = storedFilter(t);
+    if (f.kind === "jq")
+        return f.expression;
+    return f.kind === "none" ? "(none)" : `(unreadable stored shape: ${f.keys.join(", ")})`;
+}
+// Fire every active event-routine of THIS org that subscribed to this event into its own surface.
+// Stamps the full routine fire-auth bag so the fired session binds to the routine's REAL partition
+// and the outcome hook attributes ok/failed back (event routines self-disable on repeated failure
+// too). Surfaces with no wired channel/target are skipped (logged); matches past the cap are
+// skipped AND AUDITED.
+async function fanOut(ev, deps) {
+    const org = deps.org ?? deploymentOrg();
+    const list = deps.listRoutines ?? listAllRoutines;
+    const resolveTarget = deps.resolveTarget ?? resolveRoutineTarget;
+    const confirmInternal = deps.confirmInternal ?? bridgeConfirmChannelInternal;
+    // Forensics edges (OPE-145), passed straight through to routines/fire-audit.ts so a test can
+    // drive both the audit sink and the throttle's first-sighting primitive. `principalId` names the
+    // INGRESS as the actor on this leg — the clock leg's synthetic dispatcher principal would be a
+    // lie here (nothing on a schedule caused this) — and it is derived from the delivery's own
+    // declared source, so a queue-borne delivery is attributable to the queue, not to a webhook.
+    const auditDeps = {
+        ...(deps.audit ? { audit: deps.audit } : {}),
+        ...(deps.markSeen ? { markSeen: deps.markSeen } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+        principalId: `${ev.source}:webhook`,
+    };
+    // OPE-184 — the same shape, for the subscription-liveness stamp: this delivery's injected
+    // clock/throttle by default, with an explicit `matchStamp` winning over both so a test can drive
+    // the stamp without also re-pointing the delivery dedupe.
+    const stampDeps = {
+        ...(deps.markSeen ? { markSeen: deps.markSeen } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+        ...(deps.matchStamp ?? {}),
+    };
+    // A LOST FIRE ON THIS LEG: the forensic row AND the strike, in ONE place (OPE-180).
+    //
+    // THE ASYMMETRY THIS CLOSES. `foldRoutineOutcome` (routines/outcome-fold.ts) had exactly two
+    // callers — the session-end hook and the CLOCK leg's delivery-rejection catch. This leg had
+    // neither: a rejected delivery wrote `routine.fire_lost` and stopped, so `consecutiveFailures`
+    // stayed 0 forever and an event routine firing into a channel the bot was removed from retried on
+    // EVERY matching delivery, indefinitely. Clock routines got OPE-146's three-strike self-disable;
+    // event routines got a growing pile of rows. (Partial coverage before this: an event fire that DID
+    // start a session still folded via the session-end hook, because the marker rides on the session
+    // auth — the gap was specifically delivery REJECTION, where no session exists to end.)
+    //
+    // 🔴 ONE DELIVERY MATCHING N ROUTINES STRIKES EACH ROUTINE AT MOST ONCE — never one routine N
+    // times, and deliberately NOT "once per surface failure". The strike belongs to the (routine, fire
+    // attempt) pair, exactly as it does on the clock leg:
+    //   • a routine appears at most once in `matches` (it is a filter over distinct store rows), so
+    //     the amplification worth fearing — N strikes onto ONE routine from ONE delivery — is
+    //     structurally impossible, not merely unlikely;
+    //   • N routines sharing one dead surface each taking one strike is CORRECT, and is what the clock
+    //     leg already does (three routines on an archived channel each disable themselves over their
+    //     own ticks). Collapsing to one strike per surface would leave N-1 routines permanently
+    //     un-struck — reinstating "retries forever" for all but one of them — and would need
+    //     cross-routine state the fold has no notion of.
+    // The genuine difference from the clock leg is RATE, not count: this leg is driven by inbound
+    // deliveries, so three strikes can land in seconds rather than three tick cadences. Two guards
+    // already bound that, and both pre-date this ticket: the durable REPLAY DEDUPE above means a
+    // redelivery of the same delivery id — precisely what a non-2xx from us provokes — never
+    // re-enters the fan-out, so one rejected delivery cannot strike twice; and over-cap matches take
+    // the skip path, which by construction cannot fold. Converging faster on a genuinely dead surface
+    // is the goal ("removing it from the surface ends it"), and a time-based strike throttle here
+    // would be machinery the clock leg does not have — divergence is the exact failure outcome-fold.ts
+    // exists to prevent.
+    //
+    // BOTH lost-fire sites on this leg go through here, which is what makes OPE-178's structural
+    // no-strike rule literally true rather than merely intended: a hydration `error` is a lost fire and
+    // strikes; hydration `forbidden`/`gone` route to `auditRoutineSkip`, which never reaches this
+    // function. No suppression flag, no dead guard.
+    //
+    // ORDER IS LOAD-BEARING (same as schedules/dispatch.ts): the `routine.fire_lost` row is written
+    // FIRST so the loss is recorded even if the fold's store write is the broken thing, and the fold's
+    // own failure is logged and swallowed — bookkeeping must never turn a lost fire into an unhandled
+    // rejection out of the fan-out's single sequential loop, where it would take out every LATER
+    // routine's fire as collateral.
+    const loseFire = async (r, error) => {
+        await auditRoutineFireLost(r, error, auditDeps);
+        try {
+            const folded = await foldRoutineOutcome({
+                marker: { id: r.id, surfaceKey: r.surfaceKey, org: r.org },
+                sessionOutcome: "failed",
+                at: deps.now?.() ?? new Date(),
+            });
+            if (folded.folded) {
+                log(`lost fire folded for ${r.id} [${r.surfaceKey}] ` +
+                    `(fails=${folded.consecutiveFailures}${folded.disabled ? ", AUTO-DISABLED" : ""})`);
+            }
+        }
+        catch (foldErr) {
+            log(`lost-fire fold skipped for ${r.id}: ${String(foldErr)}`);
+        }
+    };
+    // ORG FILTER (OPE-139). listAllRoutines is cross-tenant by design; a delivery arriving on THIS
+    // deployment's ingress may only ever fire THIS deployment's tenant. Without it a hosted
+    // multi-tenant instance would fan one org's event into another org's channels.
+    //
+    // STAGE 2 — the FILTER (OPE-163, now a jq predicate per OPE-210). Non-throwing by contract: a
+    // filter that will not parse, that yields something other than a boolean, that exceeds an
+    // evaluation limit, or whose source's normalizer has been de-selected yields NO MATCH plus an
+    // AUDITED skip, never an exception — a throw here would take out every OTHER matching routine's
+    // fire as collateral, since the fan-out is one sequential loop.
+    //
+    // 🔴 A BROKEN FILTER MUST BE VISIBLE, NOT SILENT (§2.7). "Why didn't my routine fire" is the most
+    // common question this plane gets, and a filter that errors is its most confusing answer — it
+    // looks exactly like "nothing has happened yet". So the skip row carries the reason AND the
+    // expression that produced it: without the expression, a reader has a message ("Unknown function:
+    // input_filename") with nothing to attach it to, and the row is throttled per (routine, reason) so
+    // it costs one row per window however hot the delivery stream is. The routine is deliberately NOT
+    // struck for it (fire-audit.ts RoutineSkipReason.filter_invalid) — config drift is not the
+    // routine's fault, and a strike would let one deploy 3-strike-disable a whole fleet.
+    //
+    // The skip row's `filter` field says what the ROW HOLDS, which for an unreadable row (OPE-1145)
+    // is the offending keys rather than an expression — "(none)" there would read as "no filter",
+    // which is the one thing that row is not.
+    const candidates = (await list()).filter((r) => r.org === org && r.status === "active");
+    const matches = [];
+    let invalid = 0;
+    for (const r of candidates) {
+        const verdict = await evaluateSubscription(r, ev);
+        if ("invalid" in verdict) {
+            invalid++;
+            log(`event ${ev.summary} skipped ${r.id}: filter did not evaluate (${verdict.invalid})`);
+            await auditRoutineSkip(r, "filter_invalid", {
+                why: verdict.invalid,
+                event: ev.event,
+                ...(isEventTrigger(r.trigger) ? { filter: auditFilterText(r.trigger), source: r.trigger.source } : {}),
+                note: "the subscription's filter could not be evaluated to a boolean, so the routine was skipped rather than fired",
+            }, auditDeps);
+            continue;
+        }
+        if (!verdict.match)
+            continue;
+        // OPE-184 — SUBSCRIPTION LIVENESS, STAMPED HERE AND NOWHERE LATER. "Your filter matches
+        // nothing" and "your filter matches but something downstream stopped it" are different answers
+        // to "why is my subscription silent", and only the first is this pair's business; the second is
+        // already reported by the `routine.skip` rows the loop BELOW writes. So the stamp happens in
+        // THIS loop — before the read grant, before target resolution, before the fan-out cap, all of
+        // which live in the second loop and cannot begin until this one has finished. The `invalid` arm
+        // above `continue`s past this line, so a filter that could not be EVALUATED never stamps: a
+        // broken filter that looked live would be the exact confusion the field exists to remove.
+        // Coalesced and fail-soft inside routines/match-stamp.ts — it never throws into the fan-out.
+        await stampSubscriptionMatch(r, stampDeps);
+        matches.push(r);
+    }
+    const cap = eventMaxFanOut();
+    // STAGE 4 — HYDRATION (OPE-178), memoised for the life of THIS delivery. Created here, and here
+    // only, so every routine matching one delivery renders the SAME fetched state (and costs at most
+    // one API call between them). It is dropped with the delivery: a longer-lived cache would serve a
+    // later delivery stale state, which is the exact failure payload-as-pointer exists to remove.
+    const memo = newHydrationMemo();
+    let fired = 0;
+    let unwired = 0;
+    let overCap = 0;
+    let overBudget = 0;
+    let halted = 0;
+    let ungranted = 0;
+    let drifted = 0;
+    let gated = 0;
+    let hydrated = 0;
+    let withheld = 0;
+    let lostFires = 0;
+    for (const r of matches) {
+        // STAGE 3 — "CAN" (OPE-163). The read grant over the WHOLE scope path the delivery proved,
+        // evaluated against EVERY partition this fire touches (routines/event-authz.ts). Core requires
+        // only that the path is non-empty; the source's own grant adapter decides which step is
+        // authoritative. Runs BEFORE target resolution and before the cap, so an unauthorized routine
+        // consumes neither.
+        //
+        // 🔴 THIS IS THE ONLY PLACE THE GRANT IS EVER CHECKED — `checkEventReadGrant` has exactly one
+        // caller in the tree, and it is this line. `create_routine` does not check it, so arming a
+        // routine on a scope the domain cannot read succeeds and the routine then simply never fires.
+        // Fire-time enforcement is the load-bearing half either way (a grant revoked after arming must
+        // stop the fire — the same parity the clock dispatcher's live trust recheck has), which is why
+        // it is the half that exists; the absence of a create-time check is a WORSE ERROR MESSAGE, not
+        // a weaker boundary. Do not read this comment as "belt and braces" — there is one belt.
+        const grant = checkEventReadGrant(ev, eventGrantPartitions(r), deps.grant ?? {});
+        if (!grant.ok) {
+            ungranted++;
+            log(`event ${ev.summary} matched ${r.id} but the read grant refuses (${grant.reason}${grant.partition ? ` on ${grant.partition}` : ""}) — skipped`);
+            await auditRoutineSkip(r, "grant_refused", {
+                // NOT `reason` — auditRoutineSkip spreads `extra` AFTER its own `reason`, so reusing the
+                // key would silently overwrite the skip reason readers switch on with a sub-reason.
+                grant: grant.reason,
+                ...(grant.partition ? { partition: grant.partition } : {}),
+                event: ev.event,
+                // The grant is checked NOW about something that happened THEN — carried so the
+                // state-at-time question is at least answerable from the audit trail.
+                ...(ev.occurredAt ? { occurredAt: ev.occurredAt } : {}),
+            }, auditDeps);
+            continue;
+        }
+        // Same seam, same order as the clock dispatcher: unresolvable targets never consume cap.
+        const dest = resolveTarget(r);
+        if (!dest) {
+            unwired++;
+            log(`event ${ev.summary} matched ${r.id} but its surface has no wired channel/target — skipped`);
+            // OPE-145: audited (throttled) — a stale target is a silent, permanent "never fires again",
+            // and this leg has no dry-run schedule-hold to make it visible the way the clock leg does.
+            await auditRoutineSkip(r, "unresolved_target", { event: ev.event, ...(ev.action ? { action: ev.action } : {}) }, auditDeps);
+            continue;
+        }
+        if (fired >= cap) {
+            overCap++;
+            log(`event ${ev.summary} matched ${r.id} but the fan-out cap (${cap}) is reached — SKIPPED (audited; an event has no "later")`);
+            await auditRoutineSkip(r, "fanout_cap", { cap, matched: matches.length, event: ev.event, ...(ev.action ? { action: ev.action } : {}) }, auditDeps);
+            continue;
+        }
+        // OPE-166 — "SHOULD THIS ROOM HEAR IT". The grant above proved the DOMAIN may read the content;
+        // it says nothing about whether this ROUTINE'S OWN ROOM is a fit audience for it. Refuses only
+        // on an OBSERVED `guest` floor (routines/fire-disclosure.ts holds the full reasoning, the
+        // fail-open rule and the not-a-dead-guard argument).
+        //
+        // ⚠️ POSITION IS DELIBERATE: after the cheap local reasons not to fire (grant, target, cap) so a
+        // refused delivery costs no roster call, and BEFORE hydration so a room that may not hear the
+        // content never causes it to be FETCHED in the first place.
+        const disclosure = await checkFireDisclosure(r.surfaceKey, deps.disclosure ?? {});
+        if (!disclosure.ok) {
+            withheld++;
+            log(`event ${ev.summary} matched ${r.id} but the room's audience floor is "${disclosure.floor}" — WITHHELD (audited + announced)`);
+            // The notice rides THIS row's throttle: posted only when a row was actually emitted, so an
+            // inbound delivery stream can't turn a standing misconfiguration into channel spam.
+            const emitted = await auditRoutineSkip(r, "audience_floor", {
+                floor: disclosure.floor,
+                event: ev.event,
+                ...(ev.action ? { action: ev.action } : {}),
+                note: "the read grant allows this content but the reporting room's live audience floor does not",
+            }, auditDeps);
+            if (emitted)
+                await announceFireWithheld(r.id, r.surfaceKey, dest.origin, deps.notice ?? {});
+            continue;
+        }
+        // Live trust recheck (fail-closed), mirroring the clock dispatcher exactly: only a CONFIRMED
+        // Slack CHANNEL can be positive, and (OPE-275, matching schedules/dispatch.ts's OPE-269 half)
+        // a DM-destined fire's trust is its CREATOR's current standing — re-derived from the platform
+        // on every fire, never a verdict cached at arm time. Every other surface stamps nothing and
+        // bindFrom's fail-closed default (external) keeps shared memory + the runtime domain-skills
+        // tier OFF. Computed HERE — before the budget gate — because the gate CONSUMES the verdict:
+        // `perDomain["dm"]`/`perDomain["public"]` classify by (mode, trust), so a gate called without
+        // trust resolves neither criteria layer and a DM event routine would evade exactly the budget
+        // its creator's attended DM turns are declined by.
+        const slackChannelId = r.surfaceKey.split("/")[0] === "slack" && typeof dest.target.channelId === "string"
+            ? dest.target.channelId
+            : undefined;
+        const internal = slackChannelId !== undefined && dest.mode === "channel" ? await confirmInternal(slackChannelId).catch(() => false) : false;
+        const creatorInternal = await recheckFireCreator({
+            createdBy: r.createdBy,
+            platform: r.surfaceKey.split("/")[0],
+            mode: dest.mode,
+            workspaceId: r.surfaceKey.split("/")[1],
+            ...(deps.confirmCreatorInternal ? { check: deps.confirmCreatorInternal } : {}),
+        }).catch(() => undefined);
+        const fireTrust = (dest.mode === "dm" ? creatorInternal === true : internal) ? "internal" : "external";
+        // THE BUDGET GATE (OPE-275). This leg used to be the ONE new-spend origin with no
+        // `scopeOverBudget` call at all: a matched delivery woke a model turn consulting no cap layer,
+        // so anyone who could generate events on a granted scope drove unbounded unattended spend —
+        // while the fires WERE attributed, so the creator's ledger filled and their attended turns
+        // started declining as the ungated routine burned on. Per MATCHED ROUTINE, not per delivery,
+        // because a budget is a property of the routine's own scope (its partition) and one delivery
+        // can match routines on different surfaces with different caps. Position: after the cheap
+        // local reasons not to fire and after the disclosure gate (same relative order as
+        // webhooks/dispatch.ts — a room that may not hear the content should not cause a ledger read),
+        // and BEFORE hydration, so an over-budget routine never costs a vendor fetch. `r.createdBy` is
+        // the per-user budget axis (OPE-268): the fire's spend lands on its creator's ledger rows, so
+        // the creator's budget is the only one the gate can compare without charging one person and
+        // measuring another. No admin bypass on this leg either — spend/bypass.ts is consulted only by
+        // the attended ingress gates, same fence as the clock and webhook legs. Fail-open on a CHECK
+        // error, fail-closed on a computed over — the same two postures as every other call site.
+        // THE BREAK-GLASS HALT (OPE-1602) — the event leg's half of the shared predicate
+        // (routines/fire-halt.ts; the clock leg calls the same function). BEFORE the budget gate and
+        // therefore before hydration, for the reason the budget comment above gives: a fire that must
+        // not happen at all should cost no ledger read and no vendor fetch. Fail-CLOSED, unlike the
+        // budget CHECK beside it. An event has no "later", so this delivery is simply dropped — the
+        // routine is untouched and fires on the next matching delivery after `resume`.
+        if (await routineFireHalted(r, { event: ev.event, ...(ev.action ? { action: ev.action } : {}) }, { audit: auditDeps })) {
+            halted++;
+            log(`event ${ev.summary} matched ${r.id} but a break-glass halt is in force — SKIPPED (audited; an event has no "later")`);
+            continue;
+        }
+        try {
+            const verdict = await scopeOverBudget(routinePartition(r), dest.mode, (deps.now?.() ?? new Date()).toISOString(), fireTrust, r.createdBy);
+            if (verdict.over) {
+                overBudget++;
+                log(`event ${ev.summary} matched ${r.id} but the scope is over budget (${verdict.reason ?? "cap reached"}) — SKIPPED (audited; an event has no "later")`);
+                await auditRoutineSkip(r, "over_budget", {
+                    ...(verdict.reason ? { budgetReason: verdict.reason } : {}),
+                    event: ev.event,
+                    ...(ev.action ? { action: ev.action } : {}),
+                }, auditDeps);
+                continue;
+            }
+        }
+        catch {
+            /* never let budget checking block a fire — the CHECK fails open, the CAP fails closed */
+        }
+        // THE PRE-FIRE STEP (OPE-151, routines/pre-fire.ts) — the SAME function the clock dispatcher
+        // calls, for the reason that module's header gives: a condition gate that covered one ingress
+        // and not the other would read as a gate while a whole trigger kind ran regardless.
+        //
+        // ⚠️ POSITION: after the cheap local refusals and BEFORE hydration, on hydration's own argument
+        // one comment down — a delivery that is not going to fire must cost no outbound API call. The
+        // collectors themselves DO cost calls, which is why they sit behind the halt, the grant, the
+        // target resolution, the cap and the budget check above.
+        //
+        // An event has no "later", so a gated delivery is simply dropped: the routine is untouched, it
+        // keeps no schedule to advance, and it fires on the next matching delivery whose condition holds.
+        // The SAME fallback object the clock leg uses, from the one place that builds it — a second copy
+        // here is exactly how this plane lost a control on one ingress before (OPE-1667).
+        const pre = await runPreFire(r, (deps.now?.() ?? new Date()).toISOString()).catch((err) => preFireFallback(r, err));
+        if (!pre.gate.fire) {
+            gated++;
+            log(`event ${ev.summary} matched ${r.id} but its condition gate said no — SKIPPED (audited): ${pre.gate.why}`);
+            await auditRoutineSkip(r, "condition_gate", {
+                ...(pre.gate.gate ? { gate: pre.gate.gate } : {}),
+                gateReason: pre.gate.why,
+                event: ev.event,
+                ...(ev.action ? { action: ev.action } : {}),
+            }, auditDeps);
+            continue;
+        }
+        // STAGE 4 — HYDRATE (OPE-178). PAYLOAD-AS-POINTER, NOT PAYLOAD-AS-TRUTH: the delivery told us
+        // WHICH entity changed; we now re-fetch WHAT it says over our own credential, rather than
+        // rendering the sender's summary and calling it the truth.
+        //
+        // ⚠️ POSITION IN THE LOOP IS DELIBERATE — after the grant check, the target resolution AND the
+        // cap. Hydration is the only stage here that costs an outbound API call, so it must sit behind
+        // every cheap local reason not to fire; a delivery whose only match is unwired or over-cap must
+        // cost nothing. The memo above still guarantees "at most one fetch per delivery" across
+        // whatever does get here.
+        //
+        // 🔴 THE TAXONOMY. Two of these four arms must NOT count against the routine, and the mechanism
+        // that guarantees it is WHICH AUDIT CALL each arm makes, not a flag:
+        //   ok          → fire, with the fetched state fenced into the prompt.
+        //   gone        → FIRE with the summary alone (a deletion is legitimate news, and the entity
+        //                 being unfetchable IS the event). No skip row: it fired.
+        //   forbidden   → NO fire, `routine.skip` reason `grant_drift` — a SKIP, which by construction
+        //                 never folds onto the routine. If this counted, a repo the agent lost access to
+        //                 would silently disable every routine watching it.
+        //   error       → NO fire, `routine.fire_lost` — literally the same call the delivery-rejection
+        //                 path below makes. That is what "per the existing dispatch failure path" means
+        //                 here, and it is why the asymmetry survives.
+        let entityBlock;
+        if (ev.pointer) {
+            const h = await hydratePointer(ev.pointer, memo, deps.hydrate ?? {});
+            if (h.status === "forbidden") {
+                drifted++;
+                log(`event ${ev.summary} matched ${r.id} but hydrating ${ev.pointer.platform} ${ev.pointer.id} was REFUSED by the vendor — grant drift, skipped (no strike)`);
+                await auditRoutineSkip(r, "grant_drift", {
+                    platform: ev.pointer.platform,
+                    entity: ev.pointer.id,
+                    event: ev.event,
+                    ...(ev.occurredAt ? { occurredAt: ev.occurredAt } : {}),
+                    note: "our read grant allows this scope but the vendor refused the fetch — access changed after the grant was written",
+                }, auditDeps);
+                continue;
+            }
+            if (h.status === "error") {
+                log(`event ${ev.summary} matched ${r.id} but hydration failed: ${h.error}`);
+                await loseFire(r, `hydration failed: ${h.error}`);
+                continue;
+            }
+            // `gone` and `unsupported` both fall through to a summary-only fire, and deliberately leave
+            // `entityBlock` undefined — the prompt must not claim to have read something it did not.
+            if (h.status === "ok") {
+                hydrated++;
+                entityBlock = renderHydratedEntity(h.entity);
+            }
+        }
+        // THE FIRE'S OWN ID, minted before the bag that carries it (OPE-626). One uuid names this fire
+        // in three places — the auth bag's per-fire stamp, the run seat key, and the window divert's
+        // wake id — so the outcome fold latches the same fire on both delivery legs. An event fire uses
+        // a per-run seat, so the fold was already correct for it; the stamp rides here so the two
+        // routine ingresses build ONE bag shape, which is what routines/fire-auth.ts exists to keep.
+        const fireWakeId = mintWakeId();
+        // The trust verdicts stamped here (`internal`, `creatorInternal`) are the ones the budget gate
+        // above already consumed — one recheck per fire, two consumers, and they cannot disagree.
+        const auth = {
+            authenticator: ev.source,
+            principalType: "service",
+            principalId: `${ev.source}:webhook`,
+            // OPE-143: the SAME bag the clock dispatcher stamps — platform identity included, so the
+            // fired session binds to the routine's real partition instead of the fallback one.
+            //
+            // OPE-159 TAINT STAMP. `eventPrompt` below folds the delivery's summary (and any hydrated
+            // entity) into the prompt through `ingestUntrusted` — but that call runs HERE, in the ingress
+            // process, where the taint half fail-softs to a no-op, so every event-fired session used to
+            // run with a CLEAN taint signal while its opening prompt carried an outside party's bytes.
+            // The stamp is what the fired turn seeds the real signal from (hooks/spawn-taint.ts).
+            //
+            // CONDITIONAL, and the condition is structural rather than a guess: `ev.redacted` means the
+            // ingress declared a `trigger-only` posture and `normalizeDelivery` already stripped every
+            // payload-derived renderable (routines/event-model.ts redactEvent) — the summary is then
+            // built from the INGRESS-DECLARED source alone and `pointer` is gone, so nothing an outside
+            // party authored can reach this prompt and there is nothing to taint. Every other delivery
+            // renders attacker-authored text and is tainted. NOT A DEAD GUARD in either direction: the
+            // GitHub ingress never redacts, a `trigger-only` declared hook always does.
+            // 🔴 KEEP THE BUILDER CALL ON THIS LINE. scripts/principal-gate-lint.ts (RULE 4,
+            // access/principal-gate-manifest.ts findUnattendedDispatchSites) is line-based: it reads the
+            // FIRST `attributes:` line under a `principalType: "service"` and requires a `…FireAttributes(`
+            // call ON IT. Wrapping this object across lines makes the site read as a hand-rolled inline bag
+            // and fails the gate.
+            // OPE-151: `|| pre.tainted` — a REDACTED delivery carries none of the sender's bytes, but a
+            // COLLECTOR on the same routine may still have handed the prompt an outside system's output,
+            // and the stamp has to mean "an outside party wrote something here" whichever half put it there.
+            attributes: { ...routineFireAttributes(r, dest.attributes, dest.mode, internal, creatorInternal, fireWakeId), ...taintedFireAttrs(!ev.redacted || pre.tainted) },
+        };
+        // OPE-144: an EVENT fire is a triggered flow exactly like a clock fire, so it takes the SAME
+        // decision — join the unified window at THREAD grain when the surface windows and delegation is
+        // armed, else the pre-OPE-144 native cross-channel send. An event has no "later", so each delivery is its
+        // own run (a unique seat key), never a resumed seat.
+        // `url` is a `fields` entry on the neutral model, not a top-level column — the fence takes the
+        // structural minimum (summary + url) so neither shape depends on the other.
+        //
+        // OPE-178: `entity` is the HYDRATED body, and eventPrompt folds it into the SAME `ingestUntrusted`
+        // fence as the summary. It is NOT added to `fields` — `fields` is the MATCHABLE key space, and
+        // making fetched content filterable would change what the read grant protects (a filter over
+        // hydrated prose is a filter over data the grant check never saw). Renderable, never filterable —
+        // exactly the posture `url` already has.
+        const message = eventPrompt(r, {
+            summary: ev.summary,
+            ...(ev.fields["url"] ? { url: ev.fields["url"] } : {}),
+            ...(entityBlock ? { entity: entityBlock } : {}),
+        }, pre.collected);
+        const deliver = async () => {
+            if (dest.origin) {
+                const diverted = await divertTriggeredFire(deps.to, { message, surfaceKey: r.surfaceKey, origin: dest.origin, seatKey: runFireSeatKey(fireWakeId), auth, wakeId: fireWakeId }, deps.fireWindow ?? {});
+                if (diverted)
+                    return;
+            }
+            await deps.to(dest.channel, dest.target).send(message, { auth });
+        };
+        // OPE-145: same `routine.fire_lost` row the clock leg writes — a rejected delivery starts no
+        // session, so the outcome hook never runs and nothing else would ever record this fire.
+        // OPE-180: and it now COUNTS, through the same fold the clock leg uses. See `loseFire` above.
+        let lost = false;
+        await deliver().catch(async (err) => {
+            lost = true;
+            log(`fire delivery failed for ${r.id} on ${r.surfaceKey}: ${String(err)}`);
+            await loseFire(r, String(err));
+        });
+        // A LOST fire is not a fired one — it consumes the cap slot (the attempt was made and cost
+        // whatever the surface cost) but it must not be REPORTED as delivered, or a queue consumer
+        // reading `fired > 0` would conclude the delivery landed somewhere it did not.
+        fired++;
+        if (lost)
+            lostFires++;
+    }
+    if (matches.length > 0 || invalid > 0) {
+        log(`event "${ev.summary}": ${matches.length} matched -> ${fired - lostFires} fired (${hydrated} hydrated), ${ungranted} ungranted, ` +
+            `${withheld} audience-withheld, ${overBudget} over-budget, ${halted} halted, ${gated} condition-gated, ${drifted} grant-drift, ${unwired} unwired, ${overCap} over-cap (cap ${cap}), ` +
+            `${invalid} invalid-filter`);
+    }
+    return {
+        matched: matches.length,
+        fired: fired - lostFires,
+        skipped: ungranted + unwired + overCap + overBudget + halted + gated + withheld + drifted + lostFires,
+    };
+}
+/**
+ * THE SEAM. Admit one already-verified delivery into the routing plane and report what it did.
+ *
+ * The caller has ALREADY authenticated it in whatever terms its transport uses — an HMAC header, an
+ * IAM-signed queue receive, an EventBridge invocation identity. This function trusts that and
+ * trusts nothing else: `source` is whatever the INGRESS declared from its own configuration, never
+ * sniffed off the payload, which is what makes normalizer (and behind it, verifier) resolution
+ * unspoofable.
+ *
+ * NEVER THROWS for a bad delivery. Every "we cannot route this" case is an `accepted: false` report
+ * with a reason, because a throw on a per-delivery path is how a serverless ingress turns a
+ * malformed payload into a 500 and a vendor redelivery storm. A throw out of here means the STORE or
+ * a fire target broke, which is exactly the case a queue consumer SHOULD redrive.
+ *
+ * ORDER IS LOAD-BEARING and matches the design's stage table:
+ *   normalize (unroutable ⇒ never burns a dedupe slot) → dedupe → fan out.
+ * Dedupe runs AFTER verification (the caller's job) and after normalization: deduping first would
+ * let an unauthenticated flood poison the table with forged delivery ids and suppress the genuine
+ * redeliveries that follow, and deduping an unmodelled `ping` would spend a slot on a delivery that
+ * can never fire.
+ */
+export async function admitTrigger(d, deps) {
+    // Echoed on EVERY arm, including the refusals — a delivery the plane could not route is precisely
+    // the one whose id an operator will be asked about, so dropping it on the `accepted: false` paths
+    // would leave the only unanswerable case unanswerable.
+    const id = d.deliveryId ? { deliveryId: d.deliveryId.slice(0, DELIVERY_ID_MAX_CHARS) } : {};
+    const none = { ...id, matched: 0, fired: 0, skipped: 0 };
+    let rejection;
+    const ev = normalizeDelivery(d, (reason) => {
+        rejection = reason;
+        log(`delivery not routable: ${reason}`);
+    });
+    // `null` with no reason is the ROUTINE case — an event this source's normalizer does not model
+    // (a `ping`). It is not an error and must not read as one.
+    if (!ev)
+        return { accepted: false, reason: rejection ?? `source "${d.source}" does not model this event`, ...none };
+    // REPLAY DEDUPE (OPE-139), post-verification. A vendor redelivers on any non-2xx, and on
+    // serverless the redelivery can land on a different instance — so the guard has to be durable,
+    // not an in-process set. A delivery with no id (a hand-rolled test poke, a queue message with no
+    // idempotency attribute) is not deduped rather than being dropped.
+    if (d.deliveryId) {
+        const org = deps.org ?? deploymentOrg();
+        const markSeen = deps.markSeen ?? liveMarkSeen;
+        const atIso = (deps.now?.() ?? new Date()).toISOString();
+        const first = await markSeen(org, deliveryDedupeKey(d.source, d.deliveryId), atIso, DELIVERY_DEDUPE_TTL_MS);
+        if (!first) {
+            log(`delivery ${d.deliveryId} already fanned out — replay dropped`);
+            return { accepted: false, reason: "replay of an already-routed delivery", ...none };
+        }
+    }
+    // THE CAPTURE WINDOW (OPE-211 + OPE-184 Half 2). Placed HERE — after normalization, after the
+    // replay dedupe, before the fan-out — and each of those three is load-bearing:
+    //
+    //   • AFTER NORMALIZATION, because what is stored is the jq FILTER DOCUMENT and normalization is
+    //     what produces it. It is also what applies the `trigger-only` redaction that capture refuses
+    //     on, so capturing earlier would mean capturing a shape no posture had been applied to yet.
+    //   • AFTER THE DEDUPE, so a vendor redelivering on a 500 does not consume window slots with
+    //     copies of one delivery. A window of fifty identical rows would answer the question the
+    //     window exists to answer with the one shape of data that cannot answer it.
+    //   • BEFORE THE FAN-OUT, so what is captured is every ACCEPTED delivery, including the ones that
+    //     match no routine. Those are the NEGATIVES, and §2.6's whole argument is that the filter is
+    //     testable BECAUSE the negatives are present. Capturing only what fired would quietly rebuild
+    //     the hits-only history that OPE-212 was written to escape.
+    //
+    // FAIL-SOFT, DELIBERATELY: a capture failure never affects whether a delivery routes. Retention is
+    // a diagnostic convenience and routing is the product; a store hiccup must not turn into a dropped
+    // event. `captureDelivery` returning FALSE is not a failure at all — it is the ordinary answer for
+    // the overwhelming majority of deliveries, whose hooks were never armed.
+    await captureIfArmed(d, ev, deps);
+    const tally = await fanOut(ev, deps);
+    return { accepted: true, ...id, ...tally };
+}
+/**
+ * Store one delivery in its hook's capture window, when there is one. Total and non-throwing.
+ *
+ * The FOUR gates, in order — and every one of them is a way of saying no, which is the correct shape
+ * for a function whose failure mode is retaining a third party's bytes nobody asked to retain:
+ * no declared window (the default for every hook), a window the store's own ceilings have closed,
+ * a redacted event (`trigger-only`), and a document that overran its by-construction bound.
+ */
+async function captureIfArmed(d, ev, deps) {
+    if (!d.captureUntil)
+        return;
+    const documentJson = captureDocument(ev);
+    // `undefined` here is the trigger-only refusal (and the oversize drop) — see capture-window.ts.
+    if (!documentJson)
+        return;
+    try {
+        const org = deps.org ?? deploymentOrg();
+        const at = (deps.now?.() ?? new Date()).toISOString();
+        const capture = deps.captureDelivery ?? ((...a) => getOperationalStore().captureDelivery(...a));
+        await capture(org, ev.source, documentJson, at, d.captureUntil, CAPTURE_MAX_DELIVERIES);
+    }
+    catch (err) {
+        // Swallowed on purpose (see the call site): the delivery still routes.
+        log(`capture window write failed for "${ev.source}": ${String(err)}`);
+    }
+}
+//# sourceMappingURL=ingress.js.map