@open-everywhere/core 0.1.0

package/agent/access/window-routing.ts

@@ -0,0 +1,23 @@
+// Classifies a wake against the routing invariant: a `native` wake in a room whose domain WINDOWS is audited as degraded, because such a seat keeps talking while holding a different session key, toolset and memory answer. Since OPE-1695 TWO things reach that row — a routing regression, and the runtime privacy floor standing the seat down — and this pure classifier cannot subtract the second, so read a row against the surface's vouch before calling it a bug.
+
+import type { WindowGrain } from "../identity/binding.js";
+import { windowedDomainFor, type Domain } from "../memory/domain.js";
+
+export type WindowRoutingPosture =
+  /** On a window/task/thread seat — the intended path (or the wake is a worker, which is windowed by construction). */
+  | "windowed"
+  /** `native`, and legitimately so: the topology gate is off, or the channel resolves to no seat
+   *  domain at all (no explicit domain and no `org` pseudo-domain to inherit). */
+  | "native-by-design"
+  /** `native` even though the room HAS a seat — a routing regression, or the runtime privacy floor
+   *  standing the seat down. Loud either way; see the header for how to tell them apart. */
+  | "native-degraded";
+
+/** Classify a wake against the routing invariant. `domainKey` is the partition's DOMAIN-grain key, the same key every other window gate is asked about, so this can never disagree with the divert layer about which channel it means. */
+export function classifyWindowRouting(grain: WindowGrain, domainKey: string, domains: readonly Domain[]): WindowRoutingPosture {
+  if (grain !== "native") return "windowed";
+  return windowedDomainFor(domainKey, domains) ? "native-degraded" : "native-by-design";
+}
+
+/** The audit `action` a degraded wake emits — one greppable string, shared by the hook and its test. */
+export const WINDOW_ROUTING_DEGRADED_ACTION = "window.routing_degraded";

package/agent/access/work-grant.ts

