@open-everywhere/core 0.1.0

package/agent/tools/update_status.ts

@@ -0,0 +1,65 @@
+// update_status records what the agent is currently doing as ONE line, keyed by this session, in the surface-tier STATUS.md that every thread in the surface shares and the channel mirrors to a pinned message.
+// Not consequential, so no approval. Thread-root status emoji are the channel's own job; this is the higher-level "what's in flight" view.
+
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { resolvePartition } from "../memory/partition.js";
+import { SURFACE } from "../memory/store.js";
+import { surfaceProvider } from "../memory/resolve.js";
+import { bindFrom, currentTurnId } from "../identity/binding.js";
+import { writeMemoryTier } from "../memory/write-road.js";
+import { writeTierFile } from "../memory/sandbox-sync.js";
+import { withMemoryRootWritable } from "../memory/root-fence.js";
+import { statusItemLine, upsertStatusItem, statusSeed, type WorkState } from "../status/status.js";
+
+export default defineTool({
+  description:
+    "Record your current work status so the team can see it at a glance (it's mirrored to a pinned status message in the channel, shared across all threads). Call when you start a substantial task, when you finish, or when you're blocked / need input. One status per thread.",
+  inputSchema: z.object({
+    state: z
+      .enum(["working", "done", "needs_input", "blocked"])
+      .describe("working = in progress; done = finished; needs_input = waiting on a human; blocked = stuck."),
+    summary: z.string().min(1).describe("One short line: what you're doing / did / are blocked on."),
+  }),
+  outputSchema: z.object({ updated: z.boolean(), state: z.string() }),
+  approval: never(),
+  async execute(input, ctx) {
+    const p = resolvePartition(ctx);
+    const sessionId = ctx.session.id;
+    const when = new Date().toISOString().slice(0, 16).replace("T", " ") + "Z";
+    const line = statusItemLine(sessionId, input.state as WorkState, input.summary, when);
+
+    // 🔴 The provider is the one the SESSION'S OWN PLAN names. A DM's SURFACE tier IS its per-user personal silo, hard-pinned to the DB provider, so reading and writing it through the env-selected singleton instead would split a DM's status line from its own memory and land personal DM content in the shared durable store that pin exists to keep it out of.
+    // A channel's surface tier carries no plan pin, so there it still resolves to the same env-selected singleton.
+    const provider = surfaceProvider(bindFrom(ctx));
+
+    // 🔴 The base is the DURABLE tier, never the sandbox, for two independent reasons. First, this tool is not a memory persist path: handing the writer the whole sandbox surface directory let any file under it reach the durable tier through a status call — including on a channel session whose plan holds no surface tier at all, which is a door the write fence closes and a status tool must not reopen.
+    // Second, the board is CROSS-THREAD state: every thread upserts its own line into one STATUS.md, and a channel session's sandbox has no copy, so a sandbox base dropped every other thread's line on each call. Naming ONE file is safe because the tier write is upsert-only on every provider.
+    const durable = await provider.readTier(p, SURFACE);
+    const current = durable["STATUS.md"] ?? statusSeed(p.surfaceKey);
+    const updated = upsertStatusItem(current, sessionId, line);
+
+    const sandbox = await ctx.getSandbox();
+    // Write it live in this session, then persist to the durable store so the channel's pinned-message sync and other threads see it.
+    // 🔴 This write can CREATE the surface directory: every session gets a status, including a channel session whose plan holds no surface tier, and creating it needs write on the memory root that the root fence takes away at session start. So it runs with the root unlocked and re-locked — and unlike the flush-time callers, this one runs INSIDE a model step, so the unlock is a window.
+    await withMemoryRootWritable(sandbox, () => writeTierFile(sandbox, SURFACE, "STATUS.md", updated));
+    // THE ONE ROAD (OPE-1873), as an OPERATIONAL write. The status board is host bookkeeping on the
+    // surface tier, not a fact the agent remembered, so it files under `memory.operational_write`:
+    // a `memory.write` row here would answer "did the note reach the silo?" with a status update.
+    await writeMemoryTier({
+      provider,
+      partition: p,
+      tier: SURFACE,
+      files: { "STATUS.md": updated },
+      message: `status [${input.state}] ${sessionId}`,
+      road: "status-board",
+      kind: "operational",
+      principalId: bindFrom(ctx).principalId,
+      turnId: currentTurnId(ctx),
+      extra: { state: input.state, sessionId },
+    });
+
+    return { updated: true, state: input.state };
+  },
+});

