@open-everywhere/provider-notion 0.1.0

package/agent/provider-events.ts

@@ -0,0 +1,198 @@
+// NOTION's event inventory (OPE-1612). See the core module's header
+// (packages/core/agent/routines/provider-events.ts) for what the three routing states mean.
+//
+// NOTION PARTITIONS BY PREFIX, NOT BY EVENT. `notionEventClass`
+// (channels/notion-event-normalizer.ts) reads the type's prefix: `page.` / `database.` /
+// `data_source.` are STRUCTURAL and routable, `comment.` is CONVERSATION and the ambient
+// supervisor's, anything else is unrecognised. `liftNotionEvent` returns null for everything that is
+// not structural, so every `comment.` row below is honestly `routing: "none"` — nothing routes it,
+// even though the bundle does register a normalizer.
+//
+// THE MAPPING IS THE ENVELOPE'S, NOT THE TYPE'S. `notionScopePath` reads `workspace_id`, the
+// `parent` object and the `entity` object, and every structural delivery carries the same three. So
+// each structural row below records the same mapping; what differs between them is what the event
+// MEANS, which is what the note carries. The `sub` step is the exception and it is conditional:
+// `page.content_updated` names an ARRAY of updated blocks and the path takes one only when the array
+// holds exactly one, because the path holds at most one step per kind.
+//
+// 🔴 THE PARENT-TYPE SET IS THE NORMALIZER'S REVIEWED LIST, NOT THE VENDOR'S PUBLISHED ONE. Notion's
+// event reference shows a `parent` object in each sample payload but never enumerates the types it
+// can take, so `notionScopePath`'s list — `space` → `group`, and `database` / `data_source` / `page`
+// / `block` → `container` — is a decision somebody made, and this file records the same set. A
+// `space` parent is reachable for EVERY structural family, so every structural row below lists
+// `group` beside `container`: the two are alternatives on one delivery (a parent is one thing), and
+// listing both is what tells a reader that a teamspace-level narrowing is available at all.
+//
+// The `database.` family is the vendor's older spelling. Notion's 2025-09-03 API version deprecates
+// several of those in favour of the `data_source.` equivalents; both are still delivered and both
+// route identically here, so both are listed.
+
+import type { ProviderEventDeclaration } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const NOTION_PROVIDER_EVENTS: ProviderEventDeclaration = {
+  source: "notion",
+  doc: "https://developers.notion.com/reference/webhooks-events-delivery",
+  events: [
+    {
+      event: "page.created",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was added; the container step is its parent database, data source or page",
+    },
+    {
+      event: "page.properties_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page's property values changed — a status field moving is this event, not a content edit",
+    },
+    {
+      event: "page.content_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity", "sub"],
+      note: "a page's blocks changed; the sub step is the block, and only when the delivery names exactly one",
+    },
+    {
+      event: "page.moved",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was moved to a different parent; the container step is the NEW parent",
+    },
+    {
+      event: "page.deleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was sent to trash — the terminal event a scope path can carry and a fetch cannot",
+    },
+    {
+      event: "page.undeleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was restored from trash",
+    },
+    {
+      event: "page.locked",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was locked against edits",
+    },
+    {
+      event: "page.unlocked",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a page was unlocked",
+    },
+    {
+      event: "database.created",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a database was added; the group step is the teamspace, when the parent is one",
+    },
+    {
+      event: "database.content_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "rows were added to or removed from a database",
+    },
+    {
+      event: "database.schema_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a database's property schema changed — the event that breaks a routine reading a column by name",
+    },
+    {
+      event: "database.moved",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a database was moved to a different parent",
+    },
+    {
+      event: "database.deleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a database was sent to trash",
+    },
+    {
+      event: "database.undeleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a database was restored from trash",
+    },
+    {
+      event: "data_source.created",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "the 2025-09-03 spelling of a database creation, delivered beside the older `database.` family",
+    },
+    {
+      event: "data_source.content_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "rows were added to or removed from a data source",
+    },
+    {
+      event: "data_source.schema_updated",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a data source's property schema changed",
+    },
+    {
+      event: "data_source.moved",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a data source was moved to a different parent",
+    },
+    {
+      event: "data_source.deleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a data source was sent to trash",
+    },
+    {
+      event: "data_source.undeleted",
+      routing: "mapped",
+      match: ["parent", "entity"],
+      scope: ["group", "container", "entity"],
+      note: "a data source was restored from trash",
+    },
+    {
+      event: "comment.created",
+      routing: "none",
+      match: [],
+      scope: [],
+      note: "a comment was added; declined by the normalizer on purpose — a comment is CONVERSATION and the ambient supervisor answers it, so routing it would wake a seat twice for one event",
+    },
+    {
+      event: "comment.updated",
+      routing: "none",
+      match: [],
+      scope: [],
+      note: "a comment was edited; declined with the whole `comment.` family",
+    },
+    {
+      event: "comment.deleted",
+      routing: "none",
+      match: [],
+      scope: [],
+      note: "a comment was removed; declined with the whole `comment.` family",
+    },
+  ],
+};