@@ -0,0 +1,119 @@
+// A provider is TWO surfaces: the CHAT credential, which nothing here governs, and the WORK surface, which a domain holds ONLY by declaring the work role in its own `Domain.credentials`.
+// That declaration IS the grant and it NEVER falls back: a domain that declares nothing holds no work grant, and absence is a refusal rather than a default. GitHub is the exception, declaring its grant as an access bundle's repo list.
+
+// callerWorkDomain and callerWorkGrant are the grant chain once, so three consumers cannot disagree about which domain the caller is in. The resolver stays injectable because Notion canonicalises a page UUID, and `domains` stays a thunk for a `session.started` resolver that runs before config registers.
+
+import { resolveDomainForChannel, type Domain } from "../memory/domain.js";
+import { resolvePartition } from "../memory/partition.js";
+import type { BindableContext } from "../identity/binding.js";
+import { credentialOverrideFor, type CredentialBoundDomain } from "./domain-credentials.js";
+
+/** The credential id this domain does `connector` work under, or undefined when it holds no work grant. NO FALLBACK: undefined means the domain may not do work on this provider, never "use the org default". */
+export function workGrantCredential(
+  domain: CredentialBoundDomain | undefined,
+  connector: string,
+  workRole: string,
+): string | undefined {
+  const declared = credentialOverrideFor(domain, connector, workRole);
+  if (!declared) return undefined;
+  // `use` is validated non-empty at boot (domainCredentialProblems), so this is the declared id.
+  return declared.use;
+}
+
+/** The mount predicate every work tool's `session.started` resolver calls: false means the tool is ABSENT, not merely refusing. A tool the model can see but can never use is what produces a false capability claim in a member-facing reply. */
+export function hasWorkGrant(
+  domain: CredentialBoundDomain | undefined,
+  connector: string,
+  workRole: string,
+): boolean {
+  return workGrantCredential(domain, connector, workRole) !== undefined;
+}
+
+/** How a work tool's mount reads the caller's domain. The default compares whole surface keys verbatim; Notion passes its own, which canonicalises a page UUID first. */
+export type WorkDomainResolver = (surfaceKey: string, domains: readonly Domain[]) => Domain | undefined;
+
+const resolveByChannelKey: WorkDomainResolver = (surfaceKey, domains) => resolveDomainForChannel(surfaceKey, domains).domain;
+
+/** The memory domain a calling session belongs to, whatever surface it was woken on. FAIL-SOFT to undefined, which is the fail-closed direction here: an unreadable partition or config means no grant can be shown, so no work tool mounts. */
+export function callerWorkDomain(
+  ctx: BindableContext,
+  domains: () => readonly Domain[],
+  resolveDomain: WorkDomainResolver = resolveByChannelKey,
+): Domain | undefined {
+  try {
+    return resolveDomain(resolvePartition(ctx).surfaceKey, domains());
+  } catch {
+    return undefined;
+  }
+}
+
+/** The grant-to-mount rule in one call: read as a boolean it is a provider's mount predicate, read as a string it is the credential resolver. One function, so a mount and the credential it mounts for cannot disagree about the caller's domain. */
+export function callerWorkGrant(
+  ctx: BindableContext,
+  connector: string,
+  workRole: string,
+  domains: () => readonly Domain[],
+  resolveDomain?: WorkDomainResolver,
+): string | undefined {
+  return workGrantCredential(callerWorkDomain(ctx, domains, resolveDomain), connector, workRole);
+}
+
+/** Where a provider's WORK half lives. `entity` is an addressable item a caller names, so the grant alone is a complete route and the platform can be a ticket destination; `container` is the conversation this turn arrived in, so the grant is joined with the window's sources and the platform is never a destination. A provider may hold both on one role. */
+export type WorkSurfaceKind = "entity" | "container";
+
+/** One provider's WORK role — the (connector, org-default credential id) pair a declaration names. */
+export interface WorkRole {
+  readonly connector: string;
+  readonly role: string;
+  readonly kind: WorkSurfaceKind;
+}
+
+/**
+ * The reviewed record of every (connector, work-role) pair some provider in this tree reads as a work grant.
+ * It grants nothing and fences nothing, because every gate calls hasWorkGrant with its own pair, and it is NOT a list of ticket destinations (channels/work-registry.ts answers that). Extend it in the same diff that teaches a provider to read a grant.
+ */
+export const WORK_ROLES: readonly WorkRole[] = [
+  { connector: "notion", role: "team-key", kind: "entity" },
+  { connector: "linear", role: "workspace", kind: "entity" },
+  { connector: "slack", role: "work-token", kind: "container" },
+  { connector: "discord", role: "work-token", kind: "container" },
+  { connector: "teams", role: "work-token", kind: "container" },
+  // Notion and Linear are CONTAINERS as well as entities: an addressable entity is also the conversation a seat or worker was delegated from. The same role is reused deliberately - one declaration read by two mount predicates, rather than a second credential a domain would have to keep in step.
+  { connector: "notion", role: "team-key", kind: "container" },
+  { connector: "linear", role: "workspace", kind: "container" },
+];
+
+/** The work role declared for `connector`, or `undefined` when this tree reads none for it. */
+export function workRoleFor(connector: string): string | undefined {
+  return WORK_ROLES.find((w) => w.connector === connector)?.role;
+}
+
+/** The work role for a CONTAINER-kind (chat) surface, or `undefined` — the predicate
+ *  access/surface-work-grant.ts gates on. An `entity`-kind provider answers undefined here: its work
+ *  half is a page or an issue, not the conversation. */
+export function containerWorkRoleFor(connector: string): string | undefined {
+  return WORK_ROLES.find((w) => w.connector === connector && w.kind === "container")?.role;
+}
+
+/** GitHub's connector slug on the work plane — the name every consumer reports the grant under. */
+export const GITHUB_CONNECTOR = "github";
+
+/** The grant is the session's repo grant, resolved for the calling scope. It grants nothing and fences nothing: `repoAllowed` stays the authoritative wall, and a wildcard `owner/*` counts even though it names no concrete repo. */
+export function hasGithubWorkGrant(repos: readonly string[]): boolean {
+  return repos.length > 0;
+}
+
+/** The connectors these domains hold a work grant on, sorted - the prompt-facing summary, never a gate. A LIST because a surface can resolve into several domains; `repos` is a second argument because the repo grant is resolved for the calling scope, which a domain list cannot answer. */
+export function workGrantedConnectors(
+  domains: readonly (CredentialBoundDomain | undefined)[],
+  repos: readonly string[] = [],
+): readonly string[] {
+  const out = new Set<string>();
+  for (const domain of domains) {
+    for (const w of WORK_ROLES) {
+      if (hasWorkGrant(domain, w.connector, w.role)) out.add(w.connector);
+    }
+  }
+  if (hasGithubWorkGrant(repos)) out.add(GITHUB_CONNECTOR);
+  return [...out].sort();
+}

