@open-everywhere/core 0.1.0

package/dist/agent/routines/event-model.d.ts

@@ -0,0 +1,463 @@
+import type { Scope } from "../access/bundle.js";
+/**
+ * Vendor-neutral CLASS of container. CLOSED — five levels, ordered OUTERMOST-FIRST. A normalizer
+ * populates whichever levels its delivery actually proves; gaps are allowed (GitHub has no
+ * `group`), REPEATS and INVERSIONS are not (see {@link normalizedEventDefect}).
+ */
+export type ScopeKind = "tenant" | "group" | "container" | "entity" | "sub";
+/** The five kinds in outermost-first order — the ordering the scope path must respect. */
+export declare const SCOPE_KINDS: readonly ScopeKind[];
+export interface ScopeStep {
+    readonly kind: ScopeKind;
+    /** The vendor's OWN id. OPAQUE — core never parses it, only compares it. */
+    readonly id: string;
+    /** Human label. UNTRUSTED (attacker-authored: a repo name, a page title). Never matched on. */
+    readonly label?: string;
+}
+/** Where to re-fetch authoritative state, for the payload-as-pointer posture. */
+export interface EntityPointer {
+    /** The same runtime dispatch key `EntityRef` uses (channels/entity-actions.ts). */
+    readonly platform: string;
+    readonly id: string;
+    /** TERMINAL event ⇒ the entity is gone, so hydration MUST NOT be required. Set by the
+     *  normalizer off the vendor's own delete signal, never inferred from a failed fetch. */
+    readonly gone?: boolean;
+}
+/** ≤16 matchable scalars, each ≤200 chars — see {@link FIELD_VALUE_MAX} for why truncation, not
+ *  rejection, is the right failure mode for an over-long value. */
+export declare const FIELDS_MAX_KEYS = 16;
+export declare const FIELD_VALUE_MAX = 200;
+/**
+ * ONE normalized external event. Everything downstream of normalization — the filter evaluator, the
+ * read-grant check, the fire preamble — sees only this. No `Request`, no headers, no raw body.
+ */
+export interface NormalizedEvent {
+    /** WHICH HOOK this came from — the NAME, and what a routine's `trigger.source` is matched
+     *  whole-string against (`event-match.ts`). Stamped by {@link normalizeDelivery} from the
+     *  delivery's own declared name, so a normalizer cannot decide which subscriptions it answers.
+     *
+     *  ⚠️ It used to be documented as "the registry key", and that is now {@link scheme}'s job — see
+     *  the module header's asymmetry note before resolving anything through this field. */
+    readonly source: string;
+    /** WHICH CONTRACT this is — the registry key the normalizer and the scope grant were resolved
+     *  through. ABSENT ⇒ {@link source} (routines/scheme-name.ts's absence rule), which is what keeps
+     *  a hand-built event and every pre-split stored shape correct. Always stamped in practice by
+     *  {@link normalizeDelivery}; go through `webhookScheme(ev)` rather than reading it raw. */
+    readonly scheme?: string;
+    /** The vendor's event name, VERBATIM (never re-spelled into a house vocabulary — a rename layer
+     *  is a second thing to keep in sync and buys nothing the filter cannot already express). */
+    readonly event: string;
+    readonly action?: string;
+    /** OUTERMOST-FIRST container path. May be EMPTY (a source that proves no container at all —
+     *  which the read-grant check then refuses, fail-closed, rather than treating as "anywhere"). */
+    readonly scope: readonly ScopeStep[];
+    /** Who caused it, when {@link EventNormalizer.resolvesActor} says the payload can say. CARRIED,
+     *  NOT YET CONSUMED (OPE-192) — the only code that touches it is {@link redactEvent}, which strips
+     *  it, because a vendor handle is attacker-chosen prose. It was documented as load-bearing for a
+     *  self-trigger guard that does not exist; it is not, and no filter may key on it (a normalizer
+     *  puts the actor in `fields` if it wants it matchable — GitHub's `sender`). */
+    readonly actor?: {
+        readonly id?: string;
+        readonly handle?: string;
+    };
+    /** The MATCHABLE scalars. A filter may only name a key the normalizer DECLARED in
+     *  {@link EventNormalizer.matchKeys}; extra keys here are carried for rendering, not matching. */
+    readonly fields: Readonly<Record<string, string>>;
+    readonly deliveryId?: string;
+    /** ISO, per the SOURCE — not our receive time. Distinct on purpose: a fire's preamble carries
+     *  both, so "this says 'PR opened' about an already-merged PR" is diagnosable. */
+    readonly occurredAt?: string;
+    /** CODE-RENDERED one-liner. Contains attacker-authored substrings (a PR title), so it is only
+     *  ever emitted through `access/untrusted.ts`'s fence — never into a trusted position. */
+    readonly summary: string;
+    readonly pointer?: EntityPointer;
+    /**
+     * OPE-159 — this delivery was REDACTED to its bare occurrence: the ingress declared a
+     * `trigger-only` posture, so nothing payload-derived reaches the model. `summary` is a fixed
+     * code-rendered line, `pointer` is gone (nothing is fetched), and no renderable payload field
+     * survives. `fields` and `scope` are KEPT and are still matched on — a filter's output is a
+     * boolean, not text, so filtering never puts an outside party's bytes in front of the model.
+     *
+     * Set by {@link normalizeDelivery} from {@link TriggerDelivery.redactPayload}, never by a
+     * normalizer: a normalizer authors the payload projection, so letting it declare its own
+     * redaction would put the guarantee in the hands of the thing being guarded against.
+     */
+    readonly redacted?: boolean;
+    /**
+     * OPE-214 — this delivery was NARROWED to the listed field keys: the ingress declared a
+     * `projection` posture, so {@link summary} was rebuilt from exactly these keys and every other
+     * payload-derived renderable was dropped. The keys are the INGRESS's declaration (config), never
+     * the payload's.
+     *
+     * MUTUALLY EXCLUSIVE WITH {@link redacted}, structurally: `normalizeDelivery` tests redaction
+     * FIRST and returns, and `redactEvent` strips this field, so no event can ever carry both. A
+     * projected event is still payload-bearing — the values are an outside party's bytes, just fewer
+     * of them — so it takes the same taint stamp and the same untrusted fence a `content-bearing`
+     * delivery does. It is NOT a second flavour of redaction and no consumer may read it as one.
+     */
+    readonly projected?: readonly string[];
+    /**
+     * OPE-209 — the hook's declared read grant, STAMPED here from {@link TriggerDelivery.readableBy}
+     * and never authored by a normalizer, for the identical reason {@link redacted} is not: a
+     * normalizer reads attacker-controlled bytes, so it must not be able to state the rule that
+     * decides who may read the result.
+     *
+     * Present ⇒ `routines/event-authz.ts` decides by this ALONE. Absent ⇒ the source's
+     * `EventScopeGrant` adapter decides (the vendor-ingress path). Empty ⇒ refuse.
+     */
+    readonly readableBy?: readonly Scope[];
+}
+/**
+ * A transport-free delivery. THE seam: no `Request`, no URL, no method, no queue ARN, no
+ * visibility timeout — "core params never encode hosting topology", applied to ingress. A queue
+ * consumer synthesises `headers` from message attributes and lands on exactly this shape.
+ */
+export interface TriggerDelivery {
+    /** The NAME of the hook (or native ingress) this arrived on. DECLARED by the ingress that received
+     *  it (from config), never sniffed off the payload. Becomes {@link NormalizedEvent.source}. */
+    readonly source: string;
+    /** The SCHEME — the registry key the normalizer is resolved through (OPE-198 S2). DECLARED by the
+     *  ingress from the same configuration and with the same unspoofability property as {@link
+     *  source}. ABSENT ⇒ {@link source}, so every existing ingress — the native GitHub fan-out
+     *  included — is correct without being touched. */
+    readonly scheme?: string;
+    /** LOWERCASED header names. Already-verified metadata — verification happens upstream. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The raw body bytes as received. */
+    readonly body: string;
+    readonly deliveryId?: string;
+    readonly receivedAt: string;
+    /**
+     * OPE-159 — the ingress declares this delivery's payload must NOT reach the model
+     * (`trigger-only`, `webhooks/config.ts`'s `posture`). Declared by the INGRESS from its own
+     * configuration,
+     * exactly like {@link source}, and never read off the payload: the whole property is that an
+     * outside party cannot influence whether their own bytes get rendered.
+     *
+     * Applied in {@link normalizeDelivery} — i.e. once, at the ONE place every transport's delivery
+     * becomes a routable event — rather than at each render site. A render-site check would have to
+     * be repeated at every future site, and the failure mode of forgetting one is silent.
+     */
+    readonly redactPayload?: boolean;
+    /**
+     * OPE-214 — the ingress declares that only THESE field keys may be rendered (`projection`,
+     * webhooks/config.ts). Declared by the INGRESS from its own configuration with exactly the same
+     * unspoofability property {@link redactPayload} has: a sender cannot name its own keys, because
+     * the list is not in the payload at all.
+     *
+     * 🔴 IT IS SUBORDINATE TO {@link redactPayload}, NEVER A PEER. `normalizeDelivery` tests redaction
+     * first and returns, so a delivery carrying both projects nothing. That ordering is the whole
+     * reason a third posture is safe to add: `trigger-only` exists to keep payloads away from humans,
+     * and an ordering that let a projection run alongside it would be precisely the back door. The
+     * ingress derives both from ONE posture value (`configHookDisclosure`) so the pair cannot
+     * disagree in the first place; the ordering is what makes that a property of the code rather than
+     * of every caller remembering.
+     *
+     * An EMPTY list is treated as "no projection declared" — not as "project nothing". A hook that
+     * wants nothing rendered says `trigger-only`, which is a posture with a name, a card line and a
+     * test; an empty key list reaching this field means a declaration went wrong upstream, and the
+     * validator refuses it there (`assertWebhooksValid`).
+     */
+    readonly project?: readonly string[];
+    /**
+     * ⭐ THE CAPTURE WINDOW'S DEADLINE for the hook that received this delivery (OPE-211 + OPE-184
+     * Half 2) — ISO-8601, and ABSENT MEANS DO NOT CAPTURE. `webhooks/capture-window.ts` holds the
+     * argument; `routines/ingress.ts` is the one consumer.
+     *
+     * Declared by the INGRESS from the stored row, exactly like {@link redactPayload} and
+     * {@link readableBy}, and for the identical reason: whoever holds the sending secret must not be
+     * able to arm retention of their own bytes. A delivery cannot carry this field inbound — it is not
+     * read from the body or the headers anywhere, and there is no path that would.
+     *
+     * 🔴 IT IS SUBORDINATE TO {@link redactPayload} IN THE SAME WAY {@link project} IS. A trigger-only
+     * hook can hold no open window, the declaration helper refuses the combination, and the capture
+     * itself refuses again on the normalized event's `redacted` stamp. The rule that a posture built
+     * to keep payloads away from humans has no storage back door is worth three refusals.
+     */
+    readonly captureUntil?: string;
+    /**
+     * ⭐ THE HOOK'S READ GRANT (OPE-209, replacing OPE-196's single `ownerDomain`) — declared by the
+     * ingress from the hook's own declaration (config file or stored row), and never re-derived from
+     * anything a delivery carries.
+     *
+     * ⭐ WHY IT IS ON THE DELIVERY AND NOT LOOKED UP BY THE NORMALIZER. A normalizer is handed exactly
+     * one {@link TriggerDelivery} and is pure — it has no store, no config and no org. So the only way
+     * an authorization fact can be DECLARATION-DERIVED rather than PAYLOAD-DERIVED is for the ingress
+     * that holds the declaration to state it here. {@link redactPayload} is the precedent, and it is
+     * the same shape of fact: an ingress-declared, non-transport constraint on what a delivery may
+     * cause, applied once at {@link normalizeDelivery}'s seam rather than re-derived downstream.
+     *
+     * 🔴 IT IS THE ENTIRE CONFIDENTIALITY DECISION FOR A HOOK-BORNE EVENT. `routines/event-authz.ts`
+     * evaluates it (union, `access/read-grant.ts`) against each candidate partition's resolved access,
+     * INSTEAD OF the source's `EventScopeGrant` adapter — a hook that declares its own grant does not
+     * also get a per-scheme rule inventing one. A sender cannot move its own events into another
+     * domain: it never touches this field, because it is not in the payload at all.
+     *
+     * ABSENT/EMPTY is legal and FAILS CLOSED, not open — `scopeGrantsRead` refuses both. No caller may
+     * read absence as "any domain".
+     *
+     * Vendor ingresses (the native GitHub fan-out, a queue consumer) leave it unset — their scope comes
+     * from a namespace the VERIFIER makes the sender authoritative over, which is a different rule and
+     * still runs through the source's grant adapter. See `routines/event-authz.ts` for the invariant
+     * that governs which of the two applies.
+     */
+    readonly readableBy?: readonly Scope[];
+}
+/** The stored filter a subscription carries, structurally — so this leaf can read and render one
+ *  without importing `routine.ts`'s `RoutineTrigger` (which imports this file). ONE field: the two
+ *  retired languages that used to sit beside it were deleted by OPE-1145. */
+export interface StoredSubscription {
+    /** ⭐ A jq predicate over `jq-filter.ts`'s `EventFilterDocument`. ABSENT means "no filter", which
+     *  fire time honours as all-events and create time refuses ({@link storedFilter}'s `none` arm). */
+    readonly jq?: string;
+}
+/**
+ * WHAT A STORED SUBSCRIPTION SAYS — three arms, and the third one is why this is a function.
+ *
+ * `unknown` IS ITS OWN ARM, NOT A FLAVOUR OF `none`. It carries no expression, so a caller cannot
+ * evaluate it by accident, and it never collapses into the all-events reading by omission. What
+ * TypeScript does NOT do is force a new caller to handle it: `StoredFilter` is a plain union with no
+ * exhaustiveness check, so `f.kind === "jq" ? … : fire()` compiles and would re-open the fire-hose.
+ * That is weaker than `JqOutcome`, where the non-error arm carries the match value itself. So the
+ * guarantee here is the TEST, not the type: `event-routing-test.ts` pins all three surfaces (fire,
+ * render, store), and each pin goes red when its arm is dropped. A new reader of a stored
+ * subscription belongs in that test.
+ *
+ * `unknown` is deliberately keyed on the row's EXTRA KEYS rather than on a known list of retired
+ * spellings: a hand-edited row inventing `where:` is exactly as unreadable as a surviving `match:`,
+ * and naming the keys is what makes the refusal actionable in an audit row.
+ */
+export type StoredFilter = {
+    readonly kind: "jq";
+    readonly expression: string;
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "unknown";
+    readonly keys: readonly string[];
+};
+export declare function storedFilter(t: StoredSubscription): StoredFilter;
+/**
+ * One-line human rendering of a subscription — `list_routines`, the CLI, and the arming approval
+ * card all go through it, so what a human APPROVES and what the evaluator RUNS are the same
+ * sentence. Lives here (a leaf over the filter type) rather than with the evaluator so
+ * `routines/routine.ts` can render a trigger without importing the evaluator that imports it.
+ *
+ * AN UNREADABLE ROW DESCRIBES ITSELF AS ONE, and says it will never fire — which is exactly what
+ * `evaluateSubscription` then does with it. That is the renderer's standing invariant ("a stored
+ * row must never DESCRIBE itself differently from how it behaves") applied to the one case the
+ * OPE-1145 deletion creates.
+ */
+export declare function describeFilter(source: string, t: StoredSubscription): string;
+/** One system's payload→NormalizedEvent translation, plus the DECLARATIONS that make a filter
+ *  naming this source validatable before it is ever stored. */
+export interface EventNormalizer {
+    /** Registry key = exactly what a routine declares as its `source`. */
+    readonly source: string;
+    /** Set ⇒ this entry belongs to a provider BUNDLE and registration routes through
+     *  `admitProviderRegistration`, so a de-selected provider contributes nothing and every routine
+     *  naming that source then fails closed at resolution. Core's own leave it UNSET. */
+    readonly provider?: string;
+    /** The ONLY `fields` keys a filter may name. Rendered into `create_routine`'s refusal copy, so a
+     *  typo'd key is refused with the legal set named — the house pattern.
+     *
+     *  When {@link matchKeysOpen} is set this list stops being exhaustive and becomes the RESERVED
+     *  subset — the keys the contract itself always emits — which is still what the refusal copy and
+     *  the tool description quote. */
+    readonly matchKeys: readonly string[];
+    /**
+     * 🔴 THE KEY SPACE IS THE SENDER'S, NOT THE CONTRACT'S (OPE-196 / S3) — so a create-time
+     * closed-vocabulary check is NOT EXPRESSIBLE for this source, and saying so is better than
+     * pretending a list is complete.
+     *
+     * Set ONLY by a CATEGORY-(b) contract: one where OE defines the envelope and the caller fills it
+     * in (`webhooks/oe-standard-webhook.ts`). Its envelope carries a `fields` bag whose KEYS are chosen
+     * by whoever wrote the sender — `status`, `branch`, `severity` — and no static declaration in this
+     * tree can know them. A vendor contract (category (a)) has a payload shape we read from the
+     * vendor's docs, so its `matchKeys` genuinely IS closed and this field stays absent.
+     *
+     * WHAT IT COSTS, HONESTLY. `validateSubscription`'s membership check is what kills the
+     * SILENT-NO-OP class (a typo'd key sitting `active` forever, matching nothing). For an open
+     * source that check cannot run, so a typo IS possible. Three things bound it and none of them is
+     * this field: the clause SHAPE, the caps and the key GRAMMAR are still enforced; the sender and the
+     * routine author are the same org (a (b) hook's secret was minted for them); and `list_routines`
+     * renders the filter through `describeFilter`, so the typo is legible. It is a real, named
+     * regression in one direction, taken because the alternative — a hook declaring its own field
+     * vocabulary at creation — is the payload-extraction design this arc deliberately killed.
+     *
+     * ABSENT ⇒ CLOSED, which is what makes every shipped source unchanged.
+     */
+    readonly matchKeysOpen?: boolean;
+    /** The subset of {@link matchKeys} that IDENTIFY A SCOPE (GitHub: `repo`). Used by the
+     *  mandatory-narrowing rule: a filter must narrow by SOMETHING, either an `under` selector or a
+     *  clause on one of these. Without it "subscribe to this whole tenant" is the accidental default. */
+    readonly scopeKeys: readonly string[];
+    /** Which scope kinds this source can ever prove — an `under` naming any other kind is refused at
+     *  create time, because it could never match and would sit `active` forever matching nothing. */
+    readonly scopeKinds: readonly ScopeKind[];
+    /**
+     * ⭐ THE SCOPE PATH IS DERIVED ENTIRELY FROM THE RECEIVING HOOK'S ROW, NEVER FROM THE PAYLOAD
+     * (OPE-196 / S3) — the §2 invariant of the webhook-ingress plan, declared as a reviewed field
+     * rather than argued in prose.
+     *
+     * 🔴 THIS IS NOT A GENERAL RULE AND MUST NOT BE SET "TO BE SAFE". The rule the plane actually
+     * enforces is: *scope may be derived from the payload only to the extent the VERIFIER makes the
+     * sender authoritative over that namespace.* GitHub's signature proves GitHub sent it, and GitHub
+     * IS authoritative about which repo an event came from — so `routines/github-normalizer.ts`
+     * correctly derives its whole path from `repository.full_name` and correctly leaves this UNSET. A
+     * sender holding a secret WE minted is authoritative over exactly one fact — WHICH HOOK IT IS —
+     * and over no external namespace, so its path is row-derived and this is set.
+     *
+     * TWO CONSEQUENCES, both of which is why it is a field and not a comment:
+     *   1. `event-match.ts` skips the MANDATORY-NARROWING rule for such a source. That rule exists
+     *      because one vendor `source` spans a whole tenant's containers, so "subscribe to everything"
+     *      must be spelled out. Here the subscription's `source` names ONE HOOK and the path below
+     *      `container` is that hook's own, so naming it IS the narrowing — demanding a second
+     *      `under: {container: <the hook's own name>}` would be ceremony, and ceremony that buys
+     *      nothing is how a control gets routed around.
+     *   2. It is directly TESTABLE: two deliveries with wildly different bodies on one hook must
+     *      produce byte-identical scope paths. A claim about a payload boundary that no assertion can
+     *      contradict is the failure class this tree has a name for.
+     */
+    readonly scopeHookConstant?: boolean;
+    /**
+     * Can this source's payload identify the ACTOR who caused the event? A REVIEWED DECLARATION OF A
+     * VENDOR PROPERTY — declared rather than inferred so the answer is a decision someone made while
+     * reading the vendor's payloads, not a guess.
+     *
+     * 🔴 NOTHING READS IT (OPE-192). It used to be documented as "load-bearing for the future
+     * self-trigger guard"; that guard does not exist and has no design, so the claim described a
+     * control that was not there — the failure class this tree has a name for. Setting it either way
+     * changes no behaviour today. Answer it honestly for your source anyway: the day a guard against
+     * OE's own writes re-triggering OE is built, this is the field that says which sources it can
+     * stand on, and a retrofitted answer would be a guess about payloads nobody was looking at.
+     */
+    readonly resolvesActor: boolean;
+    /**
+     * The LOWERCASED header name this source carries its own idempotency key in, when it has one
+     * (GitHub: `x-github-delivery`). Absent ⇒ this source offers no delivery id and the durable
+     * replay dedupe simply does not run for it — never a synthesised one (see
+     * {@link TriggerDelivery.deliveryId}).
+     *
+     * ⭐ WHY THIS IS ON THE NORMALIZER AND NOT ON `WebhookVerifier` (OPE-201). `keyOrigin` and
+     * `signedTimestamp` are the precedent for a DECLARED per-source fact, and they live on the
+     * verifier because they are facts about the SIGNATURE SCHEME. A delivery-id header is not: it is a
+     * fact about the vendor's DELIVERY ENVELOPE, the same family as the event-name header the
+     * normalizer already owns privately (`routines/github-normalizer.ts`'s `EVENT_HEADER`). Two
+     * structural reasons settle it:
+     *
+     *   1. THE CONSUMER RESOLVES NORMALIZERS, NEVER VERIFIERS. The id is spent by `admitTrigger`, the
+     *      transport-free seam, whose whole point is that a queue receive or an EventBridge
+     *      invocation lands on it too. Those never touch a `WebhookVerifier`, so a fact homed there
+     *      would be unreachable from the plane that uses it.
+     *   2. THE NORMALIZER ALREADY TREATS `d.deliveryId` AS ITS OWN. It reads it and stamps it onto
+     *      {@link NormalizedEvent.deliveryId}, so declaring the header anywhere else would put the
+     *      name and its only reader in two modules.
+     *
+     * DECLARED DATA, NOT INFERRED — there is deliberately no "try a list of likely header names".
+     * Only the VALUE comes from the sender (it always did: the native GitHub route reads the same
+     * header straight off the request); the NAME is a reviewed field, exactly as `source` is.
+     */
+    readonly deliveryIdHeader?: string;
+    /** `null` = an event we do not model (a `ping`) — the ingress 200s and ignores it. MUST NOT
+     *  throw: a broken normalizer must not be able to 500 an ingress (see {@link normalizeDelivery}). */
+    normalize(d: TriggerDelivery): NormalizedEvent | null;
+}
+/**
+ * Register (or replace) the normalizer for one source. A normalizer carrying `provider` is routed
+ * through the provider-selection gate first. Returns whether the row landed.
+ */
+export declare function registerEventNormalizer(normalizer: EventNormalizer): boolean;
+/** The normalizer for `source`, or undefined when none is registered. NEVER a fallback to another
+ *  source's normalizer — resolution is by declared source, and a miss is a refusal. */
+export declare function eventNormalizer(source: string | undefined): EventNormalizer | undefined;
+/**
+ * The delivery id THIS SCHEME declares it carries, read out of an ingress's own headers (OPE-201).
+ *
+ * ⚠️ THE PARAMETER IS THE **SCHEME**, NOT THE HOOK'S NAME (OPE-198 S2). A delivery-id header is a
+ * fact about the vendor's delivery envelope — i.e. about the contract — so it is keyed the same way
+ * the normalizer that declares it is. Callers pass `webhookScheme(hook)`; passing `.source` happens
+ * to work today only because every hook has `scheme === name`.
+ *
+ * The one supported way for an ingress to obtain a {@link TriggerDelivery.deliveryId} from a
+ * request it received. Returns undefined for an unregistered scheme, a scheme that declares no
+ * {@link EventNormalizer.deliveryIdHeader}, and an absent or blank header value alike — all three
+ * are "this delivery has no id", which {@link TriggerDelivery.deliveryId} already models as
+ * not-deduped rather than dropped.
+ *
+ * `headers` must already be LOWERCASE-KEYED, matching {@link TriggerDelivery.headers}.
+ *
+ * ⚠️ EVERY INGRESS THAT HOLDS REAL HEADERS SHOULD CALL THIS. The derivation is deliberately NOT
+ * folded into `admitTrigger`: `TriggerDelivery`'s invariant is that every field on it was DECLARED
+ * by the ingress that received the delivery, and the id is not derivable at that seam anyway —
+ * `routines/github-fanout.ts` synthesises a two-field header bag and passes its id explicitly, so a
+ * central derivation would silently find nothing there while looking like it covered everything.
+ */
+export declare function declaredDeliveryId(scheme: string, headers: Readonly<Record<string, string>>): string | undefined;
+/** Every registered source, sorted — for refusal copy and tool descriptions. */
+export declare function registeredEventSources(): readonly string[];
+/** Test seam: forget every registered normalizer (mirrors resetWebhookVerifiersForTest). */
+export declare function resetEventNormalizersForTest(): void;
+/** The id of the scope step of this kind, or undefined. The path holds AT MOST ONE step per kind
+ *  ({@link normalizedEventDefect} enforces it), which is what makes a selector on an INNER kind
+ *  imply containment in every outer one — i.e. what makes `under` a genuine prefix test. */
+export declare function scopeIdOf(scope: readonly ScopeStep[], kind: ScopeKind): string | undefined;
+/**
+ * The INNERMOST step the delivery proved.
+ *
+ * 🔴 NOT "what the read grant is evaluated against" — which is what this comment used to say, and it
+ * was wrong. `checkEventReadGrant` calls this function purely as a NON-EMPTINESS PREDICATE (an empty
+ * path cannot be authorized by a scope rule) and then hands the grant adapter the WHOLE path. Which
+ * step is authoritative is 100% the adapter's choice: GitHub's grant reads the `container` step and
+ * explicitly refuses a delivery that proves only a `tenant`. Core requires that the path is
+ * non-empty; it has no opinion about which end of it matters.
+ */
+export declare function innermostScope(scope: readonly ScopeStep[]): ScopeStep | undefined;
+/**
+ * Structural defects a NormalizedEvent must not have, or null. Returned rather than thrown so the
+ * caller can refuse the delivery without a broken normalizer being able to 500 an ingress.
+ *
+ * The ordering/uniqueness rule is not tidiness. A scope test reads as a PREFIX test but is
+ * IMPLEMENTED as kind-keyed lookup ({@link scopeIdOf}, and the `.scope.<kind>` projection a filter
+ * sees), and those two coincide only while the path is a strictly increasing sequence of distinct
+ * kinds. A normalizer emitting `[container:a, container:b]` would silently make
+ * `.scope.container == "a"` match an event inside `b`.
+ */
+export declare function normalizedEventDefect(ev: NormalizedEvent): string | null;
+/**
+ * Normalize one delivery through the registered normalizer for its DECLARED source.
+ *
+ * Returns null — never throws — for every "we can't route this" case, so an ingress 200s-and-ignores
+ * uniformly: unregistered source, an event the normalizer doesn't model, a normalizer that threw,
+ * or a structurally defective result. A `reason` sink is offered instead of a throw because the
+ * caller wants to AUDIT the difference between "not modelled" (routine) and "broken" (a bug), and a
+ * thrown error on a per-delivery path is how a serverless ingress turns a bad payload into a 500.
+ *
+ * Over-long field values are TRUNCATED to {@link FIELD_VALUE_MAX} rather than rejected: values that
+ * are matched on are ids (short), values that are long are prose (titles), and dropping a whole
+ * delivery because someone wrote a long PR title would be a self-inflicted outage.
+ */
+export declare function normalizeDelivery(d: TriggerDelivery, onReject?: (reason: string) => void): NormalizedEvent | null;
+/**
+ * OPE-159 — strip every payload-derived RENDERABLE from a normalized event, keeping only what is
+ * MATCHED on. The `trigger-only` posture, made concrete.
+ *
+ * WHAT SURVIVES, AND WHY: `fields` and `scope` stay, because a filter evaluates to a boolean and a
+ * boolean is not text — matching on the payload never puts an outside party's bytes in front of the
+ * model. `event`/`action` stay for the same reason (they are what filters key on).
+ *
+ * WHAT GOES, AND WHY EACH ONE: `summary` is replaced with a line built ONLY from `source`, which
+ * the INGRESS declared from its own configuration — not one byte of it is payload-derived, so a
+ * holder of a leaked secret cannot get a single character of their own choosing in front of the
+ * model. `pointer` is dropped, which is what makes "no fetch happens" structural rather than a
+ * convention: with no pointer, `routines/ingress.ts` never enters its hydration arm at all.
+ * `fields.url` is dropped because it is the one field that is RENDERED as well as matchable
+ * (ingress.ts reads `ev.fields["url"]` into the prompt), so leaving it would be a hole in exactly
+ * the property this function exists to provide. `actor` goes because a handle is attacker-chosen
+ * prose on several vendors.
+ *
+ * The result is that a leaked `trigger-only` secret buys exactly one thing: causing a known,
+ * member-authored, human-approved prompt to run. That is the same authority a cron already has.
+ */
+export declare function redactEvent(ev: NormalizedEvent, declaredSource: string): NormalizedEvent;
+//# sourceMappingURL=event-model.d.ts.map

package/dist/agent/routines/event-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-model.d.ts","sourceRoot":"","sources":["../../../agent/routines/event-model.ts"],"names":[],"mappings":"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"}