@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-engagement.js

@@ -0,0 +1,283 @@
+// THE NOTION AMBIENT ENGAGEMENT SEAM (chat-surface contract §2.5) — the Notion wiring over core's
+// pure engagement policy (`packages/core/agent/channels/engagement.ts`). It gives Notion the middle
+// posture Slack, Discord and Teams already have: addressing the app marks the PAGE ENGAGED, a later
+// PLAIN comment on that page wakes the agent, and `stand_down` stores the stop.
+//
+// THE ANCHOR is `notionConversationKey(workspaceId, pageId)` — `<workspace>/<page>`, the same string
+// the mapper publishes as `anchorChannelId` for the stop registry. The doc session is PAGE-scoped
+// (`notionSupervisorToken` keys the standing session by page, aware of all the page's discussions),
+// so the page is the conversation a person can address a stop to, and a per-discussion mark would
+// leave the same session answering the discussion next door.
+//
+// 🔴 THE ADDRESS IS A NAME-DROP, NOT AN @MENTION, AND THAT IS A VENDOR FACT. Notion lets no user
+// @mention an internal integration at all, so `classifyNotionComment` promotes a name-drop (or the
+// structurally-unreachable structured mention) to `direct` — that IS Notion's addressed leg, and it
+// is therefore what enrols a page here. `notionNameDrop` owns the matching, including its
+// word-boundary guards; this module never looks at comment text.
+import { getOperationalStore, getThreadEngagement, markThreadEngaged, resolvePartition, shouldDeliverReply, } from "@open-everywhere/core/agent/adapter-api.js";
+import { buildNotionAuth, notionConversationKey } from "./notion-identity.js";
+/** The engagement-registry anchor for one Notion delivery, or `undefined` when either id is missing.
+ *
+ *  🔴 IT IS THE ONE PREDICATE THE MAPPER AND THE SEAM SHARE. `bindNotion` publishes exactly this as
+ *  `engagementKey`, so `stand_down`'s mark and this seam's read address the same row. */
+export function notionEngagementAnchor(f) {
+    return notionConversationKey(f.workspaceId, f.pageId);
+}
+/** The partition one page's engagement row lives in — `notion/<workspace>/<page>`, which is what
+ *  `resolvePartition` gives a bound Notion session and therefore what `stand_down` writes under. It
+ *  is built through the same `buildNotionAuth` the wake dispatches, so the seam can never key a row
+ *  the turn would not. Null on an unresolvable identity — the caller then keeps today's path. */
+export function notionSeamPartition(f) {
+    if (!f.workspaceId || !f.pageId)
+        return null;
+    try {
+        const auth = buildNotionAuth({
+            workspaceId: f.workspaceId,
+            pageId: f.pageId,
+            ...(f.principalId ? { principalId: f.principalId } : {}),
+            ...(f.credentialId ? { credentialId: f.credentialId } : {}),
+        });
+        return resolvePartition({ channel: { kind: "notion" }, session: { auth: { current: auth } } });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the seam for one NON-ADDRESSED comment — READ-ONLY. An addressed comment never reaches
+ * this function: it marks instead ({@link markNotionEngaged}), so exactly one caller writes the row.
+ *
+ * THE DECISION ITSELF IS CORE'S. `shouldDeliverReply` owns the disqualifier order and the reasons;
+ * this function only translates Notion facts into its input. Nothing here re-states the policy.
+ *
+ * FAIL-CLOSED on a store error: `getThreadEngagement` reads a failure as `null`, so an unreadable
+ * registry holds rather than delivers.
+ *
+ * `authorIsBot` is the caller's own loop-guard verdict. The classifier drops a self-authored or
+ * integration-authored comment before this runs, so it is `false` on every live call; it stays a
+ * parameter rather than a hard-coded literal so the guard is visible at the call site and a test can
+ * drive the other direction.
+ */
+export async function resolveNotionEngagement(f, authorIsBot, deps = {}) {
+    const anchor = notionEngagementAnchor(f);
+    if (!anchor)
+        return { kind: "unanchored", reason: "the delivery names no workspace and page — no row to address" };
+    const partition = notionSeamPartition(f);
+    if (!partition)
+        return { kind: "unanchored", reason: "the delivery has no resolvable partition — no row to address" };
+    const read = deps.getEngagement ?? ((p, key) => getThreadEngagement(p, key));
+    const row = await read(partition, anchor);
+    const decision = shouldDeliverReply({
+        isEngaged: row !== null,
+        stopped: row?.stopped ?? false,
+        authorIsBot,
+        isAppMention: false, // an addressed comment never reaches this function
+        inThread: true, // an anchored Notion page IS the container engagement is kept per
+    });
+    if (decision.deliver)
+        return { kind: "deliver", anchor, reason: decision.reason };
+    return { kind: "hold", anchor, reason: decision.reason, stopped: row?.stopped === true };
+}
+/**
+ * Mark one page ENGAGED on an addressed (name-drop or structured-mention) comment. ONCE PER COMMENT.
+ *
+ * `participating: true` is the re-invitation: it promotes the row and CLEARS a previous stand-down,
+ * which is what "name the agent to bring it back" means here.
+ *
+ * 🔴 THE MARK IS DEDUPED, AND THE STOP IS WHY — the same durable guard GitHub's and Linear's marks
+ * take. Clearing the flag is right for a person's second name-drop and WRONG for Notion redelivering
+ * the first one. THE ROUTE DOES NOT ALWAYS ACK, so the redelivery is reachable: `handleNotionDelivery`
+ * carries no top-level `catch`, and eve's channel dispatcher answers a throw with a 500 — while this
+ * mark sits ABOVE `getOrCreateSession` and the wake, either of which can throw on a store outage. The
+ * sequence that costs is then: name-drop marks the page, the mint throws, Notion is told 500, somebody
+ * asks the agent to stand down, and Notion's retry of the original comment lifts the stop.
+ * `commentId` is the trigger comment's own id, so the guard keys on the thing that must happen once.
+ * DURABLE layer only, and it expires with the store's TTL — a retry later than that window can still
+ * re-mark. FAIL-OPEN on a store error, the posture every dedupe in this repository takes.
+ *
+ * Best-effort throughout — `markThreadEngaged` swallows a store failure, because engagement
+ * bookkeeping must never fail a turn. Returns the anchor it marked, or null when it marked nothing.
+ */
+export async function markNotionEngaged(f, commentId, deps = {}) {
+    const anchor = notionEngagementAnchor(f);
+    if (!anchor)
+        return null;
+    const partition = notionSeamPartition(f);
+    if (!partition)
+        return null;
+    const now = deps.now ?? (() => new Date().toISOString());
+    const atIso = now();
+    if (commentId !== undefined && commentId.length > 0) {
+        const seen = deps.markEventSeen ?? liveMarkEngageSeen;
+        if (!(await seen(partition.org, `notion-engage:${anchor}:${commentId}`, atIso)))
+            return null;
+    }
+    const mark = deps.markEngaged ?? ((p, key, at) => markThreadEngaged(p, key, at, { participating: true }));
+    await mark(partition, anchor, atIso);
+    return anchor;
+}
+/**
+ * ONE WAKE PER COMMENT (OPE-1906). TRUE = this comment has not woken the agent inside the window,
+ * so the caller should dispatch. FALSE = the same comment id already did, so the caller must not.
+ *
+ * 🔴 THE OTHER HALF OF THE LOOP GUARD, AND THE CLASSIFIER CANNOT BE IT. `classifyNotionComment`
+ * reads one comment's author; a REDELIVERY of a person's comment carries the same author and the
+ * same text, so it classifies identically and dispatches again — a second model turn, a second
+ * `notion.dispatched` row, and a second reply into the discussion. Nothing else on this road is
+ * keyed on the delivery, so this is the only place that can say "again".
+ *
+ * REDELIVERY IS REACHABLE, and {@link markNotionEngaged} above already says why: the route does not
+ * always ack. `handleNotionDelivery` carries no top-level `catch`, and eve's channel dispatcher
+ * answers a throw with a 500, so Notion retries. A page shared with two subscriptions delivers the
+ * same comment twice by design (OPE-467), and a vendor retry needs no failure of ours at all.
+ *
+ * 🔴 THE MARK IS TAKEN BEFORE THE WAKE, AND THAT TRADE IS DELIBERATE. Marking afterwards would let
+ * two concurrent deliveries of one comment both run a turn, which is the cost this guard exists to
+ * stop; `markEventSeen` is atomic across instances, so marking first stops them. The price is that
+ * a delivery whose dispatch THROWS is not retried inside the window — the same price the engage
+ * mark one step above already pays, and the reason this guard sits as LATE as it can, below every
+ * cheaper refusal, so only a delivery that was really about to wake a turn ever spends a mark.
+ *
+ * 🔴 A SUITE THAT DRIVES `handleNotionDelivery` PAST THIS POINT MUST INJECT `markEventSeen`, or
+ * pin its own store path. The default is the DURABLE operational store, and an unpinned suite in
+ * this package shares one sqlite file (scripts/suite-store-isolation-lint.ts says why) — so a suite
+ * that replays a fixed comment id writes a mark that survives the run, and its NEXT run reads
+ * `duplicate-delivery` where it expected `dispatched`. `lint:suite-store` cannot catch that: its
+ * reach test is a source scan, and such a suite names no store entry point of its own. Five suites
+ * inject the stub today.
+ *
+ * FAIL-OPEN, three ways: a store error, an unresolvable partition and a delivery with no comment id
+ * all answer TRUE, so an outage costs a duplicate turn rather than a deaf deployment. The try/catch
+ * covers the INJECTED edge too, not just the live default (the shape webhooks/replay-dedupe.ts and
+ * webhooks/reject-audit.ts take) — which is how a test drives the fail-open arm without breaking a
+ * real store. `commentId` is the thing that must happen once, and a Notion comment id is globally
+ * unique, so the key needs no anchor.
+ */
+export async function firstNotionDispatchOfComment(f, commentId, deps = {}) {
+    if (commentId === undefined || commentId.length === 0)
+        return true;
+    const partition = notionSeamPartition(f);
+    if (!partition)
+        return true;
+    const now = deps.now ?? (() => new Date().toISOString());
+    const seen = deps.markEventSeen ?? liveMarkDispatchSeen;
+    try {
+        return await seen(partition.org, `notion-dispatch:${commentId}`, now());
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * WHAT WOKE ONE ADMITTED DELIVERY, in the wake envelope's own vocabulary (core's `WakeAddressing`).
+ * It is the value the `notion.dispatched` audit row reports, and NO PRODUCT CODE BRANCHES ON IT.
+ * Every reader is an EVIDENCE reader outside the product: the journey pack's `reportedThreadFollow`
+ * (packages/core/scripts/e2e/engaged-rows.ts) gates `J-ENGAGED-notion`'s follow-up step on it,
+ * `drive-notion-namedrop.ts` prints and asserts it, and the test tiers read it. So changing the
+ * value moves what the pack can prove; it moves no delivery decision.
+ *
+ * 🔴 IT IS DELIBERATELY NOT THE CLASSIFIER'S VALUE. The classifier answers one question — did this
+ * comment ADDRESS the agent — and an engaged follow-up did not, so it stays `channel-watch`. The
+ * supervisor core needs that: `channel-watch` is what makes the turn a JUDGED one, and promoting it
+ * would silence the very wake this seam exists to admit.
+ *
+ * 🔴 BUT `channel-watch` ALSO NAMES UNOWNED ROOM CHATTER on an ambient page, and the audit row is
+ * the one place those two must not read alike. A row that reported `channel-watch` for both cannot
+ * tell an ENGAGED wake from an AMBIENT one, and that distinction is the whole evidentiary worth of
+ * the §2.5 seam on this surface: it is what `J-ENGAGED-notion` gates its follow-up step on
+ * (`reportedThreadFollow`, packages/core/scripts/e2e/engaged-rows.ts). Until OPE-1501 the row was
+ * unreachable on an addressed-only page — the ambient gate returned before the classifier ran — so
+ * the collision cost nothing. The gate now admits an engaged follow-up, and the collision costs the
+ * proof, which is what OPE-1510 fixed here.
+ *
+ * 🔴 IT REPORTS THE REGISTRY, NOT THE DOOR. The seam is read for every plain comment, above and
+ * independently of the ambient gate, so on an ambient-ENABLED page a plain comment on an engaged
+ * page also reads `thread-follow` — the ambient flag would have admitted it either way. The value
+ * therefore separates an engaged wake from an ambient one only where the domain has ambient OFF,
+ * which is the addressed-only posture the journeys drive.
+ *
+ * `engagedFollowUp` is the webhook core's own seam verdict, and the `channel-watch` guard below is
+ * belt-and-braces: an ADDRESSED comment never asks the seam, so it can never carry the flag.
+ */
+export function notionWakeAddressing(addressing, engagedFollowUp) {
+    return addressing === "channel-watch" && engagedFollowUp === true ? "thread-follow" : addressing;
+}
+/**
+ * THE SEAM'S WHOLE CONTRIBUTION TO THE AUDIT ROW, as one pure mapping.
+ *
+ * 🔴 THE TWO FIELDS ANSWER DIFFERENT QUESTIONS, AND A ROW NEEDS BOTH. `addressing` says WHAT WOKE
+ * the delivery. `via` says HOW THE OPERATOR DECLARED THE PAGE, which is the domain origin the
+ * addressed door gated on (`notionPageDomain`, channels/notion-scope.ts). A `container` claim
+ * reaches pages NOBODY ENUMERATED — the whole workspace, or a same-level page glob, which are the
+ * two shapes a container entry may take (memory/domain.ts); a `roster` entry is a page an
+ * operator wrote down. Both reach the same door, and a row carrying only `addressing` reports them
+ * identically — which leaves the wider admission looking exactly like the narrower one in the
+ * audit trail. The row says WHICH KIND of claim, never how wide that claim is: read the domain's
+ * own container entry for the breadth.
+ *
+ * `via` is the webhook core's own read, carried on the dispatch. An absent field reads `none`: the
+ * conservative word, so a caller that omits it can never claim a declaration it did not make.
+ */
+export function notionWakeAuditDetail(addressing, engagedFollowUp, via) {
+    return { addressing: notionWakeAddressing(addressing, engagedFollowUp), via: via ?? "none" };
+}
+/** How long this module remembers one comment id — the window both durable guards below key on.
+ *  It bounds the vendor retry both of them answer, so ONE number serves both: a redelivery this
+ *  module treats as "again" for the mark must be "again" for the wake too, or the two guards would
+ *  disagree about the same delivery. */
+const NOTION_DEDUPE_TTL_MS = 10 * 60_000;
+/** The durable half of the mark dedupe. FAIL-OPEN: an unreachable store answers "not seen", so a
+ *  store outage costs a redundant mark rather than a lost engagement. */
+let warnedEngageDedupe = false;
+async function liveMarkEngageSeen(org, key, atIso) {
+    try {
+        return await getOperationalStore().markEventSeen(org, key, atIso, NOTION_DEDUPE_TTL_MS);
+    }
+    catch (err) {
+        if (!warnedEngageDedupe) {
+            warnedEngageDedupe = true;
+            console.warn(`[open-everywhere:notion-engagement] engage dedupe unavailable — a redelivered name-drop may re-mark: ${String(err)}`);
+        }
+        return true;
+    }
+}
+/** The durable half of the WAKE once-guard ({@link firstNotionDispatchOfComment}). Same window as
+ *  the mark above, and the same FAIL-OPEN posture: an unreachable store costs a duplicate turn,
+ *  never a silenced comment. */
+let warnedDispatchDedupe = false;
+async function liveMarkDispatchSeen(org, key, atIso) {
+    try {
+        return await getOperationalStore().markEventSeen(org, key, atIso, NOTION_DEDUPE_TTL_MS);
+    }
+    catch (err) {
+        if (!warnedDispatchDedupe) {
+            warnedDispatchDedupe = true;
+            console.warn(`[open-everywhere:notion-engagement] dispatch dedupe unavailable — a redelivered comment may wake a second turn: ${String(err)}`);
+        }
+        return true;
+    }
+}
+/**
+ * Build the join ids for the row. Pure, and EVERY FIELD IS AN ID — never a comment body, an author
+ * name or a page title.
+ *
+ * 🔴 WHY THE ROW NEEDS THEM. Before this, `notion.dispatched` recorded the discussion and the
+ * addressing but nothing that identified the DELIVERY, so a leg that forged one replay could only
+ * scan a time window for a verdict row and hope no other wake fell inside it. S-TAINT-DRYRUN Arm B
+ * did exactly that and the scan could not tell its own replay's verdict from an ambient one
+ * (OPE-1907). With the delivery id on the row, one forge joins one wake joins one session.
+ *
+ * An absent value is OMITTED rather than written as `undefined`: an audit row that carries a key
+ * with no value reads, to anyone querying it, like a value that was looked for and found empty.
+ */
+export function notionDispatchJoinDetail(ids) {
+    const out = {};
+    if (ids.deliveryId)
+        out.deliveryId = ids.deliveryId;
+    if (ids.commentId)
+        out.commentId = ids.commentId;
+    if (ids.wakeId)
+        out.wakeId = ids.wakeId;
+    return out;
+}
+//# sourceMappingURL=notion-engagement.js.map

package/dist/agent/channels/notion-engagement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-engagement.js","sourceRoot":"","sources":["../../../agent/channels/notion-engagement.ts"],"names":[],"mappings":"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"}

package/dist/agent/channels/notion-event-normalizer.d.ts

@@ -0,0 +1,194 @@
+import { type Domain, type EventNormalizer, type EventScopeGrant, type NormalizedEvent, type ScopeStep } from "@open-everywhere/core/agent/adapter-api.js";
+/**
+ * The registry key for BOTH halves of the event plane, and it is the SAME string the webhook
+ * verifier registers under — one contract, spelled once. (Since OPE-198 S2 this key is the
+ * delivery's SCHEME; on the native Notion route the scheme and the hook name coincide.)
+ */
+export declare const NOTION_EVENT_SOURCE = "notion";
+/** Event-type families that are WORK — routed into the event plane. Prefix-matched on the
+ *  verbatim `type` discriminator (`page.properties_updated`, `data_source.schema_updated`, …). */
+export declare const NOTION_STRUCTURAL_PREFIXES: readonly string[];
+/** Event-type families that are CONVERSATION — the ambient supervisor's, never a routine's.
+ *  Named explicitly (rather than falling into the unrecognised bucket) so the partition is a
+ *  reviewed statement in code and a reader can see that the omission is deliberate. */
+export declare const NOTION_CONVERSATIONAL_PREFIXES: readonly string[];
+/** Notion's webhook envelope, probed defensively — a mis-shaped payload must yield `null`, never a
+ *  throw (a normalizer that throws is caught by `normalizeDelivery`, but an ingress should not rely
+ *  on that to avoid a 500). Mirrors `notion-api.ts`'s loose typing of the same envelope. */
+export interface NotionEventEnvelope {
+    readonly id?: unknown;
+    readonly timestamp?: unknown;
+    readonly workspace_id?: unknown;
+    readonly type?: unknown;
+    readonly event_type?: unknown;
+    readonly authors?: unknown;
+    readonly entity?: {
+        readonly id?: unknown;
+        readonly type?: unknown;
+    };
+    readonly data?: {
+        readonly parent?: {
+            readonly id?: unknown;
+            readonly type?: unknown;
+        };
+        readonly updated_blocks?: unknown;
+    };
+}
+/** Is this event type WORK (routable), CONVERSATION (the supervisor's), or unrecognised? Exported
+ *  so the disjointness can be asserted directly rather than inferred from `normalize` returning
+ *  null for two different reasons. */
+export declare function notionEventClass(type: string | undefined): "structural" | "conversational" | "unrecognised";
+/**
+ * The delivery id Notion carries for one event — its top-level `id`, which is in the BODY (Notion
+ * publishes no delivery-id header). THE supported way for the Notion ingress to populate
+ * {@link TriggerDelivery.deliveryId}, which is what arms `admitTrigger`'s durable replay dedupe.
+ * Returns undefined for an unparseable body and for a blank id alike — both are "this delivery has
+ * no id", which the plane already models as not-deduped rather than dropped.
+ */
+export declare function notionEventDeliveryId(rawBody: string): string | undefined;
+/** The scope path one envelope proves. Exported for the unit test, which drives it directly. */
+export declare function notionScopePath(ev: NotionEventEnvelope): ScopeStep[];
+/** Lift one Notion envelope onto the v2 event model, or null when it is not ours to route.
+ *  Exported for the unit test, which drives it directly rather than through the registry. */
+export declare function liftNotionEvent(ev: NotionEventEnvelope, declaredSource: string): NormalizedEvent | null;
+export declare const notionEventNormalizer: EventNormalizer;
+/**
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 NOTION'S READ GRANT — AND THE BOUNDARY IT IS *NOT*.
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * WHAT OE ACTUALLY HOLDS, MEASURED (a design note §1, §6; `notion-api.ts`
+ * `resolveNotionCredential`): an INTERNAL INTEGRATION SECRET (`db:notion:channel-key`, broker `db`) —
+ * one for the whole deployment by default, or one per domain that binds its own (OPE-467). Each is
+ * bearer-token-flat: there is no scopes string, it is bound to a single workspace at creation, and
+ * what it can see is a SHARE LIST maintained on NOTION'S side, page by page, by workspace members.
+ *
+ * 🔴 THEREFORE THE CREDENTIAL CANNOT BE THE BOUNDARY, AND THIS ADAPTER DOES NOT PRETEND IT IS.
+ * Three properties make that unavoidable, and each one alone would be enough:
+ *   1. A domain need not bind its own integration, and by default none does — ten domains then
+ *      reach Notion with the same bytes, so nothing credential-derived can differ between them.
+ *      A grant rule that held only for BOUND domains would be a rule with a config-shaped hole.
+ *   2. The share list is invisible to OE — it is not in any config we hold and there is no API that
+ *      would let a PURE, SYNC `grantsRead` consult it even if it were.
+ *   3. `EffectiveAccess` has no Notion-shaped granted resource to express it over (`repos` is a
+ *      hardcoded GitHub `string[]`), and inventing one for a credential nobody varies per domain
+ *      would be schema for a distinction that does not exist.
+ * A `grantsRead: () => true` with those facts in a comment is the failure class this tree has a
+ * name for — a documented absence of a boundary that LOOKS like a boundary — so it is not what
+ * ships here.
+ *
+ * WHAT *IS* A REAL, PER-DOMAIN, DEPLOYER-OWNED NOTION BOUNDARY: which domain a Notion surface
+ * belongs to. `domainsForSurface` reads the static `domains` registry in the app tree — deployer
+ * config, merged by PR, validated at module load, with a surface belonging to at most ONE domain.
+ * It is the SAME authority, over the SAME `notion/<workspace>/<page>` surface key, that already
+ * gates whether the ambient supervisor may engage on that page at all (`notion.ts`
+ * `notionAmbientEnabled`). So the rule is:
+ *
+ *   A routine may be triggered by a Notion event iff the routine's partition is in a domain the
+ *   deployer put the affected Notion surface in.
+ *
+ * It REFUSES things that are real: a routine in domain `payments` cannot subscribe to a page the
+ * deployer put in `security`; a page in NO domain cannot trigger anything anywhere; a delivery
+ * proving only a workspace is refused outright, because a workspace is not a surface anybody
+ * configured.
+ *
+ * INNERMOST-CONFIGURED-WINS, AND IT NEVER FALLS THROUGH A REFUSAL. The walk goes inwards→outwards
+ * and the FIRST step the registry knows about is authoritative: it grants or it refuses, and the
+ * walk stops. A step the registry says nothing about is skipped (deployers configure pages and
+ * databases, not every descendant), which is what makes the rule usable — but continuing PAST a
+ * refusal would let a parent-database grant authorize a child page the deployer deliberately put
+ * somewhere else, which is the widening this ordering exists to prevent.
+ *
+ * ⚠️ TWO ASSUMPTIONS, STATED BECAUSE THEY ARE THE ONES MOST LIKELY TO SHIFT.
+ *   • `loadDomains` is explicitly a swappable seam ("the seam a DB/dashboard would swap behind",
+ *     memory/config/domains.ts). This grant's authority class is TIED to that seam staying deployer-owned:
+ *     the day a dashboard lets a non-deployer edit domain membership, this rule silently weakens to
+ *     whatever authorizes that editor.
+ *   • Notion's own share list is a SECOND fence underneath this one, not a substitute for it: a
+ *     subscription only delivers events for objects the connection was shared onto, so a delivery
+ *     arriving at all already proves OE can see the object. That fact is OE-wide, never per-domain,
+ *     which is exactly why it cannot be the grant.
+ *
+ * ⚠️ IT READS CONFIG, WHICH GITHUB'S GRANT DOES NOT NEED TO. `grantsRead` is documented PURE — no
+ * I/O, no ctx, no fetch — and this stays inside that: `getConfig()` is a registry read and
+ * `domainsForSurface` reads static, module-load-validated config. It is the SAME read
+ * `requestForPartition` (event-authz.ts) already performs on this exact fire path, so it introduces
+ * no new authority class and no new I/O. An unregistered config throws, `checkEventReadGrant`
+ * catches it as `unresolvable`, and the delivery fails CLOSED.
+ */
+/**
+ * The scope steps that can DECIDE a Notion delivery, innermost first. The first step any domain owns
+ * is authoritative — it grants or it refuses, and the walk stops there.
+ *
+ * ⭐ ONE LIST, TWO READERS, ON PURPOSE. {@link notionEventScopeGrant} walks it to find the step that
+ * AUTHORIZES, and {@link notionTriggerScopeVerdict} walks it to find the step it must check the
+ * SIGNER against. If the two walked different orders, the fence would check one step and the grant
+ * would authorize another, which is the exact shape of a fence that looks applied and is not.
+ *
+ * 🔴 `tenant` IS DELIBERATELY ABSENT. The grant's own comment holds the standing reason; the fence
+ * inherits it, and inherits the consequence too — a forged `workspace_id` is never checked directly.
+ * It does not need to be. The tenant only changes WHICH domain a step below resolves to, and the
+ * fence then reads that domain's credential.
+ */
+export declare const NOTION_GRANT_STEPS: readonly ["sub", "entity", "container", "group"];
+export declare const notionEventScopeGrant: EventScopeGrant;
+/** {@link notionTriggerScopeVerdict}'s answer. `ok` is the ONLY field a caller may branch on; the
+ *  `reason` is operator-facing prose for the log line and carries no control flow. */
+export type NotionTriggerScopeVerdict = {
+    readonly ok: true;
+    readonly detail: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 THE INGRESS FENCE (OPE-500) — MAY THIS SIGNER ROUTE A DELIVERY ABOUT THIS SCOPE?
+ * ════════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * `channels/notion.ts` calls this on every VERIFIED structural delivery, BEFORE `admitTrigger`. A
+ * refusal drops the delivery out of the trigger plane. It never affects the ambient comment path,
+ * which has its own OPE-496 resolution and never reaches this function.
+ *
+ * THE RULE, in one sentence:
+ *
+ *   A delivery may arm a routine on a scope only when the domain that owns that scope is a domain
+ *   the SIGNING integration serves.
+ *
+ * WHY THAT IS THE RIGHT AUTHORITY. The signing integration is the ONE authenticated fact a delivery
+ * carries (`gateNotionDeliveryAcross` — the secret that verifies identifies the sender). The scope
+ * path is not authenticated at all. `notion-credentials.ts` already establishes which integration a
+ * domain binds, and that binding is deployer config merged by PR. So this asks the payload's claim
+ * one question the payload cannot answer for itself, and answers it from config.
+ *
+ * WORKED THROUGH, because the point is what it REFUSES. Domain `payments` binds integration
+ * `notion-payments` with its own inbound secret. A holder of `notion-payments`'s `verification_token`
+ * signs a body naming a `security` page. The granting step resolves to `security`, whose credential
+ * is `notion-security` (or the org default). That is not the signer, and the two do not share an
+ * inbound secret, so the delivery routes nothing.
+ *
+ * 🔴 THE ONE THING IT CANNOT SEPARATE, STATED PLAINLY. Two integrations that share an INBOUND SECRET
+ * are indistinguishable to the HMAC gate — `connectorIntegrations` defaults a domain's
+ * `inboundSecret` to the deployment default, so a domain that binds a credential WITHOUT declaring
+ * its own inbound secret signs exactly like the org default. This function accepts that case rather
+ * than refusing it, because refusing would break a supported config in which the domain runs no
+ * subscription of its own. The honest statement of the property is therefore:
+ *
+ *   A domain is fenced from another domain's forged deliveries IFF it runs its own inbound secret.
+ *
+ * That is the same condition `notion-credentials.ts` already states for the read boundary, and the
+ * runbook already tells operators to satisfy it. It is not a hole this function opens; it is the
+ * limit of what the HMAC can tell one sender from another.
+ *
+ * FAIL CLOSED, AND THE REFUSALS ARE REAL. No signer (the dev hatch), an unparseable body, and a path
+ * no domain owns all refuse. The last one costs nothing: {@link notionEventScopeGrant} would refuse
+ * the same delivery a moment later, so dropping it here only makes the refusal legible.
+ *
+ * PURE. `resolveSurface` defaults to the same `getConfig().domainsForSurface` the grant reads, and is
+ * injectable so the test drives every arm with no registry.
+ */
+export declare function notionTriggerScopeVerdict(rawBody: string, signerCredentialId: string | undefined, domains: readonly Domain[], resolveSurface?: (p: {
+    workspaceKey: string;
+    surface: string;
+}) => readonly string[]): NotionTriggerScopeVerdict;
+//# sourceMappingURL=notion-event-normalizer.d.ts.map

package/dist/agent/channels/notion-event-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-event-normalizer.d.ts","sourceRoot":"","sources":["../../../agent/channels/notion-event-normalizer.ts"],"names":[],"mappings":"AAmHA,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EAEf,MAAM,4CAA4C,CAAC;AAKpD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,WAAwB,CAAC;AAEzD;kGACkG;AAClG,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAA2C,CAAC;AAEpG;;uFAEuF;AACvF,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAAiB,CAAC;AAE9E;;4FAE4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;KACnC,CAAC;CACH;AAsBD;;sCAEsC;AACtC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,gBAAgB,GAAG,cAAc,CAK3G;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,EAAE,EAAE,mBAAmB,GAAG,SAAS,EAAE,CAiCpE;AAED;6FAC6F;AAC7F,wBAAgB,eAAe,CAAC,EAAE,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAwDvG;AAED,eAAO,MAAM,qBAAqB,EAAE,eA6BnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,YAAI,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC;AAEnF,eAAO,MAAM,qBAAqB,EAAE,eAwCnC,CAAC;AAkBF;sFACsF;AACtF,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,cAAc,GAAE,CAAC,CAAC,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,SAAS,MAAM,EAA4C,GAC5H,yBAAyB,CA6D3B"}