package/agent/tools/usage_report.ts

@@ -0,0 +1,103 @@
+// usage_report is activity analytics for a domain or the whole org: conversations, turns, a per-user breakdown and the busiest surfaces. It ships AGGREGATES only, and reports counts rather than judgments.
+// Scope gating is identical to the spend report: domain scope is anyone in a memory domain, and org scope needs an org admin. "Conversations" is an APPROXIMATION derived from grouped data, while turns, per-user counts and busiest surfaces are exact.
+
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { usageSummary } from "../spend/usage-events.js";
+import { getConfig } from "../access/config.js";
+import { resolveReportScope, filterToDomain, approxConversationCount, aggregateByUser, aggregateBySurface, resolveSlackLabels } from "../spend/reporting.js";
+import { maskDmSurfaceKey } from "../spend/dm-mask.js";
+import { fulfilPaneRead } from "../access/pane-venue.js";
+import { bridgeFetchUserDisplayName, bridgeFetchChannelDisplayName } from "../channels/slack-bridge.js";
+
+function isoDaysAgo(days: number): string {
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+
+/** The DM rendering of an org-scope usage report (OPE-44's delivery arm). Plain text, top rows only
+ *  — a DM is a reading room, not a spreadsheet; the full table stays available in a governance
+ *  channel or via the control MCP. */
+function renderUsageReportForDm(r: { org: string; sinceDays: number; conversations: number; turns: number; byUser: readonly { principalId: string; name?: string; events: number }[]; busiestSurfaces: readonly { surfaceKey: string; channel?: string; events: number }[] }): string {
+  const lines = [
+    `Usage — org "${r.org}", last ${r.sinceDays} days`,
+    `conversations ≈ ${r.conversations} · turns ${r.turns}`,
+    "",
+    "Most active people:",
+    ...(r.byUser.length ? r.byUser.slice(0, 5).map((u) => `  • ${u.name ?? u.principalId} — ${u.events} turns`) : ["  (none in window)"]),
+    "",
+    "Busiest surfaces:",
+    ...(r.busiestSurfaces.length ? r.busiestSurfaces.slice(0, 5).map((s) => `  • ${s.channel ?? s.surfaceKey} — ${s.events} turns`) : ["  (none in window)"]),
+    "",
+    'Top rows only; "conversations" is an estimate. Ask again in a governance channel (or use the control plane) for the full breakdown.',
+  ];
+  return lines.join("\n");
+}
+
+export default defineTool({
+  description:
+    "Activity analytics for your memory domain, or (org admins only) the whole org: conversation count (an estimate — see note), turns, a per-user activity breakdown, and the busiest surfaces, over a time window. scope=\"domain\" works for anyone in a memory domain; scope=\"org\" requires an org admin.",
+  inputSchema: z.object({
+    scope: z.enum(["domain", "org"]).describe('"domain" = your own resolved memory domain (anyone in it); "org" = the whole org (org-admin only).'),
+    sinceDays: z.number().int().positive().max(365).optional().describe("Window in days, default 30."),
+  }),
+  outputSchema: z.object({
+    scope: z.enum(["domain", "org"]),
+    org: z.string(),
+    domain: z.string().optional(),
+    sinceDays: z.number(),
+    since: z.string(),
+    conversations: z.number().describe("Distinct-session estimate — see note."),
+    turns: z.number().describe("Non-sandbox usage-event count (~model calls)."),
+    byUser: z.array(z.object({ principalId: z.string(), name: z.string().optional(), events: z.number(), inputTokens: z.number(), outputTokens: z.number() })),
+    busiestSurfaces: z.array(z.object({ surfaceKey: z.string(), channel: z.string().optional(), events: z.number(), sessions: z.number(), inputTokens: z.number(), outputTokens: z.number() })),
+    note: z.string(),
+  }),
+  approval: never(),
+  async execute(input, ctx) {
+    const resolved = resolveReportScope(ctx, input.scope);
+    // Dual gate. The scope resolver is the ROLE half — org scope needs an org admin. Org-grain output is also pane-scoped, so the pane read is the VENUE half: it returns the build's value in the right venue, redirects WITHOUT running the build, or runs it and delivers the result to the requester's DM itself, throwing so nothing reaches the room.
+    // Domain scope is room-safe in that domain's channels and takes no venue gate.
+    const build = async () => {
+      const sinceDays = input.sinceDays ?? 30;
+      const since = isoDaysAgo(sinceDays);
+
+      const allRows = await usageSummary(resolved.org, { sinceTs: since });
+      const scopedRows = resolved.domain ? filterToDomain(allRows, resolved.domain, getConfig().loadDomains()) : allRows;
+      // Anti-doxxing: DM rows report under one "(dms)" bucket per workspace — masked
+      // BEFORE aggregation so they group naturally. The store keeps full resolution.
+      const maskedRows = scopedRows.map(maskDmSurfaceKey);
+
+      const conversations = approxConversationCount(maskedRows);
+      const surfaces = aggregateBySurface(maskedRows);
+      const turns = surfaces.reduce((sum, s) => sum + s.events, 0);
+      const users = aggregateByUser(scopedRows);
+
+      // Best-effort display labels (Slack users.info / conversations.info, memoized) so
+      // the report reads as names, not raw ids. The raw id always stays in the row.
+      const labels = await resolveSlackLabels(
+        users.map((u) => u.principalId),
+        surfaces.map((s) => s.surfaceKey),
+        { userName: bridgeFetchUserDisplayName, channelName: bridgeFetchChannelDisplayName },
+      );
+      const byUser = users.map((u) => ({ ...u, ...(labels.users.has(u.principalId) ? { name: labels.users.get(u.principalId)! } : {}) }));
+      const busiestSurfaces = surfaces.map((s) => ({ ...s, ...(labels.channels.has(s.surfaceKey) ? { channel: labels.channels.get(s.surfaceKey)! } : {}) }));
+
+      return {
+        scope: input.scope,
+        org: resolved.org,
+        ...(resolved.domain ? { domain: resolved.domain } : {}),
+        sinceDays,
+        since,
+        conversations,
+        turns,
+        byUser,
+        busiestSurfaces,
+        note:
+          'conversations is an approximation: usage rows are grouped by (surface, user, kind), and a single conversation CAN carry more than one sender (per-turn identity changes turn to turn), so this can overcount a multi-sender thread — turns/byUser/busiestSurfaces event counts are exact (plain sums), only the distinct-session figures ("conversations" and each surface\'s "sessions") share this caveat. name/channel labels are best-effort Slack lookups — prefer them when presenting, but the raw ids are the ground truth (a row without a label is a non-Slack principal, a DM, or a failed lookup). DM usage is aggregated into a single "(dms)" bucket per workspace — individual DM surfaces are deliberately never listed in reports (the underlying rows keep full resolution). A row written before the conversation-mode stamp existed cannot be classified, so it reports under a separate "(unclassified)" bucket per workspace: masked rather than named, and kept apart from "(dms)" so a channel\'s spend is never reported as DM spend.',
+      };
+    };
+    if (input.scope !== "org") return await build();
+    return await fulfilPaneRead(ctx, { kind: "usage.report.org", render: renderUsageReportForDm }, build);
+  },
+});

package/agent/tools/walk_pr.ts

@@ -0,0 +1,150 @@
+// walk_pr GATHERS the decision inputs for "walk me through PR #N". Read-only, open tier, host-side with a READ-scoped credential. ⭐ It is PHASE ONE OF TWO, and the split is the SECURITY DESIGN rather than a UX choice: the session that authored a change is the least-trusted context for vouching for it, so it cannot SUPPLY the facts — there is no input field, and they are fetched host-side from a provenance the session cannot author: a CODEOWNED workflow's own artifact, or a document a commit status vouches for by sha256 — cannot FRAME the review, because the schema is exactly `{repo, number}` and a test pins the key set, and cannot RENDER the answer, because phase two re-derives the facts and code-renders the document.
+// The narrator is an isolated declared subagent with no parent history whose own tools are all disabled, so an instruction embedded in the diff cannot make it fetch the proposer's context. The DELEGATION is a model act, because eve exposes no host-side seam for invoking a declared subagent — so THAT the model delegates is MEASURED from spend rows no tool input can author, while THAT the verdict is relayed faithfully stays relayed, and the document says so rather than implying otherwise.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { resolveAccessFor } from "../access/request.js";
+import { preRegisterDynamicEntry } from "../access/window-gated.js";
+import type { BindableContext } from "../identity/binding.js";
+import { repoAllowed } from "../scm/provider.js";
+import { assertGithubActingIdentity } from "../scm/github-acting-identity.js";
+import { githubWorkMount } from "../scm/github-work.js";
+import { describePrStatus, fetchPullRequestStatus, prStateLabel, resolveReadToken } from "../scm/pr-status.js";
+import { fetchPrDiff } from "../scm/pr-diff.js";
+import { fetchConfigFacts } from "../review/facts-artifact.js";
+import { buildNarratorBrief, renderWalkthrough } from "../review/pr-walkthrough.js";
+
+/** The keys this tool accepts. Exported so a test can pin that there is no third one — the
+ *  "no channel for the proposer's framing" property is only real while this set is {repo, number}. */
+export const WALK_PR_INPUT_KEYS: readonly string[] = ["repo", "number"];
+
+const inputSchema = z.object({
+  repo: z.string().describe("Repository as 'owner/repo'."),
+  number: z.number().int().positive().describe("PR number."),
+});
+
+// FACTORED (see check_pr_status.ts): a top-level const, never an inline literal in the resolver.
+export const walkPrEntry = defineTool({
+  description:
+    "Gather everything needed to walk a human through a pull request before they merge it: the PR's state, its diff, and the resolved-config FACTS (effective access per scope, domain rosters, declared webhooks, standing instructions) read either from the config-diff workflow's own artifact or from the `oe/config-diff` commit status that vouches for a cloud run's output by sha256. Returns a `narratorBrief` — pass it verbatim as `message` to fresh_eyes_review, then call post_pr_walkthrough with that verdict. Read-only, no approval needed. It deliberately takes no free-text input: you cannot add your own framing to what the independent reviewer sees.",
+  inputSchema,
+  outputSchema: z.object({
+    repo: z.string(),
+    number: z.number(),
+    headSha: z.string(),
+    prSummary: z.string(),
+    factsState: z
+      .enum(["artifact", "cloud-status", "not-triggered", "unavailable"])
+      .describe(
+        "artifact = real config facts from a CODEOWNED Actions workflow run; cloud-status = real config facts from a cloud run, vouched for by an " +
+          "`oe/config-diff` commit status and verified against the sha256 it names; not-triggered = this PR changes no config (a computed absence); unavailable = UNKNOWN.",
+      ),
+    factsRunId: z.number().optional().describe("The config-diff workflow run the facts came from. Actions provenance only — a cloud-status walkthrough has no run id. Pass to post_pr_walkthrough so a staleness check is possible."),
+    factsNote: z.string().describe("One line: where the facts came from, or why there are none."),
+    diffChars: z.number(),
+    diffClipped: z.boolean(),
+    filesTouched: z.number(),
+    narratorBrief: z.string().describe("Pass this verbatim to fresh_eyes_review as `message`. Do not edit, summarize or add to it."),
+    factsOnlyWalkthrough: z.string().describe("The walkthrough as it stands with NO narration — every interpretive section renders NOT COMPUTABLE."),
+    nextStep: z.string(),
+  }),
+  // NO `approval:` — see check_pr_status.ts. Read-only, so an absent approval is the same answer
+  // `never()` gave, and a dynamic-tool approval fn would not survive a replay lookup.
+  async execute(input, ctx) {
+    const access = resolveAccessFor(ctx);
+    if (!repoAllowed(input.repo, access.repos)) {
+      throw new Error(
+        `repo "${input.repo}" is not granted to this channel. Allowed: ${access.repos.length ? access.repos.join(", ") : "(none)"}. ` +
+          `Grant it via a bundle's repos (see agent/access/bundles.ts).`,
+      );
+    }
+    // The acting-identity gate, after the repo fence and before the token — see check_pr_status.ts
+    // for why that order, and scm/github-acting-identity.ts for what the gate decides. This verb
+    // returns the PR's whole DIFF, so an unrefused own-account ask here reads the org's view of the
+    // member's own question in more detail than any other GitHub read.
+    await assertGithubActingIdentity(ctx as BindableContext, "walk_pr");
+    const token = await resolveReadToken(input.repo);
+    // Both reads hit the same endpoint family and neither depends on the other's result, so they run
+    // together — a walkthrough is an interactive ask and two serial round trips is a visible stall.
+    const [status, diff] = await Promise.all([
+      fetchPullRequestStatus({ repo: input.repo, number: input.number, token }),
+      fetchPrDiff({ repo: input.repo, number: input.number, token }),
+    ]);
+
+    const facts = await fetchConfigFacts({
+      repo: input.repo,
+      headSha: diff.headSha,
+      token,
+      // A CAPPED file list must not be used to conclude "this PR touches no config" — that would be
+      // a computed-absence claim derived from an incomplete list, i.e. exactly a green produced by
+      // blindness. Withholding the list makes the outcome `unavailable` (an UNKNOWN) instead.
+      ...(diff.filesCapped ? {} : { changedPaths: diff.files }),
+    });
+
+    const pr = {
+      repo: input.repo,
+      number: input.number,
+      url: status.url,
+      title: status.title,
+      stateLabel: prStateLabel(status),
+      baseRef: diff.baseRef,
+      headSha: diff.headSha,
+    };
+
+    return {
+      repo: input.repo,
+      number: input.number,
+      headSha: diff.headSha,
+      prSummary: describePrStatus(status),
+      factsState: facts.kind,
+      ...(facts.kind === "artifact" ? { factsRunId: facts.provenance.runId } : {}),
+      factsNote:
+        facts.kind === "artifact"
+          ? `config-diff run ${facts.provenance.runId} (${facts.provenance.runUrl}), artifact "${facts.provenance.artifactName}", conclusion ${facts.provenance.runConclusion ?? "pending"}`
+          : facts.kind === "cloud-status"
+            ? `the "${facts.provenance.statusContext}" commit status on ${facts.provenance.headSha.slice(0, 12)}` +
+              `${facts.provenance.postedBy ? ` (posted by ${facts.provenance.postedBy})` : ""}, vouching for ${facts.provenance.documentUrl} ` +
+              `by sha256:${facts.provenance.digest} — verified before the facts were read`
+            : facts.reason,
+      diffChars: diff.diffChars,
+      diffClipped: diff.diffClipped,
+      filesTouched: diff.files.length,
+      narratorBrief: buildNarratorBrief({ pr, diff, facts }),
+      factsOnlyWalkthrough: renderWalkthrough({ pr, diff, facts }),
+      nextStep:
+        `Call fresh_eyes_review with message = narratorBrief (verbatim), then post_pr_walkthrough with repo, number, ` +
+        `narration = that verdict, and factsRunId = ${
+          facts.kind === "artifact"
+            ? facts.provenance.runId
+            : facts.kind === "cloud-status"
+              ? "(omit — these facts come from a commit status, which has no workflow run id)"
+              : "(omit — there are no facts)"
+        }. ` +
+        `Do not write the walkthrough yourself: post_pr_walkthrough renders it from the facts it fetches itself, and your prose would not be labelled as a model opinion.`,
+    };
+  },
+  // The DIFF inside the narrator brief is already wrapped in the untrusted envelope by the builder, so the structural scaffold here stays trusted text and only third-party bytes are fenced.
+  // This is a DYNAMIC tool, so the authored projection survives replay only through the durable descriptor the pre-registration below fills; the same call records the mounted name for the connector-wrap classification (access/untrusted-projection.ts). There is no patch-side backstop — OPE-378 retired it.
+  toModelOutput(output) {
+    const o = output as { prSummary: string; factsNote: string; narratorBrief: string; nextStep: string; factsState: string };
+    return {
+      type: "text" as const,
+      value: [
+        `PR: ${o.prSummary}`,
+        `Config facts: ${o.factsState} — ${o.factsNote}`,
+        "",
+        "── BRIEF FOR fresh_eyes_review (pass as `message`, verbatim) ──",
+        o.narratorBrief,
+        "",
+        `── NEXT ── ${o.nextStep}`,
+      ].join("\n"),
+    };
+  },
+});
+preRegisterDynamicEntry("walk_pr", "_single", walkPrEntry);
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) => (githubWorkMount(ctx as BindableContext) ? walkPrEntry : null),
+  },
+});

