@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-supervisor.d.ts

@@ -0,0 +1,462 @@
+import { type VendorEventTime, shouldRotate, type ExternalPolicy, type IngestedChatMessage, type NormalizedWake, type WakeEngagementTier, type WakeMessageInput, type WakeTrust, type UnifiedWindowWake, type SessionTailWakeRow, type SeatCatchUpRequest, type SeatCatchUpResult } from "@open-everywhere/core/agent/adapter-api.js";
+import { type NotionComment } from "./notion-api.js";
+import type { NotionOwnBotIds } from "./notion-bot-user.js";
+import type { OpenEverywhereNotionAuth } from "./notion-identity.js";
+import type { NotionDeliveryTrust } from "./notion-ancestry-trust.js";
+import type { NotionSessionState } from "./notion-webhook.js";
+import type { NotionVia } from "./notion-scope.js";
+/** The reserved pseudo-thread sentinel for a supervisor generation (mirrors Slack's). */
+export declare function notionSupervisorSentinel(generation: number): string;
+/** The reserved continuation token for a page's supervisor session at a given generation:
+ *  `notion:<pageId>:oe-sup:g<generation>`. Contains the `:oe-sup:g` infix hooks/spend.ts keys on,
+ *  and is stable+explicit by construction (a custom-channel token eve never re-anchors — so,
+ *  UNLIKE Slack, no non-empty state.threadTs re-anchor sentinel is needed; design §3.1). */
+export declare function notionSupervisorToken(pageId: string, generation: number): string;
+/** How a comment addresses the doc supervisor. `drop` = never wake (loop/bot guards); `direct` =
+ *  a structured bot @mention, the guaranteed-engage conversation-driver treatment; `channel-watch`
+ *  = judged by the standing supervisor (the ambient default — most comments). */
+export type NotionAddressing = "direct" | "channel-watch" | "drop";
+export interface NotionClassification {
+    readonly addressing: NotionAddressing;
+    readonly reason: string;
+}
+/**
+ * The Notion synthetic-mention (name-drop) convention. Notion CANNOT @mention an internal
+ * integration (notion-webhook.ts — the structured `mentionsUser` path is STRUCTURALLY DEAD for the
+ * agent), so a person addresses the doc agent by NAME instead: the deployment's configured names
+ * (OE_AGENT_NAME / OE_AGENT_SHORT_NAME, defaulting to the brand "open everywhere" / "oe" when unset)
+ * or the platform-resolved integration name (botName). This is the ONLY ambient-INDEPENDENT directed
+ * input Notion has, so — unlike Slack/GitHub/Linear, where a name-drop stays a judged input because a
+ * real @mention is available — here it is promoted to `direct`.
+ *
+ * The name set + word-boundary matcher live in core (identity/bot-name.ts matchesAgentName), which
+ * is ALSO what the addressed link-claim recogniser strips its leading token with (hooks/link-claim.ts)
+ * — one source of truth for "what does this agent answer to". Word-boundary matched (`\b`) so the
+ * short "oe" token never fires inside "Zoe"/"poet"/"does". A hit flows through the SAME seam a real
+ * @mention would: planNotionSingleWindow stamps `direct-mention`, which marks the wake as OWED a
+ * reply and tells the seat so. 🔴 THE STAMP DELIVERS NOTHING BY ITSELF (OPE-1982): the terminal-prose
+ * bridge it used to arm is deleted, so the reply lands via createCommentReply only when the seat
+ * calls `reply` — on its own turn, or on the ONE corrective re-drive a prose ending earns.
+ */
+export declare function notionNameDrop(text: string, botName?: string): boolean;
+/**
+ * Decide how the doc supervisor should treat one comment. The self-reply loop guard is HARDENED
+ * here (design §4.2), in cost order:
+ *  1. UNRESOLVED PRIMARY bot user id ⇒ DROP (fail closed) — self-identity is a precondition for the
+ *     loop guard; without it the agent would loop on its own replies (each createCommentReply fires a
+ *     fresh comment.created). This is the critical hardening over the old `if (botUserId && …)`.
+ *  2. SELF-authored ⇒ DROP — our own posted reply. The comparison is `created_by.id` against
+ *     {@link NotionOwnBotIds.all}: EVERY configured integration's bot user id, not only the one that
+ *     verified this delivery (OPE-1921). THAT IS THE WHOLE GUARD.
+ *     🔴 THE SET IS WHAT MAKES IT A GUARD ON A DEPLOYMENT RATHER THAN ON ONE INTEGRATION. Two
+ *     integrations can both see one page, so a reply integration A posted is delivered on B's
+ *     subscription too. Compared against B's id alone it matched nothing, read as a person and woke
+ *     a turn; A's subscription then saw B's answer. Each reply is a NEW comment id, so the OPE-1906
+ *     once-guard cannot bound that loop — only recognising our own words can.
+ *  3. UNIDENTIFIED AUTHOR (no `created_by.id`) ⇒ DROP (fail closed) — step 2 is the only check that
+ *     can recognise our own words, so a comment whose author id we cannot read defeats it.
+ *     🔴 WITHOUT THIS STEP THE GUARD FALLS BACK ON `created_by.type`, A FIELD NOTION MAY OMIT
+ *     (OPE-1857, notion-api.ts NotionComment): a comment's `created_by` is a PARTIAL user, so an
+ *     id-less author reached step 4 with nothing to test, read as a person, and woke a turn. That
+ *     is the same fail-closed posture step 1 takes for the other half of the comparison — an
+ *     identity we cannot establish never wakes the agent, in EITHER direction.
+ *  4. BOT/integration-authored (created_by.type present and not "person") ⇒ DROP — the Slack
+ *     authorIsBot analog, prevents bot-to-bot loops. A BACKSTOP for a foreign bot, never the
+ *     self-guard: an ABSENT `type` says nothing, and steps 2-3 have already answered "is it ours".
+ *  5. INCOMPLETE OWN-ID SET ⇒ DROP (fail closed, OPE-1921) — one configured integration's bot user
+ *     id did not resolve, so step 2 could not have recognised that integration's own reply. An
+ *     author Notion states is a `person` is still admitted; an author it says NOTHING about is
+ *     exactly the ambiguity the loop rides, so it drops.
+ *     🔴 IT COSTS AVAILABILITY AND THE TRADE IS DELIBERATE — see {@link NotionOwnBotIds.complete}.
+ *     A deployment that cannot resolve one integration's id is deaf to every comment Notion does not
+ *     mark `person`-authored until it can. 🔴 THAT IS NOT ONLY AMBIENT CHATTER: this step sits ABOVE
+ *     steps 6 and 7, so an addressed structured @mention, an addressed name-drop and an
+ *     `oe link <code>` identity claim all drop with it. Failing OPEN instead buys an unbounded reply
+ *     loop between two of our own integrations, which no once-guard can stop.
+ *  6. STRUCTURED bot @mention ⇒ direct (guaranteed engage). Structurally unreachable for an
+ *     internal integration today, but kept as the canonical addressed signal. Tested against the
+ *     PRIMARY id alone: a structured mention names ONE bot user, and answering a mention of a
+ *     sibling integration would put this integration in a conversation it was not addressed in.
+ *  7. NAME-DROP ⇒ direct ({@link notionNameDrop}). Notion's ONLY addressed path (no integration
+ *     @mention), so a brand/name hit is promoted to the owed-a-reply treatment, not left as a
+ *     judged input — this is the deliberate Notion-specific divergence from Slack/GitHub/Linear.
+ *  8. otherwise ⇒ channel-watch (judged by the standing doc supervisor).
+ *
+ * 🔴 THIS FUNCTION GUARDS ONE COMMENT, NOT ONE WAKE. It cannot tell a second delivery of the SAME
+ * comment from the first, because both carry identical bytes. The delivery once-guard is the other
+ * half of the loop defence and lives at the ingress
+ * (notion-engagement.ts `firstNotionDispatchOfComment`, called by notion-webhook.ts).
+ */
+export declare function classifyNotionComment(comment: NotionComment, own: NotionOwnBotIds, botName?: string): NotionClassification;
+/** The host-frozen reply-target facts one comment.created delivery resolves (the webhook core's
+ *  dispatch fields) — everything {@link planNotionSingleWindow} needs to mint the wake origin. */
+export interface NotionSingleWindowTarget {
+    /** The trigger comment's inline discussion thread — createCommentReply's discussion_id target.
+     *  Empty ⇒ no freezable reply target ⇒ NO window (fail closed, never an unresolvable wake). */
+    readonly discussionId: string;
+    readonly pageId?: string;
+    readonly workspaceId?: string | null;
+    /** The Notion integration this delivery VERIFIED under (OPE-467) — frozen into the origin so the
+     *  unified reply posts under the credential that fetched the trigger comment. */
+    readonly credentialId?: string;
+    /** The first latency anchor (OPE-1716), recorded on the ingress row. A Notion delivery carries no
+     *  vendor clock this seam can read, so the caller passes its own FRONT-DOOR RECEIPT — which makes
+     *  the vendor→ingress segment a lower bound, and the row's `vendorTsSource` says so. */
+    readonly vendorTs?: VendorEventTime;
+}
+/**
+ * The ONE single-window decision for a Notion delivery (channels/unified-window.ts
+ * singleWindowMentionPolicy is the SHARED seam — the exact function the GitHub reference's
+ * native-suppression AND classifier consult, github.ts:261 / github-supervisor.ts:139): given
+ * the grain's `singleWindow`, whether the classified comment is a structured @mention
+ * (classifyNotionComment returned `direct`), and the PRIVACY FLOOR `privacyOk`, return the
+ * {@link UnifiedWindowWake} the dispatch should carry, or undefined for the byte-identical
+ * native path.
+ *
+ * `privacyOk` is the OPERATOR-VOUCH fact the caller resolves (notion.ts): identity/trust.ts
+ * isVouchedInternal on the page's workspaceKey/surfaceKey (or the OE_TRUST=internal blanket
+ * switch), fail-closed when unregistered. This is the SAME per-surface allowlist that gates
+ * Notion's shared MEMORY (notion-identity.ts / bindNotion), so a page is admitted to the shared
+ * cross-surface WINDOW exactly when the operator has vouched it internal — never inferred from a
+ * misleading API field (a Notion page's `public_url` is set ONLY by publish-to-web and is null
+ * for the common guest-shared vector, so it would admit an external guest's mention; the vouch
+ * register is the doctrine-correct floor — operator vouches, code enforces, no inference).
+ *
+ * Notion's mention signal lives in ONE webhook delivery (unlike Slack's dual-event), and its
+ * "native" handler IS this same supervisor dispatch — so suppress-native and divert are the SAME
+ * act here: a window-carrying wake is delivered through the unified channel instead of the notion
+ * channel's own send (notion.ts's wake dep), and both legs read THIS one verdict off the one
+ * parsed event — structurally never a double-handle, never a gap:
+ *   • @mention on a singleWindow, VOUCHED-internal page → the seam suppresses the native session
+ *     and stamps `addressing:"direct-mention"` (the terminal-prose delivery bridge's arm);
+ *   • ambient (channel-watch) comment on the same page → Leg A: the window WITHOUT the addressed
+ *     stamp (judged treatment in the shared window, prose stays hard-dropped);
+ *   • un-vouched page, or singleWindow off, or no discussion id → undefined (the native
+ *     per-doc/domain path, byte-identical — a mention there keeps today's `direct` wake).
+ */
+export declare function planNotionSingleWindow(singleWindow: boolean, isMention: boolean, privacyOk: boolean, target: NotionSingleWindowTarget): UnifiedWindowWake | undefined;
+/** One comment reshaped for the wake — the trigger, or a discussion-sibling backscroll message.
+ *  `from` is resolved by the caller (self when the bot authored it, else human). */
+export interface NotionWakeMessage {
+    readonly from: "human" | "self";
+    readonly id: string;
+    readonly authorId?: string;
+    readonly sentAt: string;
+    readonly text: string;
+    /** Authenticated parent block of an inline comment. Absent for page-level discussions. */
+    readonly anchorId?: string;
+    /**
+     * Resolved per-message trust tier (identity/wake-trust.ts — the audit-wedge F3 assignment). The
+     * live dispatch (notion.ts) resolves it off the binding gate + admin rosters, for the trigger AND
+     * every discussion sibling.
+     *
+     * 🔴 REQUIRED, NOT OPTIONAL (OPE-596) — see LinearSupervisorWakeInput.trigger.trust. The trigger
+     * used to default to `principal` on the direct path and a sibling to `peer`, both fail-OPEN, and
+     * since OPE-577 the tier decides the `<untrusted_external_data>` fence. A caller that cannot
+     * resolve a tier states the fail-closed one itself: `relay` for a machine author, `unauth` for an
+     * unvouchable human.
+     */
+    readonly trust: WakeTrust;
+}
+/**
+ * The SAME message BEFORE any author tier is resolved — what notion-webhook.ts produces (OPE-596).
+ *
+ * The webhook core reads the comment payload; it holds no binding context, so it cannot answer "what
+ * standing does this author carry?". The ROUTE answers that, once, for the trigger and every
+ * sibling alike (notion.ts `trustOf`, fail-closed to `relay`). This type states that split instead
+ * of leaving it to a convention: an untiered message is NOT a {@link NotionWakeMessage} and the
+ * compiler will not let one reach {@link buildNotionSupervisorWake}. Before OPE-596 the same two
+ * shapes shared one type and the builder defaulted the missing tier UPWARD, so a route leg that
+ * forgot the stamp would have rendered a stranger's comment as a member's.
+ */
+export type NotionUntieredWakeMessage = Omit<NotionWakeMessage, "trust">;
+export interface NotionSupervisorWakeInput {
+    /** direct (guaranteed) or channel-watch (judged) — `drop` never reaches here. */
+    readonly addressing: Exclude<NotionAddressing, "drop">;
+    readonly pageId: string;
+    readonly discussionId: string;
+    readonly trigger: NotionWakeMessage;
+    /** The OTHER comments in the same discussion, oldest-first — envelope backscroll siblings.
+     *  Re-sent every wake (cheap at Notion volume) so the judge always has full thread context,
+     *  even mid-session (design §3.2). Ignored on the `direct` path (renderWake returns the body
+     *  verbatim there). */
+    readonly threadComments?: readonly NotionWakeMessage[];
+    /** The OUTGOING generation's recorded TAIL (OPE-794) — rendered BEFORE this wake's own thread
+     *  comments, so the envelope reads oldest-first across the rotation boundary. Only a FRESH
+     *  generation's first wake carries one. */
+    readonly tail?: readonly WakeMessageInput[];
+    /** This surface could not read its own page discussion since the seat's last wake (core
+     *  channels/seat-catch-up.ts). Rendered as a trusted `<system-note>`; unset ⇒ no note. */
+    readonly catchUpUnavailable?: string;
+    /** Engagement calibration for the judged preamble (memory/domain.ts engagementTierFor —
+     *  resolved by the caller; this core stays config-free). Unset ⇒ neutral ⇒ byte-identical. */
+    readonly engagementTier?: WakeEngagementTier;
+    /** Host-minted wake id (rendered `<wake wake-id=…>`) — SINGLE-WINDOW path only (channels/
+     *  unified-window.ts): the id the model echoes to `reply` so the host resolves this wake's
+     *  origin from the map. Unset ⇒ byte-identical (no attribute) — mirrors
+     *  GitHubSupervisorWakeInput.wakeId. */
+    readonly wakeId?: string;
+    /** SINGLE-WINDOW addressed @mention (mirrors GitHubSupervisorWakeInput.directMention): render
+     *  the wake as `direct-mention` — the full judged ENVELOPE (so the `wake-id` survives for the
+     *  reply tool, the ONLY reply route on the unified channel) with the ADDRESSED preamble instead
+     *  of the silence-biased watch one. Only meaningful alongside `addressing: "direct"` (the plan
+     *  only sets it for a real @mention); unset ⇒ today's render, byte-identical — a plain `direct`
+     *  wake stays the verbatim body. */
+    readonly directMention?: boolean;
+    /**
+     * This page carries an ENGAGED registry row — the seam's `deliver` verdict — so a JUDGED wake
+     * states `follow-up="thread-engaged"`, the envelope's own words for "you are already in this
+     * conversation and `stand_down` is how you leave" (instructions/access.ts's standing block).
+     *
+     * 🔴 THE ROW ALREADY SAYS IT AND THE ENVELOPE DID NOT (OPE-1711). `notionWakeAddressing` promotes
+     * the `notion.dispatched` row to `thread-follow` off this same verdict, so the deployment knows the
+     * page is enrolled and tells its audit trail — while the seat reads bare ambient activity. Ship
+     * #197 measured the cost of that gap on LINEAR, whose seam has the identical shape: a standing
+     * session declined an engaged follow-up as `user_requested_silence` on a stop asked in an earlier
+     * conversation. The fix is OPE-1673's, made on Slack and ported to both ticket surfaces.
+     *
+     * Like Slack's it does NOT touch `addressing`: `channel-watch` stays the honest silence bar for a
+     * standing session, and enrolment is a different fact from that bar. Unset/false ⇒ no attribute.
+     */
+    readonly threadEngaged?: boolean;
+}
+/**
+ * Build the NormalizedWake for one doc-supervisor turn. platform "notion", containerNoun "doc",
+ * locus.channel = the page, locus.thread = the discussion, backscroll = the discussion's other
+ * comments as oldest-first envelope siblings, ending at the triggering comment. renderWake then
+ * emits the exact `{message, context}` shape every OE dispatch sends — the SAME renderer Slack
+ * uses, with NO platform branch. A `direct` wake carries no preamble/backscroll (the body is the
+ * driver, verbatim); a `channel-watch` wake gets the judged envelope + doc-noun preamble.
+ */
+export declare function buildNotionSupervisorWake(input: NotionSupervisorWakeInput): NormalizedWake;
+/** The live supervisor session pointer for a page, as the deps report it. `freshGeneration` is
+ *  true for a brand-new OR just-rotated generation — its first wake carries the carried tail. */
+export interface NotionSupervisorSession {
+    readonly token: string;
+    readonly generation: number;
+    readonly freshGeneration: boolean;
+    /** The OUTGOING generation's recorded tail, oldest-first — empty unless this is a fresh
+     *  generation's first wake (OPE-794). */
+    readonly tail: readonly WakeMessageInput[];
+    /** The session's PREVIOUS wake time (the stored lastWakeAt, read BEFORE touchSession advances it),
+     *  or null/absent when there is no prior delivered wake (a fresh/rotated generation). The cursor
+     *  the memory-delta push (deps.memoryDelta) diffs against; unset ⇒ no delta computed. */
+    readonly lastWakeAt?: string | null;
+}
+/** Deps for {@link handleNotionSupervisorDispatch} — mirror SupervisorRouteDeps (slack-events.ts),
+ *  injected so the core is unit-testable over a mock store + a capture `wake`. org is baked into
+ *  the live impl's closures (a deployment fact — notion.ts), so it never crosses this boundary. */
+export interface NotionSupervisorDeps {
+    /** Create-or-fetch the live supervisor session for this page's surfaceKey: mint generation 1 on
+     *  first sighting, rotate to generation+1 when {@link shouldRotate} says it aged out, else
+     *  return the current generation. */
+    readonly getOrCreateSession: (surfaceKey: string, pageId: string, atIso: string) => Promise<NotionSupervisorSession>;
+    /** Record one wake on the current generation (lastWakeAt/turnCount). Best-effort. */
+    readonly touchSession?: (surfaceKey: string, atIso: string) => Promise<void>;
+    /**
+     * THE SINCE-LAST-WAKE CATCH-UP, through the ONE shared path every surface takes
+     * (channels/seat-catch-up.ts `seatCatchUp`). Optional so older test doubles keep compiling
+     * (absent ⇒ no catch-up, the pre-OPE-1726 behaviour); fail-soft by construction.
+     */
+    readonly catchUp?: (req: SeatCatchUpRequest) => Promise<SeatCatchUpResult>;
+    /**
+     * THE §2.5 ENGAGEMENT MARK for an ADDRESSED wake (OPE-1501) — defaults to
+     * `channels/notion-engagement.ts`'s `markNotionEngaged`, which writes the live registry.
+     *
+     * 🔴 IT IS A DEP BECAUSE OF WHERE IT HAS TO RUN, not for testability alone. Notion is the one
+     * surface whose EXTERNAL-AUTHOR gate is not at the ingress: the webhook core dispatches, and the
+     * decision is made HERE, one step later. Marking at the ingress would let an author the operator
+     * excluded ENROL a page by naming the agent on it — no reply, but every later plain comment from
+     * anyone would then wake a turn — and would let that same suppressed name-drop CLEAR a
+     * stand-down, because `participating: true` lifts the `stopped` flag. So the mark sits below the
+     * suppression check, where the answer already exists, and this dep is how the webhook core's own
+     * test can drive it. Absent in a unit test ⇒ the live writer.
+     */
+    readonly markEngaged?: (d: NotionSupervisorDispatch) => Promise<void>;
+    /**
+     * Record this delivered wake onto the LIVE generation's TAIL ring (OPE-794). Injected because the
+     * entry has to be filed under an ORG and a registry key, and this core deliberately holds neither
+     * — the live wiring does. Absent (a unit test) ⇒ nothing is recorded and the dispatch is
+     * unchanged, which is the same posture `touchSession` takes.
+     */
+    readonly recordWake?: (entry: SessionTailWakeRow, token: string, surfaceKey: string) => Promise<void>;
+    /** Start/continue the supervisor session under its reserved token, posting the rendered wake.
+     *  `window` is present ONLY on the SINGLE-WINDOW path (the dispatch input carried it): the
+     *  wiring (notion.ts) then DIVERTS the wake through eve's cross-channel `receive` into the
+     *  synthetic `unified` channel instead of this channel's own send. Absent ⇒ byte-identical. */
+    readonly wake: (input: {
+        token: string;
+        auth: OpenEverywhereNotionAuth;
+        message: string;
+        context: readonly string[];
+        state: NotionSessionState;
+        window?: UnifiedWindowWake;
+    }) => Promise<void>;
+    /** Compute the "changed since your last wake" `<system-reminder>` PUSH (memory/wake-delta.ts):
+     *  given the session's previous wake time (`sinceIso`), this wake's time (`atIso`), and this
+     *  session's own key (`selfKey` = its continuation token, to exclude its own writes), return the
+     *  ready block or null. Injected so the pure dispatch stays testable; the live wiring (notion.ts)
+     *  sets it ONLY when armed (supervisor + unified org gate), so unset ⇒ byte-identical. */
+    readonly memoryDelta?: (sinceIso: string, atIso: string, selfKey?: string) => Promise<string | null>;
+    /** Clock seam (defaults to the real clock). */
+    readonly now?: () => string;
+}
+/** Everything notion-webhook hands the supervisor dispatch: the classification + the wake parts +
+ *  the identity/session facts. Built by the webhook core, consumed here. */
+export interface NotionSupervisorDispatch {
+    readonly surfaceKey: string;
+    /**
+     * The Notion channel credential this delivery runs under (OPE-467) — the integration whose
+     * secret verified the signature, else (dev hatch only) the page's domain binding. Selected ONCE, by the webhook core,
+     * and carried here so the route's own Notion calls (the spend gate's visible refusal comment)
+     * cannot re-derive a DIFFERENT one. Nothing in this module reads it; it exists so there is
+     * exactly one selection per delivery rather than two rules that agree by luck.
+     */
+    readonly credentialId: string;
+    /** direct | channel-watch — `drop` is filtered upstream (never dispatched). */
+    readonly addressing: Exclude<NotionAddressing, "drop">;
+    readonly pageId: string;
+    readonly discussionId: string;
+    readonly workspaceId: string | null;
+    readonly auth: OpenEverywhereNotionAuth;
+    readonly trigger: NotionWakeMessage;
+    readonly threadComments: readonly NotionWakeMessage[];
+    /** Engagement calibration tier for the judged preamble (resolved by the webhook core). */
+    readonly engagementTier?: WakeEngagementTier;
+    /**
+     * The EXTERNAL-PARTICIPANT POLICY for this page (OPE-507), RESOLVED BY THE CALLER — this core
+     * stays config-free, exactly as {@link NotionSupervisorDispatch.engagementTier} does. The live
+     * wiring (notion.ts) resolves it as `resolveExternalPolicy(externalPolicyOverrideFor(surfaceKey,
+     * domains))`, so the org default and the domain override are both applied before it arrives here.
+     *
+     * Unset ⇒ the ORG DEFAULT alone (`resolveExternalPolicy()`), which ships `taint` ⇒ byte-identical
+     * to before this field existed. Every pure/test caller therefore stays unchanged.
+     */
+    readonly externalPolicy?: ExternalPolicy;
+    /** UNIFIED cross-surface grain resolved by the route leg (supervisorGrainFor, fail-soft false) —
+     *  stamps the wake's platform address + P5 disclosure AND marks the session state `oeUnified`
+     *  (the message-tool-only gate's key in notion.ts). Unset ⇒ byte-identical per-doc path. */
+    readonly unified?: boolean;
+    /** SINGLE-WINDOW wake plumbing, minted by the route leg via {@link planNotionSingleWindow} when
+     *  the grain says `singleWindow` AND the page passed the privacy floor: the wakeId is rendered
+     *  into the envelope by this core; the whole object is passed through to deps.wake, whose
+     *  wiring registers the map entry and diverts into the unified channel. Unset ⇒ byte-identical. */
+    readonly window?: UnifiedWindowWake;
+    /**
+     * The ANCESTOR-TRUST verdict for this delivery's page (OPE-492), resolved ONCE by the webhook core
+     * and carried here for the ROUTE. Nothing in THIS module reads it. The route reads it twice:
+     *   • the AUDIT ROW records WHICH refusal happened (`database-boundary`, `hop-limit`, `cycle`,
+     *     `unresolvable`, `workspace-root`, `no-roots`) rather than only that the page was untrusted;
+     *   • the SINGLE-WINDOW PRIVACY FLOOR accepts `trusted: true` as an internal signal (OPE-540 —
+     *     notion.ts `notionSingleWindowPrivacyOk`), so the floor and the memory plane agree on one
+     *     page. The floor only READS this verdict; it never re-derives it, so it stays synchronous.
+     * The trust also travels on {@link NotionSupervisorDispatch.auth} as the `trust_root` attribute,
+     * which is what `bindNotion` binds.
+     *
+     * Unset on a caller that declares no roots — the resolver returns `no-roots` with no I/O, and the
+     * webhook core omits the field. Both readers must treat the absent field as NOT trusted.
+     */
+    readonly trust?: NotionDeliveryTrust;
+    /** SINGLE-WINDOW addressed @mention (the plan's window carries `addressing:"direct-mention"`):
+     *  render the wake as the addressed `direct-mention` variant (envelope kept, watch preamble
+     *  swapped for the addressed one). Unset ⇒ today's renders, byte-identical. */
+    readonly directMention?: boolean;
+    /**
+     * The §2.5 ENGAGEMENT SEAM is what admitted this delivery (OPE-1510): the page carries an
+     * engagement row, and this PLAIN comment is a follow-up on it. Resolved ONCE by the webhook core —
+     * the one place that reads the registry — and carried here for the ROUTE, exactly as {@link
+     * NotionSupervisorDispatch.trust} is.
+     *
+     * 🔴 IT DOES NOT CHANGE HOW THE WAKE IS JUDGED. `addressing` stays `channel-watch`, so the
+     * silence bar is untouched. The field has two readers, and both only STATE the enrolment:
+     *   • the route's `notion.dispatched` row says WHAT WOKE IT (`notionWakeAddressing`,
+     *     channels/notion-engagement.ts);
+     *   • the WAKE ENVELOPE says it to the seat as `follow-up="thread-engaged"` (OPE-1711 — it reaches
+     *     {@link NotionSupervisorWakeInput.threadEngaged}, whose 🔴 carries the measurement).
+     * One verdict feeds both, so the row and the envelope can never disagree. Unset ⇒ the row reports
+     * the classifier's own value and the envelope states no contract, byte-identical to before.
+     */
+    readonly engagedFollowUp?: boolean;
+    /**
+     * HOW THE OPERATOR'S OWN CONFIG HOLDS THIS PAGE (OPE-1510): `roster` — a domain lists the page by
+     * id; `container` — a domain reaches it by a CONTAINER entry, which is the whole workspace or
+     * a same-level page glob (memory/domain.ts); `none` — no domain holds it. Resolved
+     * ONCE by the webhook core, by the same `notionPageDomain` read its addressed door gates on
+     * (channels/notion-scope.ts), and carried here for the ROUTE exactly as {@link
+     * NotionSupervisorDispatch.engagedFollowUp} is.
+     *
+     * 🔴 NOTHING IN THIS MODULE READS IT. It only lets the route's `notion.dispatched` row record the
+     * DOMAIN ORIGIN beside what woke the delivery, so a name-drop admitted by a claim is
+     * distinguishable from one on a page an operator listed. Unset ⇒ the row reads `none`.
+     */
+    readonly domainVia?: NotionVia;
+}
+/**
+ * The dispatch AS THE WEBHOOK CORE BUILDS IT (OPE-596) — every field of {@link
+ * NotionSupervisorDispatch} except that its messages carry no author tier yet (see {@link
+ * NotionUntieredWakeMessage}). The route leg (notion.ts) stamps the tier on the trigger and on every
+ * sibling, and that stamp is what turns this into a {@link NotionSupervisorDispatch} the supervisor
+ * core will accept. The two types are what stop the stamp being an optional step.
+ */
+export interface NotionUntieredSupervisorDispatch extends Omit<NotionSupervisorDispatch, "trigger" | "threadComments"> {
+    readonly trigger: NotionUntieredWakeMessage;
+    readonly threadComments: readonly NotionUntieredWakeMessage[];
+}
+/**
+ * THE INGESTED SET for one Notion wake, graded for the non-member taint join (OPE-466 / OPE-516).
+ *
+ * 🔴 NOTION HAD NO AUTHOR LEG AT ALL BEFORE OPE-516, and it could not have had one. The join's
+ * `refuted` field is the SURFACE's positive refutation — Slack's `is_restricted`, Teams' Entra
+ * `userType: "guest"` — and Notion publishes NO membership fact about a comment author. So the
+ * question is answered from the operator's own AUTHOR-TRUST REGISTER instead
+ * (identity/author-trust.ts): on a workspace the operator has armed, an author they did not declare
+ * grades `external`. On an unarmed workspace the leg contributes nothing and this is a no-op.
+ *
+ * `refuted` is deliberately never set here. Leaving it absent is the honest statement — Notion has
+ * no verdict to give, and a hardcoded `false` would read as "we asked and it was fine".
+ *
+ * NOTION HAS NO GROUP CONCEPT, so no memberships are contributed and a Notion declaration is
+ * principal-keys-only. That is a platform fact, not a gap in this function.
+ *
+ * A `self` author (the bot's own prior comment) carries no `authorId` from the webhook core, and its
+ * resolved tier is the machine floor, so it can never reach the register leg — the join requires a
+ * positively-human tier.
+ *
+ * Pure and exported so the grading is testable without a store or a live wake.
+ */
+export declare function notionIngestedMessages(d: {
+    readonly workspaceId: string | null;
+    readonly trigger: NotionWakeMessage;
+    readonly threadComments: readonly NotionWakeMessage[];
+}): readonly IngestedChatMessage[];
+/**
+ * THE EXTERNAL-AUTHOR DECISION for one Notion dispatch (OPE-507). Pure, exported so the three
+ * behaviours are testable without a store or a live wake.
+ *
+ * Notion's three answers, and why they are what they are:
+ *   • the TRIGGER's author is excluded ⇒ NO WAKE AT ALL (`suppressed`). That covers behaviour 2
+ *     (ambient never triggers on their comment) and behaviour 1 (their @mention is not acted on).
+ *   • a SIBLING's author is excluded ⇒ the wake proceeds and that sibling's body is WITHHELD
+ *     (behaviour 3): a permitted member's later comment still wakes the agent, and the excluded
+ *     author's earlier comment reaches the model as the arrived-marker.
+ *   • nothing is excluded, or the policy is `taint` ⇒ `withheldIds` is empty and every caller path
+ *     is byte-identical to before this existed.
+ *
+ * 🔴 NOTION POSTS NO PRIVATE NOTICE, AND THAT IS DELIBERATE. Behaviour 1 owes the excluded sender a
+ * PRIVATE notice, and Notion has no private channel back to a commenter — a comment reply lands in
+ * the shared discussion, where everyone reading the doc sees it. Announcing "I will not act on your
+ * message" into a shared doc is a disclosure, not a notice, so the Notion answer is to do nothing.
+ * The surfaces that HAVE a private channel (a Discord DM, a Slack DM) post the notice there.
+ */
+export declare function notionExternalAuthorDecision(d: {
+    readonly trigger: NotionWakeMessage;
+    readonly threadComments: readonly NotionWakeMessage[];
+    readonly ingested: readonly IngestedChatMessage[];
+    readonly policy: ExternalPolicy;
+}): {
+    readonly suppressed: boolean;
+    readonly withheldIds: ReadonlySet<string>;
+};
+export declare function handleNotionSupervisorDispatch(d: NotionSupervisorDispatch, deps: NotionSupervisorDeps): Promise<void>;
+export { shouldRotate };
+//# sourceMappingURL=notion-supervisor.d.ts.map

package/dist/agent/channels/notion-supervisor.d.ts.map

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