package/agent/register.ts

@@ -0,0 +1,144 @@
+// registerNotionProvider — the ONE boot entry of @open-everywhere/provider-notion. The app's
+// adapter-wiring module (agent/lib/register-adapters.ts) imports this STATICALLY and calls it once
+// at boot; every seam the notion bundle implements registers here and nowhere else. Static imports
+// only: eve bundles the agent definition and its whole import graph into one rolldown chunk — a
+// literal dynamic import() code-splits and trips eve's "expected one authored module" invariant.
+//
+// What notion registers (and what it deliberately does NOT):
+//   • identity mapper        — bindNotion (chat-surface plane; channels/notion-identity.ts)
+//   • capability manifest    — midTurnPost wired via createCommentReply; no reaction primitive
+//   • post arm               — notionPostArm (mid-turn reply + unified reply + edit + redrive helpers)
+//   • wake-origin codec      — the stored-data notion arm (channels/notion-origin-codec.ts)
+//   • webhook verifier       — Notion's `x-notion-signature` scheme (channels/notion-webhook-verifier.ts)
+//   • event normalizer +     — the routing plane's two halves, STRUCTURAL events only; comments stay
+//     event scope grant        with the ambient supervisor (channels/notion-event-normalizer.ts)
+//   • subtree platform       — Notion honours `Surface.subtree`, and registerNotionTrustRoots is
+//                              what core hands the declared keys to (channels/notion-ancestry-trust.ts)
+//   • memory provider        — the read-only Notion page-subtree backing (memory/memory.ts)
+//   • read adapter           — notionReadAdapter (channels/notion-read.ts, OPE-988): THREAD-FIRST —
+//                              read_thread = one discussion (the default view), read_channel = the
+//                              page's discussions, each headed by its anchor. Page CONTENT is not on
+//                              the chat plane; the comment layer is Notion's chat surface.
+//   • ancillary message ops  — notionMessageOps (channels/notion-message-ops.ts, OPE-1043/OPE-1047):
+//                              postText/editMessage — the transport the stop acknowledgement
+//                              (OPE-989's control) and the approval-decision notice now have on
+//                              Notion. postFiles uploads through Notion's two-step file-upload API
+//                              (notion-api.ts's uploadNotionFile) and attaches the results to a page
+//                              comment. NO setReaction (no reaction primitive, below).
+//   • NO reaction surface    — Notion has no integration reaction primitive
+//   • NO grant plane arm     — personal lending BORROWS the owner's MCP tools (OPE-1136). Core
+//                              drives that path itself through the connector's own MCP connection
+//                              (connections/grant-mcp-borrow.ts); a provider bundle registers
+//                              nothing for it. The REST arm this file once carried — a verb
+//                              registry plus a `GrantTransport` spending a second REST-family
+//                              token — is deleted.
+
+import {
+  registerIdentityMapper,
+  registerCapabilityManifest,
+  registerSurfaceParity,
+  registerProviderEvents,
+  registerPostArm,
+  registerWakeOriginCodec,
+  registerReadAdapter,
+  registerSeatCatchUp,
+  registerProviderDocs,
+  registerWebhookVerifier,
+  registerEventNormalizer,
+  registerEventScopeGrant,
+  registerSubtreePlatform,
+  registerSurfaceMessageOps,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { registerNotionTrustRoots } from "./channels/notion-ancestry-trust.js";
+import { PROVIDER_DOCS } from "./docs-generated.js";
+import { NOTION_SURFACE_PARITY } from "./surface-parity.js";
+import { NOTION_PROVIDER_EVENTS } from "./provider-events.js";
+import { bindNotion } from "./channels/notion-identity.js";
+import { notionPostArm } from "./channels/notion-post-arm.js";
+import { notionMessageOps } from "./channels/notion-message-ops.js";
+import { notionWakeOriginCodec } from "./channels/notion-origin-codec.js";
+import { notionReadAdapter } from "./channels/notion-read.js";
+import { notionSeatCatchUpFetch, NOTION_TIMESTAMP_PRECISION_MS } from "./channels/notion-catch-up.js";
+import { registerNotionWorkSearch } from "./channels/notion-work-search.js";
+import { notionWebhookVerifier } from "./channels/notion-webhook-verifier.js";
+import { notionEventNormalizer, notionEventScopeGrant } from "./channels/notion-event-normalizer.js";
+import { registerNotionMemory } from "./memory/memory.js";
+
+/** Perform ALL of the notion bundle's registrations. Idempotent (each register call replaces);
+ *  cheap and side-effect-free beyond the registry writes (the memory provider's token resolves
+ *  lazily through the credential broker only when a notion silo is actually read). */
+export function registerNotionProvider(): void {
+  registerIdentityMapper("notion", bindNotion);
+  // Comment surface: mid-turn post wired via createCommentReply (the post arm's dispatchReply
+  // posts a new comment into the triggering discussion). No integration reaction primitive.
+  // closingProseDropped (OPE-811, widened by OPE-2006): a per-doc container-supervisor turn runs the
+  // message-tool-only gate live — it did already on a windowed domain, and now on every domain — so
+  // its turn-final text is dropped and `reply` is the only route out.
+  // 🔴 THE SURFACE-WIDE FACT NEEDS SURFACE-WIDE EVIDENCE, and here it is: `channels/notion.ts`'s
+  // `message.completed` is this bundle's ONLY completion handler, it routes EVERY Notion session
+  // through the shared `completeSupervisorTurn` arm whatever the session's shape, and it never
+  // delegates to the agent framework's default poster. So no Notion seat of any shape posts its
+  // closing prose — which is the bar `identity/capabilities.ts` sets for declaring this fact, and
+  // the bar Linear fails.
+  registerCapabilityManifest("notion", { midTurnPost: true, reactions: false, closingProseDropped: true });
+  // The OPE-1499 parity ledger: every capability the chat-surface contract names, answered
+  // `supported` or `{ unsupported: "<reason>" }`. Gates nothing at runtime — `lint:surface-parity`
+  // reds on an unanswered row, and the contract's §7.1/§7.1.1/§7.2 tables are generated from it.
+  registerSurfaceParity("notion", NOTION_SURFACE_PARITY);
+  // The OPE-1612 event inventory: every vendor event that could wake a routine, and how far the
+  // normalizer plane carries each one. Gates nothing at runtime — `lint:provider-events` reds a
+  // bundle that declares none or that promises a match key the normalizer does not declare, and
+  // the manual's inventory table is generated from it.
+  registerProviderEvents("notion", NOTION_PROVIDER_EVENTS);
+  registerPostArm(notionPostArm);
+  // Ancillary message ops (OPE-1043): postText/editMessage, so the stop acknowledgement
+  // (hooks/turn-anchor.ts's postSurfaceText) and the approval-decision notice have a transport on
+  // Notion. postFiles (OPE-1047) uploads via Notion's file-upload API. No setReaction (no
+  // reaction primitive — see below).
+  registerSurfaceMessageOps(notionMessageOps);
+  registerWakeOriginCodec("notion", notionWakeOriginCodec);
+  // Generic chat READ plane (OPE-988): read_channel / read_thread over the page's comment layer.
+  // Without this the two verbs still MOUNTED on a unified window and refused at execute time
+  // ("reading a notion channel is not supported yet") — the OPE-927 mount-honesty class.
+  registerReadAdapter(notionReadAdapter);
+  // THE SEAT CATCH-UP FETCH (OPE-1726): the comments this page discussion collected since the
+  // seat's last wake. Core's shared path applies the bounds, the admission policy and the cap.
+  // The surface DECLARES the unit its own message stamps carry, and core widens both catch-up
+  // bounds by it (OPE-1847). A wrong or missing unit bounds the seat out of its own window.
+  registerSeatCatchUp("notion", notionSeatCatchUpFetch, { timestampPrecisionMs: NOTION_TIMESTAMP_PRECISION_MS });
+  // Work-plane federated SEARCH (OPE-961): the ONE `search` tool's Notion half. Grant-gated like
+  // notion_search.ts, and now registered here too so the federator can find it.
+  registerNotionWorkSearch();
+  // Webhook-verifier plane (OPE-164): Notion's `x-notion-signature` scheme, so a GENERIC hook can
+  // declare `source: "notion"` and be verified the way Notion signs. Changes no existing route.
+  registerWebhookVerifier(notionWebhookVerifier);
+  // ⚠️ NO PROVISIONING DECLARATION, AND THAT IS NOT AN OMISSION (OPE-207). Notion's signing key is
+  // its own `verification_token`, which arrives once in an unauthenticated setup POST — so it can
+  // never be a key WE mint, and `notionWebhookVerifier`'s `keyOrigin: "vendor-issued"` is what keeps
+  // `source: "notion"` out of the chat-creatable vocabulary. A declaration + setup exchange for that
+  // arm shipped and was deleted: nothing could put a hook into the status the arm required, so it was
+  // reachable by no route. A Notion hook is a CONFIG hook (its secret arrives through
+  // `webhooks/handshake-capture.ts` on the provider's own front door) until that changes.
+  // Event plane (OPE-189) — the FIRST bundle-resident normalizer + scope grant in the tree. Both
+  // registered on ADJACENT lines on purpose: `checkEventReadGrant` fail-closes to
+  // `no-grant-adapter` when a grant is missing, so a normalizer registered ALONE would produce a
+  // source where every match is skipped with an audited refusal and nothing says why.
+  // The normalizer routes `page.*`/`database.*`/`data_source.*` (work) and returns null for
+  // `comment.*` (conversation — the ambient supervisor's, above); see notion-event-normalizer.ts.
+  registerEventNormalizer(notionEventNormalizer);
+  registerEventScopeGrant(notionEventScopeGrant);
+  // Subtree-trust plane (OPE-539): Notion is the one platform whose surface key carries no
+  // hierarchy — a page id names a page that can hold pages — so it is the one platform that honours
+  // `defineSurface({ …, subtree: true })`. Core carries the claim and hands the keys here; this
+  // module walks the parent chain at ingestion. Declaring the capability is also what makes the same
+  // word on slack/github/teams a BOOT ERROR instead of a line that grants nothing.
+  registerSubtreePlatform("notion", registerNotionTrustRoots);
+  // Memory plane: a read-only silo with provider:"notion", container:"<root-page-id>" resolves to
+  // that Notion page + all its child pages, pulled recursively (docs/capabilities/memory.md). The
+  // integration token resolves LAZILY through the credential broker (default ref NOTION_TOKEN).
+  registerNotionMemory();
+  // Shipped-manual plane (OPE-138): this bundle's own setup runbook (docs/deploy/surfaces/notion.md,
+  // compiled into ./docs-generated.ts because docs/ is not on disk at runtime). De-select the bundle
+  // and the module leaves the import graph; registerProviderDocs re-checks the selection gate anyway.
+  registerProviderDocs("notion", PROVIDER_DOCS);
+}

package/agent/schedules/notion-ingress.ts

@@ -0,0 +1,20 @@
+// Recovery clock for authenticated Notion deliveries. The public route nudges the same drain
+// immediately, but this minute tick is the durable guarantee after a process dies between commit
+// and that nudge. It sends row keys only; the private route atomically claims and loads payload.
+
+import { defineSchedule } from "eve/schedules";
+import { deploymentOrg, getOperationalStore } from "@open-everywhere/core/agent/adapter-api.js";
+
+import { recoverNotionIngress } from "../channels/notion-ingress-drain.js";
+
+export default defineSchedule({
+  cron: "* * * * *",
+  async run() {
+    const result = await recoverNotionIngress(deploymentOrg(), getOperationalStore());
+    if (result.due > 0) {
+      console.log(
+        `[open-everywhere:notion] ingress recovery: ${result.due} due -> ${result.posted} posted, ${result.failed} failed`,
+      );
+    }
+  },
+});

package/agent/surface-parity.ts

@@ -0,0 +1,105 @@
+// NOTION's surface-parity declaration (OPE-1499). See the core module's header
+// (packages/core/agent/identity/surface-parity.ts) for what the three cell shapes mean.
+//
+// Notion is THREAD-FIRST and the inverse of Slack: a comment carries `discussion_id` from birth, a
+// new top-level comment MINTS a discussion, and there is no bare-channel state at all (§4.6.1). It
+// is also the one surface with no @mention of an integration, so its addressed leg keys on a
+// name-drop or structured mention instead — which is why those two rows read the way they do.
+
+import type { SurfaceParityDeclaration } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const NOTION_SURFACE_PARITY: SurfaceParityDeclaration = {
+  // --- registration seams (§7.1) ---------------------------------------------------------------
+  "identity-mapper": "supported",
+  "capability-manifest": "supported",
+  "post-arm": "supported",
+  "wake-origin-codec": "supported",
+  "unified-action-plane": {
+    unsupported:
+      "a Notion discussion comment is rich text with no component plane — the API offers no tappable button an integration may render into one, so there is nothing for a tap route to receive. The bridged approval posts as prose, which the question bridge already renders complete",
+  },
+  "origin-placement-carry": {
+    unsupported:
+      "the placement is INSIDE the conversation identity: a reply targets `discussionId`, which is exactly what `threadRef` keys on, so two origins that pass the conversation test name the same discussion and cannot disagree about placement",
+  },
+  "read-adapter": "supported",
+  // 🔴 PERMANENT, and confirmed in BOTH directions (OPE-1502, developers.notion.com read
+  // 2026-09-07). The webhook catalogue carries page, database, data-source and comment events and
+  // no reaction event of any kind; the comment object carries `rich_text`, `attachments` and
+  // `display_name` and no reactions field. So there is nothing to receive and nothing to poll —
+  // unlike GitHub, where the absent webhook still leaves a REST route to read.
+  "reaction-feedback-ingest": { unsupported: "vendor limit — Notion pushes no reaction event and its comment object exposes no reaction resource, so there is nothing to receive and nothing to poll" },
+  "ancillary-ops": "supported",
+  "ambient-engagement-seam": "supported",
+  // `notionWakeAddressing` (channels/notion-engagement.ts) carries the seam's own `deliver` verdict
+  // to the `notion.dispatched` row, so an engaged follow-up reads `thread-follow` and ambient page
+  // chatter still reads `channel-watch`. The row also carries `via`, which names the DOMAIN ORIGIN
+  // the addressed door gated on — that field is Notion's alone (OPE-1510).
+  "engaged-row-promotion": "supported",
+  // Notion is thread-first: every wake arrives scoped to one discussion, so every wake this surface
+  // diverts is thread-scoped and consults ownership.
+  "owned-thread-ingress": "supported",
+
+  // --- wake legs and conversation shapes -------------------------------------------------------
+  // Notion lets no user @mention an internal integration, so the old mention gate was structurally
+  // dead (channels/notion-webhook.ts). A `direct` Notion wake is an ADDRESSED, single-author
+  // comment recognised by a name-drop or structured mention — the leg exists, by another route.
+  "addressed-leg": { supported: "the `direct` wake — a name-drop or structured mention, not a platform @mention" },
+  // The ambient supervisor, a different mechanism from the §2.5 registry: the domain opt-in decides
+  // whether it runs, and the registry has never gated that. Since OPE-1501 the registry both
+  // SUPPRESSES it (a stood-down page) and OPENS it (an engaged page wakes without the opt-in).
+  "ambient-leg": { supported: "the ambient supervisor, not the §2.5 engagement registry" },
+  // `notion-catch-up.ts` re-reads the seat's own discussion (a single block's inline comments) over
+  // the same brokered credential `read_channel` uses, keeping what is newer than the seat's own
+  // `lastWakeAt`. Notion's comments endpoint takes no `since`, so the bound is applied on our side.
+  "seat-catch-up": "supported",
+  // The slot is EMPTY on this surface: `notion.ts` builds no `contextLines`, so there is no pour to
+  // police. The seat's room context is the catch-up read above, which core already admits.
+  "seat-context-admission": { unsupported: "the hydration fills no context-line slot — the seat's room context is the catch-up read, which core already admits" },
+  // A Notion comment carries no component plane — no button, no tap route. See the roster row for
+  // what that costs and where it does NOT cost anything.
+  "approval-card": { unsupported: "a page comment carries no component plane, so there is no button to render and no route for a tap. A governed act that takes the venue walk is redirected to a card-capable room in the SAME domain, or refused when the domain holds none. The paths OUTSIDE that walk do not: the spend checkpoint (spend/checkpoint.ts `requireSessionContinuation`) fails OPEN here and records the crossing in an audit row instead" },
+  // THE TRACE ARRIVES EVEN THOUGH THE BUTTON CANNOT (OPE-1854). A judge-lifted act posts its
+  // notice here as a plain page comment through the shared road (`postJudgeLiftNotice`), on this
+  // surface's own `SurfaceMessageOps` transport. It carries the overrule as an INSTRUCTION in
+  // words, with the action id a reviewer finds the act by, because no tap can land here.
+  // 🔴 BARE, NOT `{ supported: "…" }`. A noted cell is exempt from the overclaim arm, and the
+  // arm is the point: drop this bundle's text transport and the notice silently stops arriving.
+  "judge-lift-notice": "supported",
+  "name-drop-mention": "supported",
+  // 🔴 STEP 4 OF THE WEBHOOK ADMITS ONE EVENT TYPE. `handleNotionDelivery` answers `ignored` for
+  // anything that is not `comment.created`, so `comment.updated` returns above the classifier, the
+  // ambient gate and the engagement seam alike.
+  "message-edit-wake": { unsupported: "the webhook admits `comment.created` only — `comment.updated` answers `ignored` at step 4" },
+  // ONE discussion. A Notion wake always arrives thread-scoped (§4.6.1).
+  threads: { supported: "thread-first — every wake arrives scoped to one discussion" },
+  // A STANDING room, not §4.5's read_channel container — Notion has the latter (the page's
+  // discussions) and `read_channel` is supported below. A discussion is minted by its first comment
+  // and is anchored to one block, so nothing on this surface predates the conversation in it.
+  rooms: { unsupported: "no standing container — a discussion is minted by its first comment and anchored to one block" },
+  dm: { unsupported: "no DM plane — Notion carries no person-to-person message channel" },
+  mpim: { unsupported: "no DM plane — Notion carries no person-to-person message channel" },
+
+  // --- core verbs (§7.2) -----------------------------------------------------------------------
+  reply: "supported",
+  edit_reply: "supported",
+  react: { unsupported: "vendor limit — the Notion comment API exposes no reaction write" },
+  no_reply: "supported",
+  read_channel: "supported",
+  read_thread: "supported",
+  search: "supported",
+  // Unbuilt, not impossible — see OPE-1507. The transport is registered; the missing piece is the
+  // `channel` row in `access/resource-grant.ts`'s closed `RESOURCE_TYPES` table.
+  post_message: { unsupported: "not built yet — no `channel` row in `access/resource-grant.ts` — OPE-1507" },
+  dm_person: { unsupported: "no DM plane — Notion carries no person-to-person message channel (§4.7.2)" },
+  set_dm_delivery: { unsupported: "no DM plane — the verb mounts only inside a 1:1 DM (§4.7.2)" },
+  // The direction matters: a human's stop needs an INBOUND reaction event, and Notion's webhook
+  // catalogue carries none (notion-stop.ts's banner is the vendor evidence). Whether OE can WRITE a
+  // reaction is a different limit, and it is the one the two rows below name.
+  stop: { supported: "a comment whose entire body is `stop` — Notion pushes no reaction webhook" },
+  ack_stop_glyph: { unsupported: "vendor limit — the Notion comment API exposes no reaction write, so there is no glyph to place" },
+  ack_cancel_note: "supported",
+  stand_down: { supported: "marks the page row; refuses when no row exists" },
+  // OPE-1047. Notion accepts at most three files per comment — its own vendor cap.
+  post_file: { supported: "at most 3 files per post — a Notion comment's own vendor cap" },
+};

package/agent/tools/notion_search.ts

@@ -0,0 +1,110 @@
+// THE WORK-PLANE SEARCH (OPE-913) — Notion's own cross-container read, under a domain work grant.
+//
+// WHY IT IS WORK AND NOT CHAT (OPE-928's container line): a read INSIDE the wake container is chat —
+// the envelope already renders it. A read ACROSS containers is work: it reaches pages nobody in this
+// conversation named, which is an exfiltration surface, so it lives behind the domain's work grant
+// and runs on the work credential.
+//
+// MOUNT: the domain's work grant, and nothing else. No grant ⇒ the tool is ABSENT, not refusing.
+// That is the OPE-927 class closed structurally: a worker that never mounts this cannot tell a
+// member it "searched Notion and found nothing".
+//
+// 🔴 NO RESULT FILTER, EVER. Tommy ruled on 2026-08-21 that search's reach IS the credential's
+// reach: "OE never filters search results as a boundary (a post-hoc filter is not enforcement)."
+// Notion enforces the boundary for real — an internal integration sees only the page trees a human
+// shared with it — so an organisation narrows search by sharing a narrow integration, and OE ships
+// the legible seam rather than a filter that would look like one. If you are about to add a
+// domain-scoped filter here, read that ruling first.
+//
+// WHAT COMES BACK: ids and titles. No page body ever crosses this tool, so the model has to take the
+// second, FENCED step (read_notion_page, which admits only pages the caller's own domain owns) to
+// read anything. Search widens what the agent can FIND; it does not widen what it can READ.
+//
+// Output is wrapped untrusted: a page title is written by arbitrary workspace members, so the model
+// must treat it as DATA, not instructions.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { resolveNotionCredential, searchNotion } from "../channels/notion-api.js";
+import { notionWorkGrant, notionWorkMount } from "../channels/notion-work.js";
+import { assertNotionActingIdentity } from "../channels/notion-acting-identity.js";
+import {
+  ingestUntrustedModelOutput,
+  getConfig,
+  preRegisterDynamicEntry,
+  type BindableContext,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+const MAX_RESULTS = 25;
+
+// FACTORED (see read_notion_page.ts's REPLAY DOCTRINE note): a top-level defineTool const, never an
+// inline literal in the handler. Exported so the work-grant test can drive execute() and prove the
+// grant is actually WIRED here — a mount gate the handler forgets to honour is worth nothing.
+export const notionSearchEntry = defineTool({
+  description:
+    "Search this domain's Notion workspace by title and text, and get back page ids + titles. " +
+    "Use it to FIND the page you need — a spec, a runbook, a notes page — then read it with " +
+    "read_notion_page. It returns no page content, so a result is a pointer, not an answer.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("Words to search for in page titles and text."),
+    limit: z.number().int().min(1).max(MAX_RESULTS).optional().describe(`How many results to return (default 10, max ${MAX_RESULTS}).`),
+    kind: z.enum(["page", "database"]).optional().describe("Restrict results to pages or to databases. Omit for both."),
+  }),
+  outputSchema: z.object({
+    query: z.string(),
+    hits: z.array(z.object({ id: z.string(), object: z.string(), title: z.string(), url: z.string().optional() })),
+  }),
+  // NO `approval:` — a dynamic-tool approval fn only registers at session.started resolve time, so a
+  // resumed session's replay lookup fails and eve kills the turn (the pin read_notion_page carries).
+  // Read-only, so absent approval === never() is correct.
+  async execute(input, ctx) {
+    const domains = getConfig().loadDomains();
+    // THE GRANT IS RE-CHECKED IN EXECUTE, not trusted from the mount. A session resolves its tools
+    // once at session.started and can then run for hours; the config it mounted under is a
+    // deployment away from changing. Re-reading it here costs one pure lookup and means a revoked
+    // grant stops working on the next call rather than on the next rotation.
+    const grant = notionWorkGrant(ctx as BindableContext, domains);
+    if (!grant) {
+      throw new Error(
+        "This domain holds no Notion work grant, so Notion search is unavailable here. " +
+          "An operator grants it by declaring the domain's Notion work credential in agent/memory/config/domains.ts.",
+      );
+    }
+    // 🔴 OPE-1525 — THE OWN-ACCOUNT GATE, on the line below's behalf. `grant.credential` is a TEAM
+    // key by construction (channels/notion-work.ts NOTION_WORK_CREDENTIAL), so a member who asked to
+    // act with THEIR OWN Notion account has no answer here. The gate refuses that turn and writes the
+    // `connector.acting_identity` row either way — see channels/notion-acting-identity.ts.
+    await assertNotionActingIdentity(ctx as BindableContext, "notion_search");
+    const cred = await resolveNotionCredential(grant.credential);
+    if (!cred) throw new Error(`no value stored for this domain's Notion work credential "${grant.credential}" — cannot search.`);
+    const hits = await searchNotion(input.query, {
+      ...cred,
+      pageSize: input.limit ?? 10,
+      ...(input.kind ? { filter: input.kind } : {}),
+    });
+    return { query: input.query, hits: hits.slice(0, input.limit ?? 10).map((h) => ({ ...h })) };
+  },
+  toModelOutput(output) {
+    const body =
+      output.hits.length === 0
+        ? `Notion search for "${output.query}" matched nothing the work integration can see.`
+        : `Notion search for "${output.query}" — ${output.hits.length} result(s):\n` +
+          output.hits.map((h) => `- ${h.object} ${h.id}: ${h.title || "(untitled)"}`).join("\n");
+    return ingestUntrustedModelOutput(body, {
+      source: "notion search",
+      ingestion: { kind: "notion", label: "notion_search" },
+    });
+  },
+});
+preRegisterDynamicEntry("notion_search", "_single", notionSearchEntry);
+
+export default defineDynamic({
+  events: {
+    // session.started ONLY: a session's domain cannot change mid-session, so resolving the grant
+    // once is correct and cheaper (the same reasoning read_notion_page's resolver carries).
+    "session.started": (_event, ctx) => {
+      if (!notionWorkMount(ctx as BindableContext, () => getConfig().loadDomains())) return null; // no work grant ⇒ absent
+      return notionSearchEntry;
+    },
+  },
+});