package/agent/webhooks/achievability.ts

@@ -0,0 +1,235 @@
+// CREATE-TIME ACHIEVABILITY (OPE-215) — the answer to doctrine 6:
+//
+//   > Nothing validates that a declared trigger's consequences are achievable from where it will
+//   > fire.
+//
+// Everywhere Open Everywhere lets someone declare a trigger, it validated the declaration's SYNTAX
+// and not its REACHABILITY. `assertWebhooksValid` checked that a hook's instruction was non-blank
+// and nothing else, so a config hook could name a read grant no routine could ever satisfy; the
+// declaration was accepted, and then nothing happened, forever, with no message anywhere. Two live
+// instances (the config-hook target and the zero-domain trap) were the same missing idea, so this
+// module implements the IDEA and each declaring path calls it.
+//
+// 🔴🔴 THIS IS A DIAGNOSTIC. IT IS NOT A SECOND BELT, AND IT MUST NEVER BECOME ONE.
+// `routines/ingress.ts` states the constraint that shaped the existing code and it is correct:
+//
+//   > "Fire-time enforcement is the load-bearing half either way (a grant revoked after arming must
+//   > stop the fire…), which is why it is the half that exists; the absence of a create-time check
+//   > is a WORSE ERROR MESSAGE, not a weaker boundary. Do not read this comment as 'belt and
+//   > braces' — there is one belt."
+//
+// Everything here is therefore subject to two rules, and a change that breaks either is a bug:
+//
+//   1. IT MAY ONLY EVER REFUSE. Nothing in this module grants, widens, or is consulted at fire time.
+//      A verdict of "reachable" authorises nothing — fire time asks its own question and may still
+//      say no (a grant revoked after arming, a domain roster edited, a channel moved). The one place
+//      the existing argument understated the problem is where there is NO MESSAGE AT ALL, which is
+//      what this closes.
+//   2. A CHECK THAT CANNOT DECIDE MUST BE INERT, NEVER FAIL-CLOSED. "We could not ask" is not
+//      evidence of a defect, and turning it into one converts an unanswerable question into a
+//      product outage — a declaration refused, or worse a BOOT refused, because a registry had not
+//      loaded yet. Every entry point below reports `undecidable` and returns EMPTY defect lists,
+//      and callers are required to treat that as silence.
+//
+// ⭐ THE THREE-WAY SPLIT IS THE WHOLE DESIGN, and it is why this returns a record instead of a
+// boolean. "Is this achievable" has three answers, not two, and collapsing the third into either of
+// the others is how a create-time check becomes either useless or an outage:
+//
+//   • `impossible`   — DECIDABLE NOW, and certainly wrong. A grant naming a domain this deployment
+//                      does not declare cannot match anything, ever, and no later state makes it
+//                      match. Callers REFUSE on these.
+//   • `unreachable`  — DECIDABLE NOW, and probably not what was meant, but legitimately
+//                      constructible. A hook whose own target channel cannot read it still fires its
+//                      declared instruction perfectly well; what it cannot do is host a subscribing
+//                      routine in that room. Callers WARN on these and proceed.
+//   • `undecidable`  — the question could not be asked. Callers say NOTHING.
+//
+// PURE, and it stays that way. No store, no config lookup, no clock: every caller passes the domain
+// registry it already holds. That is what lets the same function run at module-import time (where
+// `getConfig()` may not be armed yet), inside a tool's execute (where everything is live), and in a
+// test with three fixture domains.
+
+import { resolveDomainForChannel, type Domain } from "../memory/domain.js";
+import { describeReadableBy, scopeGrantsRead, type ReadableBy } from "../access/read-grant.js";
+
+/** The three-way verdict. See the header for why it is not a boolean and not a list. */
+export interface TriggerReach {
+  /** Decidable and certainly wrong — a caller REFUSES on a non-empty list. */
+  readonly impossible: readonly string[];
+  /** Decidable and probably wrong, but legitimately constructible — a caller WARNS and proceeds. */
+  readonly unreachable: readonly string[];
+  /** Set ⇒ the check could not run. BOTH lists are empty and mean nothing; say nothing. */
+  readonly undecidable?: string;
+}
+
+const DECIDED_CLEAN: TriggerReach = { impossible: [], unreachable: [] };
+
+function inert(why: string): TriggerReach {
+  return { impossible: [], unreachable: [], undecidable: why };
+}
+
+/** `platform/<tenant-id>` for a fully-qualified surface key — the form `scopeGrantsRead` compares a
+ *  `tenant` scope against (`access/resolver.ts` tenantKeyOf), derived here rather than imported so
+ *  this leaf stays free of the resolver. */
+function tenantKeyOf(surfaceKey: string): string {
+  return surfaceKey.split("/").slice(0, 2).join("/");
+}
+
+/**
+ * ⭐ THE PRIMITIVE: can a consequence sitting at `surfaceKey` read events from an ingress granted
+ * `readableBy`? The exact question the fire-time check asks, asked early against config the deployer
+ * has already written.
+ *
+ * 🔴 IT CALLS `scopeGrantsRead` — THE SAME FUNCTION FIRE TIME CALLS — rather than re-deriving the
+ * union rule. A create-time diagnostic that disagreed with fire time would be worse than none: it
+ * would either refuse things that work (an outage authored by a warning) or bless things that do
+ * not (the failure it exists to catch). The fire-time caller passes a full `EffectiveAccess` and
+ * this one passes the three fields the rule actually reads, which is why that parameter was narrowed
+ * to its structural minimum rather than duplicated here.
+ *
+ * WHAT IS UNDECIDABLE, AND WHY EACH ONE:
+ *   • NO DOMAIN REGISTRY. `assertWebhooksValid` runs at module import, where the app-config seam may
+ *     not be armed; a caller that cannot hand over `loadDomains()` gets silence, not a refusal.
+ *   • NO GRANT ON THE INGRESS. A vendor ingress (the native GitHub fan-out) legitimately declares no
+ *     `readableBy` and is authorized by its source's own scope-grant adapter instead, whose answer
+ *     depends on the PAYLOAD — a repo id that does not exist until a delivery arrives. That is not
+ *     knowable in advance by anyone. An EMPTY grant is a different matter and is already refused by
+ *     `readableByDefects` where it is declared; this is not the place to re-litigate it.
+ */
+export function readGrantReach(surfaceKey: string, readableBy: ReadableBy | undefined, domains: readonly Domain[] | undefined): TriggerReach {
+  if (!domains) return inert("no domain registry was supplied, so which domain this surface belongs to is unknown");
+  if (!readableBy || readableBy.length === 0) {
+    return inert("this ingress declares no read grant of its own, so authorization is decided per-delivery by its source's scope-grant adapter");
+  }
+  const routing = resolveDomainForChannel(surfaceKey, domains);
+
+  // 🔴 ASK THE FIRE-TIME FUNCTION FIRST, ALWAYS — before any shape-based shortcut.
+  //
+  // The zero-domain shape is NOT sufficient to refuse, and assuming it was is the exact mistake this
+  // module's rule 1 names: a diagnostic that refuses things that work is worse than no diagnostic.
+  // `scopeGrantsRead` grants an `org` entry UNCONDITIONALLY, a `tenant` entry on tenant-key match and
+  // a `surface` entry on surface-key match (access/read-grant.ts) — **none of which read `domains` at
+  // all**. So a hook granted `{level:"org"}` (the `"*"` path `declare_webhook` documents) pointed at a
+  // channel that is in no domain is perfectly live at fire time, and a shape-based shortcut here
+  // would tell its author it could "never" fire.
+  //
+  // Passing `[]` for a domainless surface is the honest input, not a fallback: it is precisely what
+  // the fire-time caller passes, so the two agree by construction rather than by us re-deriving the
+  // rule here. Only once the grant genuinely does NOT match is the missing domain worth reporting —
+  // and then it is the *explanation* for the refusal, not the test that produced it.
+  const granted = scopeGrantsRead(readableBy, {
+    tenantKey: tenantKeyOf(surfaceKey),
+    surfaceKey,
+    domains: routing.domain ? [routing.domain.name] : [],
+  });
+  if (granted) return DECIDED_CLEAN;
+
+  // Not granted. It is `unreachable` and not `impossible` because a hook pointed at such a channel
+  // still fires its own declared instruction; what dies is the ability to subscribe a routine there.
+  if (!routing.domain) {
+    return {
+      impossible: [],
+      unreachable: [
+        `${surfaceKey} belongs to no memory domain, and this ingress grants ${describeReadableBy(readableBy)} — which names no domain-independent level ` +
+          `(an org-, tenant- or surface-level grant would still reach it). So no routine armed there can read this ingress's events. ` +
+          `Add the channel to a domain in the app's memory/config/domains.ts, point this at a channel already in one, or widen the grant.`,
+      ],
+    };
+  }
+  return {
+    impossible: [],
+    unreachable: [
+      `${surfaceKey} is in domain "${routing.domain.name}", which the read grant does not name — it grants ${describeReadableBy(readableBy)}. ` +
+        `A routine armed in that channel would be accepted and would then never fire.`,
+    ],
+  };
+}
+
+/**
+ * Is every `domain` entry in this grant a domain the deployment actually declares?
+ *
+ * 🔴 THIS IS THE ONE ARM THAT PRODUCES `impossible`, and the certainty comes from a specific fact:
+ * the registry is NON-EMPTY. A non-empty registry proves the loader ran and returned real data, so a
+ * name that is not in it is a typo — deterministically unmatchable, by any surface, forever.
+ *
+ * AN EMPTY REGISTRY IS DELIBERATELY *NOT* THE SAME VERDICT, and the distinction is load-bearing. A
+ * deployment mid-setup — domains not declared yet, hooks being written — has an empty registry and
+ * perfectly legitimate intentions. Refusing there would turn "you have not finished configuring" into
+ * a boot failure, which is the outage-by-diagnostic this module's rule 2 exists to prevent. So it
+ * WARNS: the same fact, stated, without taking the deployment down over it.
+ *
+ * `tenant` / `surface` / `org` entries are not checked. There is no registry of legal tenant ids or
+ * channel ids to check them against — a workspace exists because Slack says so, not because this
+ * repo declares it — so an unknown one is undecidable rather than wrong, and inventing an allow-list
+ * to check against would be a second registry for a concern nobody has.
+ */
+export function grantDomainsExist(readableBy: ReadableBy | undefined, domains: readonly Domain[] | undefined): TriggerReach {
+  if (!domains) return inert("no domain registry was supplied");
+  if (!readableBy || readableBy.length === 0) return DECIDED_CLEAN;
+  const named = readableBy.flatMap((s) => (s.level === "domain" && s.domain ? [s.domain] : []));
+  if (named.length === 0) return DECIDED_CLEAN;
+  const declared = new Set(domains.map((d) => d.name));
+  const unknown = named.filter((d) => !declared.has(d));
+  if (unknown.length === 0) return DECIDED_CLEAN;
+  const list = unknown.map((d) => `"${d}"`).join(", ");
+  if (declared.size === 0) {
+    return {
+      impossible: [],
+      unreachable: [
+        `the read grant names ${list}, and this deployment declares no memory domains at all — so nothing can read this ingress's events yet. ` +
+          `Declare the domain(s) in the app's memory/config/domains.ts; until then the grant matches nothing.`,
+      ],
+    };
+  }
+  return {
+    impossible: [
+      `the read grant names ${list}, which ${unknown.length > 1 ? "are not memory domains" : "is not a memory domain"} this deployment declares — ` +
+        `a grant naming one refuses every routine, forever, in silence. Declared domains: ${[...declared].sort().join(", ")}.`,
+    ],
+    unreachable: [],
+  };
+}
+
+/** Merge verdicts. UNDECIDABLE IS NOT CONTAGIOUS: one arm being unable to ask does not silence the
+ *  arms that could, so the result is undecidable only when EVERY arm was — which is the honest
+ *  reading of "we learned nothing". */
+export function mergeReach(...parts: readonly TriggerReach[]): TriggerReach {
+  const decided = parts.filter((p) => p.undecidable === undefined);
+  if (decided.length === 0) {
+    return inert(parts.map((p) => p.undecidable).filter(Boolean).join("; ") || "nothing was checkable");
+  }
+  return {
+    impossible: decided.flatMap((p) => p.impossible),
+    unreachable: decided.flatMap((p) => p.unreachable),
+  };
+}
+
+/**
+ * The whole create-time verdict for ONE config-declared hook: are the domains it grants real, and
+ * can the channel it fires into read it?
+ *
+ * The second question is the one §2.8 named. A fused hook's DECLARED consequence (its
+ * target + instruction) always fires — that path takes no grant at all — but its SUBSCRIBED
+ * consequences do, and the single most obvious thing anyone does with a hook is arm a routine in the
+ * very channel it posts into. A hook whose own target room cannot read it is almost never intended,
+ * and until now nothing anywhere said so.
+ *
+ * 🔴 AN EMIT-ONLY HOOK (OPE-224) MAKES THAT SECOND QUESTION UNASKABLE, NOT FAILING. With no
+ * `target` there is no "the very channel it posts into" to test the grant against, and there is no
+ * other surface this module would be entitled to guess at — a routine could legitimately be armed in
+ * any room the grant reaches. So the arm goes INERT, per rule 2: "we could not ask" must never
+ * become a refusal, and an emit-only hook is precisely the shape whose consequences are decided
+ * later and elsewhere. The FIRST arm (do the granted domains exist?) is unaffected and still
+ * produces the only `impossible` verdict this module has.
+ */
+export function webhookReach(
+  hook: { readonly id: string; readonly target?: string; readonly readableBy: ReadableBy },
+  domains: readonly Domain[] | undefined,
+): TriggerReach {
+  return mergeReach(
+    grantDomainsExist(hook.readableBy, domains),
+    hook.target === undefined
+      ? inert("this hook declares no target, so there is no room whose ability to read its events could be checked (an emit-only hook's consequences live in `event` routines, anywhere the grant reaches)")
+      : readGrantReach(hook.target, hook.readableBy, domains),
+  );
+}