package/agent/access/work-mount-manifest.ts

@@ -0,0 +1,203 @@
+// The CI pin that every WORK tool decides its mount from the caller's WORK GRANT (access/work-grant.ts), never from grain or chat topology. `via` names the one parameter: `grant` alone, `grant-or-source` (the union with a chat-plane path), or `grant-and-source` (the intersection, for a container-fenced read).
+// It reads tool SOURCE as text, so it proves a tool NAMES its predicate and that none is unclassified, never that the predicate decides the mount. It can only narrow what a seat SEES; each provider's own fence stays the authoritative wall.
+
+export interface WorkToolFile {
+  readonly name: string;
+  readonly source: string;
+}
+
+export type WorkMountVia = "grant" | "grant-or-source" | "grant-and-source";
+
+/** One work tool's mount rule. `connector` is the provider slug the mount predicate names, or `"*"`
+ *  for a NEUTRAL verb that dispatches to whichever platform the caller asks for (`create_ticket` and
+ *  the three entity verbs): such a verb names no single connector, so the union set alone is its
+ *  mount and no connector-named predicate can apply to it. */
+export interface WorkMountRule {
+  readonly connector: string;
+  readonly via: WorkMountVia;
+}
+
+/** The CI-pinned registry of work tools to how each one reads the grant. Add a row in the SAME diff that authors a work tool - the totality guard below fails an unclassified one. */
+export const WORK_TOOL_MOUNTS: Readonly<Record<string, WorkMountRule>> = {
+  // Notion: `notion_search` exists only on the work credential, so it is grant-only, while `read_notion_page` keeps its chat-plane path and is the union. `read_notion_comments` has the chat arm alone and takes no work-mount rule.
+  notion_search: { connector: "notion", via: "grant" },
+  read_notion_page: { connector: "notion", via: "grant-or-source" },
+  // Linear: the same pair as read_notion_page above - the container read OR the domain's Linear work grant.
+  read_linear_issue: { connector: "linear", via: "grant-or-source" },
+  // GitHub (OPE-940 for the first two, OPE-960 for the rest). Grant-only: a GitHub chat channel
+  // confers no repo, and every one of these tools takes a `repo` it cannot name without one.
+  // `checkout_repo` / `open_pull_request` decide the mount inside `windowGated` (they are grain-gated
+  // too); the five below are WINDOW_UNGATED and decide it in a bare `session.started` resolver.
+  checkout_repo: { connector: "github", via: "grant" },
+  open_pull_request: { connector: "github", via: "grant" },
+  check_pr_status: { connector: "github", via: "grant" },
+  get_pr_feedback: { connector: "github", via: "grant" },
+  walk_pr: { connector: "github", via: "grant" },
+  post_pr_walkthrough: { connector: "github", via: "grant" },
+  subscribe_pr: { connector: "github", via: "grant" },
+  // The neutral work verbs are grant-only: one tool, many platforms, so the GRANT SET is the mount and no single connector names it. `read_work_channel` / `read_work_thread` are the INTERSECTION class, grant AND source, for the reason the header states.
+  read_work_channel: { connector: "*", via: "grant-and-source" },
+  read_work_thread: { connector: "*", via: "grant-and-source" },
+  create_ticket: { connector: "*", via: "grant" },
+  set_state: { connector: "*", via: "grant" },
+  assign: { connector: "*", via: "grant" },
+  add_label: { connector: "*", via: "grant" },
+  // The federated `search` verb reads `searchGrantedConnectors`, the RAW grant, and deliberately not `workDestinationPlatforms`: the ticket-registry filter would silently drop Notion.
+  search: { connector: "*", via: "grant" },
+};
+
+/** Work tools that carry the execute FENCE but mount with no grant check - a ticketed gap, NOT an exemption list: a row is still checked, must keep its fence, and must carry a real ticket id. The table is EMPTY and that is the target state; keep it empty. */
+export const WORK_MOUNT_GAPS: Readonly<Record<string, string>> = {};
+
+/** The work-plane symbols that make a tool file a WORK tool — see the header's totality signature. */
+const WORK_SIGNAL = new RegExp(
+  [
+    "\\brepoAllowed\\b",
+    "\\bworkDestinationPlatforms\\b",
+    "\\b[A-Za-z]+WorkMount\\b",
+    "\\bnotionWorkGrant\\b",
+    "\\bnotionWorkCredential\\b",
+    "\\blinearWorkOrg\\b",
+    "\\bworkGrantCredential\\b",
+    "\\bhasWorkGrant\\b",
+    "\\bhasGithubWorkGrant\\b",
+    "\\bcallerWorkGrant\\b",
+    "\\bsurfaceWorkReadMount\\b",
+    "\\bassertSurfaceWorkGrant\\b",
+    "\\bsearchGrantedConnectors\\b",
+  ].join("|"),
+  "u",
+);
+
+export function isWorkTool(source: string): boolean {
+  return WORK_SIGNAL.test(source);
+}
+
+/** The connector-named grant-only mount predicate, e.g. `notionWorkMount` / `githubWorkMount`. One
+ *  naming rule across every provider: a grant-only mount is `<connector>WorkMount`. */
+function grantMountPredicate(connector: string): string {
+  return `${connector}WorkMount`;
+}
+
+function namesIdentifier(source: string, identifier: string): boolean {
+  return new RegExp(`\\b${identifier}\\b`, "u").test(source);
+}
+
+/** A `grant-or-source` mount is the UNION: the connector-named `...WorkMount` alongside the chat path (`workerChatArmMount`, or the bare `sourceScopedMount`). `workDestinationPlatforms` is the GRANT SET, so a tool that names it and declares this class fails. */
+function mountsOnUnion(source: string, connector: string): boolean {
+  if (connector === "*") return false;
+  const chatArm = namesIdentifier(source, "sourceScopedMount") || namesIdentifier(source, "workerChatArmMount");
+  return namesIdentifier(source, grantMountPredicate(connector)) && chatArm;
+}
+
+/** A `via: "grant-and-source"` mount is the INTERSECTION: `surfaceWorkReadMount` decides the mount
+ *  from the window's sources filtered by the domain's grant, and `assertSurfaceWorkGrant` re-checks
+ *  the turn's OWN platform in execute. BOTH are required — the mount alone answers "any granted
+ *  source", so a unified window carrying an ungranted source would read it without the second call. */
+function mountsOnIntersection(source: string): boolean {
+  return namesIdentifier(source, "surfaceWorkReadMount") && namesIdentifier(source, "assertSurfaceWorkGrant");
+}
+
+/** Check the work-mount invariants over a set of scanned tool files; returns problem strings and is pure. `mounts`/`gaps` default to the real tables and are injectable only so the test can drive refusals the real manifest must never contain. */
+export function checkWorkMounts(
+  tools: readonly WorkToolFile[],
+  mounts: Readonly<Record<string, WorkMountRule>> = WORK_TOOL_MOUNTS,
+  gaps: Readonly<Record<string, string>> = WORK_MOUNT_GAPS,
+): string[] {
+  const problems: string[] = [];
+  const seen = new Set<string>();
+
+  for (const tool of tools) {
+    const rule = mounts[tool.name];
+    const gap = gaps[tool.name];
+
+    if (rule !== undefined && gap !== undefined) {
+      problems.push(
+        `tool "${tool.name}" is in BOTH WORK_TOOL_MOUNTS and WORK_MOUNT_GAPS — a work tool either mounts on the grant or is a declared gap, never both`,
+      );
+    }
+
+    if (rule !== undefined) {
+      seen.add(tool.name);
+      if (!isWorkTool(tool.source)) {
+        problems.push(
+          `tool "${tool.name}" is declared in WORK_TOOL_MOUNTS but its source names no work-plane symbol — either it stopped doing provider work (drop the row) or the totality signature missed it`,
+        );
+      }
+      // Rule 1 — the mount must be decided by the grant, in the class the row declares.
+      if (rule.via === "grant") {
+        if (rule.connector === "*") {
+          // A neutral verb names no single connector, so it mounts on a grant SET, and each has exactly ONE correct spelling: the ticket verbs read `workDestinationPlatforms`, `search` reads `searchGrantedConnectors`. Naming the other would pass this check while mounting on the wrong set.
+          const wantsSearchSet = tool.name === "search";
+          const spelling = wantsSearchSet ? "searchGrantedConnectors" : "workDestinationPlatforms";
+          if (!namesIdentifier(tool.source, spelling)) {
+            problems.push(
+              `tool "${tool.name}" declares via:"grant" with connector:"*" but never names ${spelling} — a neutral work verb mounts on the GRANT SET, which is the connector-less spelling of the same rule (ticket-destination verbs read workDestinationPlatforms; the search verb reads the raw searchGrantedConnectors instead — see channels/work-search.ts)`,
+            );
+          }
+        } else if (!namesIdentifier(tool.source, grantMountPredicate(rule.connector))) {
+          problems.push(
+            `tool "${tool.name}" declares via:"grant" but its source never names ${grantMountPredicate(rule.connector)} — a grant-only work tool MUST decide its mount with the connector's grant predicate (access/work-grant.ts), not grain and not topology`,
+          );
+        }
+        // Rule 1b — a grant-only tool must NOT also mount on chat presence. That would let a domain
+        // with the provider's chat channel and no work grant see a tool that can only refuse.
+        if (namesIdentifier(tool.source, "sourceScopedMount")) {
+          problems.push(
+            `tool "${tool.name}" declares via:"grant" but also mounts through sourceScopedMount — chat presence is never a precondition NOR a widening for a work-credential-only tool (OPE-928). Either drop the sources path or reclassify the row via:"grant-or-source"`,
+          );
+        }
+      } else if (rule.via === "grant-and-source") {
+        if (!mountsOnIntersection(tool.source)) {
+          problems.push(
+            `tool "${tool.name}" declares via:"grant-and-source" but its source does not name BOTH surfaceWorkReadMount (the mount) and assertSurfaceWorkGrant (the per-turn check) — a container-fenced work read needs the grant at mount AND on the turn's own platform`,
+          );
+        }
+        // A container-fenced work read must NOT mount on the grant SET: it admits every granted
+        // connector, so the verb would arm on a window that sources none of them — the INTERSECTION
+        // is the point, and half of it would be missing.
+        if (namesIdentifier(tool.source, "workDestinationPlatforms")) {
+          problems.push(
+            `tool "${tool.name}" declares via:"grant-and-source" but names workDestinationPlatforms — that predicate is the GRANT SET alone, so it would arm this verb on every granted connector regardless of which one this window actually sources`,
+          );
+        }
+      } else if (!mountsOnUnion(tool.source, rule.connector)) {
+        problems.push(
+          `tool "${tool.name}" declares via:"grant-or-source" but its source does not name the pair (${grantMountPredicate(rule.connector)} + sourceScopedMount) — since OPE-953 that is the ONE spelling of this class: the container read OR the grant. workDestinationPlatforms is the GRANT SET now and carries no chat arm, so it cannot stand in for the pair`,
+        );
+      }
+      continue;
+    }
+
+    if (gap !== undefined) {
+      seen.add(tool.name);
+      // Rule 2 — a declared gap is still checked. It must carry a real ticket id and it must keep the
+      // execute fence that makes its refusal real and audited.
+      if (!/^OPE-\d+$/u.test(gap)) {
+        problems.push(`tool "${tool.name}" is a WORK_MOUNT_GAPS row whose value "${gap}" is not a ticket id (expected OPE-<number>)`);
+      }
+      if (!namesIdentifier(tool.source, "repoAllowed")) {
+        problems.push(
+          `tool "${tool.name}" is a WORK_MOUNT_GAPS row but no longer names repoAllowed — a gap row is tolerated ONLY while the execute fence still refuses. Give it a grant mount and move it to WORK_TOOL_MOUNTS`,
+        );
+      }
+      continue;
+    }
+
+    // Rule 3 — totality. An un-classified work tool fails.
+    if (isWorkTool(tool.source)) {
+      problems.push(
+        `tool "${tool.name}" does provider WORK (its source names a work-plane symbol) but appears in neither WORK_TOOL_MOUNTS nor WORK_MOUNT_GAPS — classify it: a work tool's mount comes from the caller's work grant (access/work-grant.ts)`,
+      );
+    }
+  }
+
+  // Rule 4 — no stale row.
+  for (const name of [...Object.keys(mounts), ...Object.keys(gaps)]) {
+    if (!seen.has(name)) {
+      problems.push(`"${name}" is declared in the work-mount manifest but no tool file of that name was scanned — stale row (rename or delete it)`);
+    }
+  }
+
+  return problems;
+}