@open-everywhere/core 0.1.0

package/agent/identity/trust.ts

@@ -0,0 +1,433 @@
+// The per-surface trust registry: the operator's declaration of a room's AUDIENCE, carried as a typed `trust` field on a surface entry. `internal` is a promotion that sits BELOW the platform's own verdict and `public` is a demotion that sits ABOVE it, so uncertainty never resolves up — identity/binding.ts holds the precedence chain.
+// An entry is an operator assertion, never an inference: malformed config fails loud at boot, and nothing registered means nothing declared. There is no exclude list; write a carve-out by declaring the opposite trust.
+
+import { getSettings } from "../settings/settings.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+import {
+  parseSurfaceKeyEntry,
+  surfaceKeyEntriesIntersect,
+  surfaceKeyEntryMatches,
+  surfaceKeyEntrySpecificity,
+  type SurfaceKeyEntry,
+} from "./surface-key-grammar.js";
+
+/**
+ * The trust an entry declares. TWO values, and `"external"` is deliberately ABSENT — `public` IS
+ * the external declaration, and it says something `external` does not: that a HUMAN asserted it.
+ * The fail-closed default of an unlisted surface is also `external`, and the audit trail has to
+ * keep those two apart ("we could not ask" must never read as "we asked and it was fine").
+ */
+export type SurfaceTrust = "internal" | "public";
+
+/** One entry in the per-surface registry: a qualified key and the trust the operator declares for it. Future per-surface properties belong on this interface and are validated in defineSurface — do not add a speculative field before a behaviour needs it. */
+export interface Surface {
+  readonly key: string;
+  readonly trust: SurfaceTrust;
+  /**
+   * Does this entry vouch the surface's whole subtree, or only that one surface? It is opt-in on the line, so every plain entry an operator already wrote still vouches exactly one surface, and it is declarable only with trust: "internal" on an exact surface key.
+   * Only a platform whose key carries no hierarchy honours it, declared through registerSubtreePlatform; a claim on any other platform is a boot error, and the vendor adapter resolves the walk because this registry is pure and synchronous.
+   */
+  readonly subtree?: boolean;
+}
+
+/** The declarable values; also the allowlist defineSurface validates against. */
+const KNOWN_TRUST: ReadonlySet<string> = new Set<SurfaceTrust>(["internal", "public"]);
+
+/**
+ * Build a validated Surface, fail-LOUD (config-time): the key must parse in the shared grammar and
+ * the trust must be known. The app's surfaces.ts wraps every entry in this so a typo in the key
+ * grammar or an unknown trust is a boot error, not a silently-ignored line.
+ *
+ * `subtree` is validated here as far as ONE LINE can decide it — the value's type, the key grain and
+ * the trust. Whether the PLATFORM honours the claim is decided at {@link applySubtreeSurfaceClaims},
+ * which is the one check this function cannot make (see there for why).
+ */
+export function defineSurface(input: Surface): Surface {
+  const { key, trust, subtree } = input;
+  const parsed = typeof key === "string" ? parseSurfaceKeyEntry(key) : undefined;
+  if (!parsed) {
+    throw new Error(
+      `defineSurface: malformed surface key ${JSON.stringify(key)} — expected "<platform>/<tenant>", "<platform>/<tenant>/<surface>", a same-level glob "<platform>/<tenant>/<prefix>*" (ONE trailing "*", last segment only), or a group rung "<platform>/<tenant>/<marker>:<id>" (e.g. "teams/<tenantId>/team:<teamId>")`,
+    );
+  }
+  if (!KNOWN_TRUST.has(trust)) {
+    throw new Error(
+      `defineSurface: unknown trust ${JSON.stringify(trust)} for surface "${key}" — known: ${[...KNOWN_TRUST].map((t) => JSON.stringify(t)).join(", ")}. "external" is NOT a value: it is the fail-closed default of an unlisted surface, and "public" is how an operator DECLARES a room external.`,
+    );
+  }
+  if (subtree !== undefined && typeof subtree !== "boolean") {
+    throw new Error(
+      `defineSurface: subtree must be a boolean for surface "${key}", not ${JSON.stringify(subtree)}. Write \`subtree: true\` to vouch the whole subtree, or leave it out to vouch that one surface.`,
+    );
+  }
+  // `false` and absent are the SAME declaration (one surface), so the field is dropped rather than
+  // stored: a caller reading back the register then sees the claim only where one was made.
+  if (subtree !== true) return { key, trust };
+  if (parsed.kind !== "surface" || parsed.glob) {
+    throw new Error(
+      `defineSurface: subtree: true needs ONE EXACT surface key, and "${key}" is not one (it is a ${parsed.kind === "tenant" ? "whole tenant" : parsed.kind === "group" ? "group rung" : "same-level glob"}). A tenant already covers every surface under it at any depth, and a glob names a set nobody enumerated — neither leaves a subtree to walk. Name the one surface the subtree hangs from.`,
+    );
+  }
+  if (trust !== "internal") {
+    throw new Error(
+      `defineSurface: subtree: true is only declarable with trust: "internal", not ${JSON.stringify(trust)} (surface "${key}"). The subtree form exists to PROMOTE a set of surfaces the key cannot name, and only the promotion has a resolver — a platform's subtree walk answers "is this under a declared root?". A "public" subtree would be a demotion nothing reads, so it is refused instead of accepted and ignored.`,
+    );
+  }
+  return { key, trust, subtree: true };
+}
+
+/** A registered entry with its parse cached — every read matches against the parse, never the
+ *  string, so the resolver and the boot-time overlap proof cannot disagree about a key. */
+interface RegisteredSurface {
+  readonly surface: Surface;
+  readonly parsed: SurfaceKeyEntry;
+  /** Higher = more specific. See surfaceKeyEntrySpecificity. */
+  readonly specificity: number;
+}
+
+// The register, in DECLARATION ORDER (the resolver's within-tier tiebreak). Empty until the app
+// registers at boot ⇒ nothing declared (fail-closed). A register call REPLACES it.
+let surfaces: readonly RegisteredSurface[] = [];
+
+/**
+ * Register the deploy's declared surfaces (app boot; a later call REPLACES the previous register —
+ * same convention as registerModelPricing). Pass the full list each time.
+ *
+ * Fail-LOUD on two kinds of self-contradiction, both checked BEFORE the register is swapped in:
+ *  1. the same key listed twice with DIFFERENT trust (a duplicate with the same trust is
+ *     idempotent and harmless);
+ *  2. two entries at the SAME specificity tier whose patterns could match ONE key with DIFFERENT
+ *     values — e.g. `github/acme/pay-*` public vs `github/acme/payments-*` internal. Most-specific-
+ *     wins breaks a cross-TIER tie by construction; a within-tier tie would be decided by
+ *     declaration order, which is a coin flip wearing a config's clothes. Decidable because the
+ *     pattern language is one trailing `*` (surface-key-grammar.ts surfaceKeyEntriesIntersect) —
+ *     the same argument memory/domain.ts's assertChannelExclusivity makes.
+ */
+export function registerSurfaces(input: Iterable<Surface>): void {
+  const next: RegisteredSurface[] = [];
+  for (const raw of input) {
+    // Conflict is checked against the already-validated prior entry at this key BEFORE
+    // re-validating, so two lines that disagree on trust fail as a self-contradiction (not as a
+    // trust-validation error on the second). A duplicate key with the SAME trust falls through.
+    const existing = next.find((e) => e.surface.key === raw.key);
+    if (existing && existing.surface.trust !== raw.trust) {
+      throw new Error(
+        `registerSurfaces: conflicting trust for surface "${raw.key}" — ${JSON.stringify(existing.surface.trust)} vs ${JSON.stringify(raw.trust)}. A key may be listed once; a reviewed config must not contradict itself.`,
+      );
+    }
+    // The SAME self-contradiction on the subtree claim: one line says "this surface" and the other
+    // says "this surface and everything under it". Idempotence only covers lines that AGREE, so the
+    // wider claim can never be swallowed by the narrower one arriving first.
+    if (existing && existing.surface.subtree !== (raw.subtree === true ? true : undefined)) {
+      throw new Error(
+        `registerSurfaces: conflicting subtree claim for surface "${raw.key}" — one line declares \`subtree: true\` and another does not. A key may be listed once; a reviewed config must not contradict itself.`,
+      );
+    }
+    const s = defineSurface(raw);
+    if (existing) continue; // same key, same trust — idempotent
+    const parsed = parseSurfaceKeyEntry(s.key)!; // defineSurface already proved it parses
+    next.push({ surface: s, parsed, specificity: surfaceKeyEntrySpecificity(parsed) });
+  }
+  for (let i = 0; i < next.length; i++) {
+    for (let j = i + 1; j < next.length; j++) {
+      const a = next[i];
+      const b = next[j];
+      if (a.specificity !== b.specificity) continue; // most-specific-wins settles it
+      if (a.surface.trust === b.surface.trust) continue; // they agree — no ambiguity to resolve
+      if (!surfaceKeyEntriesIntersect(a.parsed, b.parsed)) continue;
+      throw new Error(
+        `registerSurfaces: "${a.surface.key}" (${a.surface.trust}) and "${b.surface.key}" (${b.surface.trust}) are equally specific and can match the SAME surface with DIFFERENT trust — the winner would be declaration order, which is not a decision anyone reviewed. Narrow one of them, or make an EXACT entry for the overlap (an exact key always beats a glob).`,
+      );
+    }
+  }
+  surfaces = next;
+  // Re-hand every subtree platform its (possibly changed) keys. A platform registered BEFORE the
+  // surfaces did would otherwise hold the empty list it was handed at registration, so this is what
+  // makes the two boot orders reach the same state. No platform registered ⇒ no-op, and the
+  // unowned-claim REFUSAL still waits for applySubtreeSurfaceClaims (see there).
+  for (const [platform, handler] of subtreePlatforms) handler(subtreeSurfaceKeys(platform));
+}
+
+/** Test seam: drop the register (a fresh test must not inherit another's declarations). */
+export function _resetSurfacesForTest(): void {
+  surfaces = [];
+  // Same notification as registerSurfaces, for the same reason: a platform left holding the keys of
+  // a dropped register would carry another test's declarations into this one.
+  for (const [platform, handler] of subtreePlatforms) handler(subtreeSurfaceKeys(platform));
+}
+
+/**
+ * What a platform does with the `subtree` entries an operator declared for it — the second half of
+ * {@link registerSubtreePlatform}. It receives every declared key for that platform, in declaration
+ * order, and it may THROW: a key this registry accepts can still be wrong in a way only the vendor
+ * knows (a Notion key whose last segment is not a page id), and that must be a boot error the
+ * operator reads rather than a line they assume is covered.
+ */
+export type SubtreeSurfaceHandler = (keys: readonly string[]) => void;
+
+/** Platform id → its handler. Empty until a bundle registers ⇒ no platform honours `subtree` ⇒
+ *  every claim is a boot error. Fail-closed in the direction that refuses, not the one that
+ *  silently grants. */
+const subtreePlatforms = new Map<string, SubtreeSurfaceHandler>();
+
+/**
+ * THE CAPABILITY SEAM (OPE-539): "this platform honours `subtree`, and here is what to do with the
+ * entries that carry it". A provider bundle calls this from its own `registerXProvider()`; core
+ * names no vendor, so a deployment that de-selects the bundle also removes the capability and every
+ * `subtree` claim for it becomes the boot error it should be.
+ *
+ * Gated on the provider selection like every other platform-keyed registration seam — an unselected
+ * bundle cannot declare a capability, so the refusal path is the same one every other registry uses.
+ *
+ * A later call for the same platform REPLACES the handler (the registerSurfaces convention). The
+ * handler runs IMMEDIATELY against whatever is already registered, and again on every subsequent
+ * {@link registerSurfaces}, so the two boot orders (surfaces-then-bundles, bundles-then-surfaces)
+ * reach the same state. Only the REFUSAL of an unowned claim has to wait for the last bundle — that
+ * is {@link applySubtreeSurfaceClaims}.
+ */
+export function registerSubtreePlatform(platform: string, handler: SubtreeSurfaceHandler): void {
+  if (!admitProviderRegistration(platform, "subtree-surfaces")) return;
+  subtreePlatforms.set(platform, handler);
+  handler(subtreeSurfaceKeys(platform));
+}
+
+/** Test seam: drop the capability registry (a fresh test must not inherit another's platforms). */
+export function _resetSubtreePlatformsForTest(): void {
+  subtreePlatforms.clear();
+}
+
+/** The keys of every `subtree: true` entry for one platform, in declaration order. The input a
+ *  {@link SubtreeSurfaceHandler} receives, exposed by name so a bundle can also re-read it. */
+export function subtreeSurfaceKeys(platform: string): readonly string[] {
+  return surfaces.filter((e) => e.surface.subtree === true && e.parsed.platform === platform).map((e) => e.surface.key);
+}
+
+/**
+ * THE BOOT CHECK for the `subtree` claim — call it ONCE, after BOTH the surfaces register and every
+ * provider bundle has registered. It does two things and throws on either:
+ *
+ *  1. REFUSES a `subtree: true` entry whose platform never declared the capability. This is the
+ *     check that cannot be made earlier and cannot be made by `defineSurface`: the app registers its
+ *     surfaces before the provider bundles register (agent/agent.ts imports register-config.ts ahead
+ *     of register-adapters.ts), so at `defineSurface` time the capability registry is still empty and
+ *     an eager refusal would reject every legal claim. Deferring the decision to one explicit boot
+ *     call is the same shape, and the same boot-order reason, as `assertConnectorMemoryGrants`.
+ *  2. HANDS each platform its own keys, so the vendor's own key validation is a boot error too.
+ *
+ * 🔴 SKIPPING THIS CALL IS THE ONE WAY A CLAIM GETS ACCEPTED AND IGNORED. It is wired in
+ * agent/lib/register-adapters.ts, after the bundle loop and beside `assertConnectorMemoryGrants`.
+ * `scripts/boot-smoke-test.ts` loads that module, so a throw from here fails the cold-start gate —
+ * but nothing detects the call being DELETED, which is the same residual `assertConnectorMemoryGrants`
+ * carries. The failure direction is closed (no roots, no promotion), not open.
+ */
+export function applySubtreeSurfaceClaims(): void {
+  const unowned = surfaces.filter((e) => e.surface.subtree === true && !subtreePlatforms.has(e.parsed.platform));
+  if (unowned.length > 0) {
+    const platforms = [...new Set(unowned.map((e) => e.parsed.platform))].sort();
+    throw new Error(
+      `applySubtreeSurfaceClaims: subtree: true is declared on ${unowned.map((e) => JSON.stringify(e.surface.key)).join(", ")}, but ${platforms.map((p) => JSON.stringify(p)).join(", ")} does not honour it. A surface key on that platform already names a whole room, so there is no subtree to walk and the line would grant nothing. Either the entry means one surface — drop \`subtree\` — or the bundle that honours it is not selected by this deployment (roster.config.ts).`,
+    );
+  }
+  for (const [platform, handler] of subtreePlatforms) handler(subtreeSurfaceKeys(platform));
+}
+
+/**
+ * The keys one binding can be declared at, MOST SPECIFIC FIRST within each grain. Every trust read
+ * goes through this shape so the grains cannot drift apart between callers.
+ */
+export interface SurfaceTrustQuery {
+  /** `platform/tenant` — memory/partition.ts's workspaceKey. */
+  readonly tenantKey: string;
+  /**
+   * Surface-grain keys (`platform/tenant/surface`), MOST SPECIFIC FIRST. Usually one. A provider
+   * whose DOMAIN grain differs from its raw surface grain (a Discord thread inside a channel, a
+   * Teams conversation inside a channel) passes both — raw first, container second — so a
+   * declaration written on the container still reaches the room inside it.
+   */
+  readonly surfaceKeys: readonly string[];
+  /**
+   * The GROUP-grain key (`platform/tenant/<marker>:<id>`), when the platform has a container the
+   * surface key does not carry. Teams contributes `teams/<tenant>/team:<teamId>` (OPE-490).
+   * Optional and absent everywhere else — a platform with no intermediate rung passes nothing and
+   * the tier is simply skipped.
+   */
+  readonly groupKey?: string;
+  /**
+   * The ENTERPRISE-grain key (`platform/<enterpriseId>`) — a rung ABOVE the tenant, for a platform
+   * whose workspaces sit inside a larger organisation the workspace key does not name. Slack
+   * Enterprise Grid contributes `slack/E<enterpriseId>` (OPE-1508). Optional and absent everywhere
+   * else.
+   *
+   * 🔴 IT IS SPELLED AS A TENANT ENTRY, and that is why it needs no grammar of its own. A Grid
+   * enterprise id occupies the same slot a workspace id does, so `slack/E0GRID` parses as
+   * `kind: "tenant"` and one `defineSurface` line declares it. What this field adds is the WALK: a
+   * binding in workspace `T0SIB` also asks the register about `slack/E0GRID`, so one enterprise
+   * declaration vouches every workspace under it (Tommy's ruling, 2026-09-07).
+   *
+   * 🔴 THE WORKSPACE RUNG WINS, because it is the more specific statement about the room. Both keys
+   * parse at the same specificity tier, so the resolver's SECOND tiebreak decides — the caller's key
+   * order, and this key is passed LAST. So `slack/T0SIB` public under `slack/E0GRID` internal binds
+   * that workspace `external`, exactly as a surface-grain carve-out narrows a tenant. The reverse
+   * (`slack/E0GRID` public, `slack/T0SIB` internal) leaves the declared workspace internal: a rung
+   * declaration never overrides the narrower line an operator wrote beneath it.
+   */
+  readonly enterpriseKey?: string;
+}
+
+/**
+ * THE ONE RESOLVER. The operator's declaration for a surface, or `undefined` when they declared
+ * nothing about it. MOST SPECIFIC WINS:
+ *
+ *   1. an exact surface entry            `slack/T0ACME/C0BOARD`
+ *   2. a same-level surface glob         `github/acme/payments-*`
+ *   3. a group entry                     `teams/T0/team:<teamId>`      (exact or globbed)
+ *   4. a tenant entry                    `slack/T0ACME`
+ *   5. an enterprise entry               `slack/E0GRID`                (the rung ABOVE the tenant)
+ *   6. nothing                           ⇒ undeclared
+ *
+ * 🔴 RUNGS 4 AND 5 SHARE A SPECIFICITY TIER, so the ORDER of `keys` below is what separates them —
+ * see {@link SurfaceTrustQuery.enterpriseKey}. An enterprise entry is a tenant entry by grammar; it
+ * is a lower rung only because the caller offers it last.
+ *
+ * Same tier order as memory/domain.ts's `resolveDomainForChannel`, for the same reason: an
+ * explicitly-listed surface can never be ANNEXED by a broader pattern. That is the property
+ * notion-scope.ts was built to preserve on the ACL plane, and it transfers unchanged.
+ *
+ * Within a tier the earliest declaration wins — and `registerSurfaces` has already proved at boot
+ * that no two same-tier entries which could match one key DISAGREE, so that tiebreak can only ever
+ * pick between entries that say the same thing.
+ *
+ * 🔴 UNDECLARED RETURNS `undefined`, NEVER `"public"`. The registry is assertion-only: silence
+ * means "the operator has not declared", which is not the same claim as "the operator declared this
+ * public". Manufacturing `"public"` from silence would erase exactly the distinction the audit
+ * trail exists to keep — see the module header.
+ *
+ * PURE and SYNCHRONOUS, no I/O. Trust is upstream of authorization, so it inherits domain.ts's
+ * purity contract rather than a looser one.
+ */
+export function declaredSurfaceTrust(q: SurfaceTrustQuery): SurfaceTrust | undefined {
+  // Every candidate key, most preferred first. `surfaceKeys` is already in preference order; the
+  // group key and the tenant key follow, and their own tiers are lower anyway. The ENTERPRISE key
+  // is last, which is the ONLY thing that ranks it under the tenant — the two parse to the same
+  // `kind: "tenant"` shape and therefore to the same specificity.
+  const keys = [
+    ...q.surfaceKeys,
+    ...(q.groupKey === undefined ? [] : [q.groupKey]),
+    q.tenantKey,
+    ...(q.enterpriseKey === undefined ? [] : [q.enterpriseKey]),
+  ];
+  let best: { readonly trust: SurfaceTrust; readonly specificity: number; readonly keyIndex: number } | undefined;
+  for (const e of surfaces) {
+    for (let keyIndex = 0; keyIndex < keys.length; keyIndex++) {
+      if (!surfaceKeyEntryMatches(e.parsed, keys[keyIndex])) continue;
+      // Rank: specificity first (an exact key beats a glob beats a group beats a tenant), then the
+      // CALLER's key preference (a raw surface key beats the container it sits in), then declaration
+      // order — which registerSurfaces has already proved can only pick between entries that agree.
+      const better =
+        best === undefined ||
+        e.specificity > best.specificity ||
+        (e.specificity === best.specificity && keyIndex < best.keyIndex);
+      if (better) best = { trust: e.surface.trust, specificity: e.specificity, keyIndex };
+      break; // this entry's best match is its first matching key — later keys are less preferred
+    }
+  }
+  return best?.trust;
+}
+
+/**
+ * The declaration for a plain (workspaceKey, surfaceKey) pair — the shape most callers hold. Kept
+ * as a named function rather than an inline object literal so the two-grain question is asked one
+ * way everywhere.
+ */
+export function declaredTrustForKeys(workspaceKey: string, surfaceKey: string): SurfaceTrust | undefined {
+  return declaredSurfaceTrust({ tenantKey: workspaceKey, surfaceKeys: [surfaceKey] });
+}
+
+/**
+ * Has the operator declared this surface INTERNAL? True only when the most-specific declaration that matches it says `internal`, so a `public` carve-out under an internal tenant correctly reports NOT internal.
+ * Fail-closed: an empty or unregistered register means nothing is declared here and the caller falls through to the platform default, which is external for real platforms. Never throws.
+ */
+export function isVouchedInternal(workspaceKey: string, surfaceKey: string): boolean {
+  return declaredTrustForKeys(workspaceKey, surfaceKey) === "internal";
+}
+
+/**
+ * The privacy floor for a caller that holds the SURFACE KEY alone. It walks the declaration rungs, so a tenant line vouches every room under that tenant — a cross-tenant Teams Connect or shared room included, because an inbound activity usually omits membershipType and an absent signal does not demote. Only a positive external signal refuses a vouched surface.
+ * `opts` supplies the container and group rungs the caller cannot derive, but never the enterprise rung, so this floor can answer false where bindFrom binds internal; that divergence is fail-closed and recorded in FLOOR_UNREACHABLE_RUNGS. Supplying a rung can promote as well as demote.
+ */
+export function isVouchedSurface(
+  surfaceKey: string,
+  opts?: {
+    /** The CONTAINER-grain key, when the caller's domain grain differs from its surface grain
+     *  (a Teams reply chain inside a channel) — the second entry of `bindFrom`'s own `surfaceKeys`,
+     *  and less preferred than `surfaceKey`, exactly as there. */
+    readonly containerKey?: string;
+    /** The GROUP-grain key (`platform/tenant/<marker>:<id>`), for a platform with a rung between
+     *  the tenant and the surface. Teams contributes `teams/<tenant>/team:<teamId>`. */
+    readonly groupKey?: string;
+  },
+): boolean {
+  const containerKey = opts?.containerKey;
+  return (
+    declaredSurfaceTrust({
+      tenantKey: tenantKeyOfSurfaceKey(surfaceKey),
+      // Raw grain first, container second — `SurfaceTrustQuery.surfaceKeys` is in preference order,
+      // and this is the order binding.ts uses. A container key equal to the surface key is dropped
+      // rather than passed twice: a duplicate would change no answer, but it would make the query
+      // read as if two grains had been consulted.
+      surfaceKeys: containerKey === undefined || containerKey === surfaceKey ? [surfaceKey] : [surfaceKey, containerKey],
+      ...(opts?.groupKey === undefined ? {} : { groupKey: opts.groupKey }),
+    }) === "internal"
+  );
+}
+
+/**
+ * The {@link SurfaceTrustQuery} rungs {@link isVouchedSurface} SUPPLIES: the tenant it derives from
+ * the key, the one or two surface grains it is handed, and the optional group.
+ */
+type FloorSuppliedRung = "tenantKey" | "surfaceKeys" | "groupKey";
+
+/**
+ * Every SurfaceTrustQuery rung bindFrom passes that isVouchedSurface does not, keyed by field name, with what the gap costs. A new field on SurfaceTrustQuery must be named here or in FloorSuppliedRung or the compiler refuses, which forces the author to classify it.
+ * It checks the CLASSIFICATION, never the code, so it buys a forced decision and not a proof. The proof is scripts/surface-trust-test.ts, which drives both readers over one Grid declaration and pins the answers apart.
+ */
+export const FLOOR_UNREACHABLE_RUNGS: Readonly<Record<Exclude<keyof SurfaceTrustQuery, FloorSuppliedRung>, string>> = {
+  enterpriseKey:
+    "a Grid enterprise id sits ABOVE the workspace and appears in no surface key, so a reader holding one key cannot derive it — `bindFrom` reads it off the event envelope instead (identity/binding.ts `trustEnterpriseKey`). FAIL-CLOSED: a Grid-only declaration binds every workspace under it internal, and this floor answers `false` for the same room.",
+};
+
+/**
+ * The `platform/tenant` rung a surface key sits under. memory/domain.ts assertWindowSourcesVouched takes the same two-segment slice by hand; the two copies are kept in step by review, and nothing tests them together.
+ * It changes no answer — a tenant entry already matches a surface key at any depth — so do not read it as a guard. What it buys is a well-formed query, because SurfaceTrustQuery.tenantKey means the tenant rung.
+ */
+function tenantKeyOfSurfaceKey(surfaceKey: string): string {
+  return surfaceKey.split("/").slice(0, 2).join("/");
+}
+
+/**
+ * The bound WORKSPACE's declared tier, the input access/taint-tiers.ts needs. Workspace grain only: a page- or channel-level declaration says nothing about the workspace, and a read tool commonly reads a different page from the one the session sits on.
+ * Undeclared still returns undefined, never "public". Pass enterpriseKey to walk the Slack Grid rung above the workspace; the workspace's own declaration still wins.
+ */
+export function declaredWorkspaceTrust(workspaceKey: string, enterpriseKey?: string): SurfaceTrust | undefined {
+  return declaredSurfaceTrust({
+    tenantKey: workspaceKey,
+    surfaceKeys: [workspaceKey],
+    ...(enterpriseKey === undefined ? {} : { enterpriseKey }),
+  });
+}
+
+/**
+ * Every registered entry, in declaration order — the one diagnostic read and the preflight's input. Read-only: a caller cannot mutate the register through it.
+ * A caller asking whether a surface is internal must call isVouchedInternal instead. Matching these entries at either grain by hand misses a `public` carve-out under an internal tenant, so a room declared open to the world would read as vouched.
+ */
+export function registeredSurfaces(): readonly Surface[] {
+  return surfaces.map((e) => e.surface);
+}
+
+/**
+ * Memo TTL for a LIVE trust verification, ms — the identity.dmTrustTtlMs setting. It resolves FRESH per call rather than once at import, and callers use it only as an expiry, so a re-read moves an expiry and never a verdict and a shortened TTL takes effect on a warm process.
+ * Every miss re-verifies against the platform and every failure fails closed, so this TTL bounds how long a stale-but-positive verdict can survive.
+ */
+export function dmTrustTtlMs(): number {
+  return getSettings().identity.dmTrustTtlMs;
+}

package/agent/identity/wake-trust.ts

@@ -0,0 +1,217 @@
+// Assigns one wake's trust tier: `principal` for an author on the org or domain admin roster, `peer` for an identified human on a confirmed-internal surface, `unauth` for a human the gate cannot vouch, and `relay` for any machine author. Every uncertainty resolves DOWN, never up.
+
+import type { WakeTrust } from "../channels/wake-envelope.js";
+import type { BackscrollTrustFor, NormalizedMessage } from "../channels/backscroll-window.js";
+import type { BindableContext } from "./binding.js";
+import { bindFrom } from "./binding.js";
+import { criteriaDomain, domainForChannel, type Domain } from "../memory/domain.js";
+import { rosterHasPrincipal } from "./principal-key.js";
+import { getConfig } from "../access/config.js";
+import { parseScopeKey } from "../access/scope-key.js";
+import { isAllowlistedDriverAuthor } from "../testing/driver-allowlist.js";
+
+/** The facts one wake's trust tier is decided from — all already in hand at every dispatch
+ *  site (nothing here requires a new lookup). */
+export interface WakeTrustFacts {
+  /** The triggering message was authored by a bot / app / webhook / another agent session
+   *  (any non-human sender). Always `relay` — machine-authored content never speaks with
+   *  member (let alone admin) standing. */
+  readonly authorIsBot: boolean;
+  /** The author's raw platform principal id (Slack member id, GitHub login, Linear/Notion
+   *  user id) — the NATIVE half of the `platform/<id>` key Domain.admins lists; the platform
+   *  half comes from the wake's surface (see {@link wakeAuthorIsAdmin}). Absent/unresolvable on a HUMAN author →
+   *  `unauth` (fail-closed: an unidentifiable human can't be vouched as a member, but is still a
+   *  human, not the machine `relay` floor). */
+  readonly authorId?: string;
+  /** The existing surface trust gate's verdict for THIS wake's surface: true only when the
+   *  surface was POSITIVELY confirmed internal (Slack's conversations.info check, a mapper
+   *  verdict, an operator vouch / OE_TRUST). false/unknown on a HUMAN author → `unauth` (the same
+   *  fail-closed posture the memory gate takes — external and unverified are treated alike, and
+   *  an unvouched human is reference-only, never peer). */
+  readonly surfaceInternal: boolean;
+  /** Roster verdict: the author is on the org admin roster or this channel's domain admin
+   *  roster (see {@link wakeAuthorIsAdmin}). Only consulted for internal humans. */
+  readonly authorIsAdmin: boolean;
+  /** This BOT author is an EXPLICITLY allowlisted e2e test driver (agent/testing/driver-allowlist.ts —
+   *  OE_TEST_DRIVER_IDS, default EMPTY). The ONE narrow relay→peer lift: an admitted driver bot posts
+   *  as a fixture "user" so the governance legs it drives arrive at PEER — never `principal` (the bot
+   *  branch returns BEFORE any roster check, so the lift can only ever produce peer), matching the
+   *  human-token Slack driver's standing. Posture PARITY for fixtures, not a weakening of the default:
+   *  unset env ⇒ empty allowlist ⇒ always false ⇒ every bot is `relay`, byte-identical to before. */
+  readonly isAllowlistedDriver?: boolean;
+}
+
+/**
+ * Pure tier decision. FAIL-CLOSED, always DOWN: a MACHINE author is `relay` (the absolute
+ * floor); a HUMAN the gate can't vouch (no id, or an unconfirmed surface) is `unauth`
+ * (reference-only, below peer); `principal` requires a positive roster hit on an identified
+ * human on a confirmed-internal surface — never a default. Uncertainty never resolves UP.
+ */
+export function wakeTrustFor(f: WakeTrustFacts): WakeTrust {
+  // The machine floor. The allowlisted-driver lift returns from inside this branch, before any roster check, so it can only ever produce `peer` — never `principal`.
+  if (f.authorIsBot) return f.isAllowlistedDriver ? "peer" : "relay";
+  if (!f.authorId) return "unauth"; // human but unidentifiable — unvouched, fail closed down
+  if (!f.surfaceInternal) return "unauth"; // human on an external / unverified surface — unvouched
+  return f.authorIsAdmin ? "principal" : "peer";
+}
+
+/**
+ * Is this author on the admin roster that applies to this channel? Mirrors
+ * access/roles.ts roleForBinding exactly (same config, same key form): the `org`
+ * pseudo-domain's admins are admins everywhere; an explicit domain's admins hold on the
+ * channels that resolve to it via `channelKey` (`platform/workspace/<domain-grain
+ * surface>` — memory/partition.ts's domainKey form). FAIL-CLOSED: no author id, no
+ * channel key match, or no rosters configured all read as "not an admin".
+ *
+ * A roster entry is the qualified principal key, and EVERY namespace half of it comes from the
+ * WAKE'S OWN SURFACE — the platform, and on a tenant-scoped platform the WORKSPACE, that
+ * `channelKey` NAMES, read through access/scope-key.ts — never from inspecting the id. That is
+ * also why an absent (or platform-less, or malformed) `channelKey` fails closed even for an ORG
+ * admin: with no surface there is no namespace to qualify the author in, and guessing one is
+ * precisely the cross-vendor — and, since OPE-309, cross-WORKSPACE — match the qualified form
+ * exists to delete. Every live wake site passes a channel key (it is built from the binding), so
+ * this narrowing costs nothing real.
+ */
+export function wakeAuthorIsAdmin(
+  authorId: string | undefined,
+  channelKey: string | undefined,
+  domains: readonly Domain[],
+): boolean {
+  if (!authorId || !channelKey) return false;
+  // BOTH namespace halves of the roster key, read through the ONE reader of the scope-key grammar
+  // (access/scope-key.ts) rather than a hand-rolled `split("/")`. That expression is right for
+  // `platform/workspace/surface` and WRONG for the grammar's third shape — a bare DOMAIN name, which
+  // it reads as a platform, so `payments` + `U123` would compose the roster key `payments/U123` for a
+  // vendor that does not exist. The parser answers a `domain` (or `malformed`) shape there instead
+  // of confidently wrong, and `rosterHasPrincipal` already fails closed on `undefined` — so an
+  // unqualifiable author simply is not an admin. ONE parse feeds both halves, so they cannot end up
+  // disagreeing about the same key.
+  const parsed = parseScopeKey(channelKey);
+  const platform = parsed.kind === "tenant" || parsed.kind === "surface" || parsed.kind === "principal" ? parsed.platform : undefined;
+  // The TENANT half of the roster key, from the same parse (OPE-309). A channel key that names no
+  // workspace leaves it undefined, and `rosterHasPrincipal` fails closed on that for a
+  // tenant-scoped platform exactly as it does on a missing platform.
+  const tenant = parsed.kind === "tenant" || parsed.kind === "surface" ? parsed.workspace : undefined;
+  // 🔴 ADMIN IS EXACT-ID ONLY. A roster entry is a `platform/<id>` key — never a `linkSet:<id>` ref
+  // (config load rejects those on admin rosters; admin standing is static/diff-auditable with no
+  // runtime link-set store read on this synchronous wake-pipeline gate).
+  const admits = (roster: readonly string[] | undefined): boolean =>
+    rosterHasPrincipal(roster, platform, tenant, authorId);
+  if (admits(criteriaDomain("org", domains)?.admins)) return true;
+  return admits(domainForChannel(channelKey, domains)?.admins);
+}
+
+/** The configured domains, or [] when the app config isn't registered (tests, partial
+ *  boots). A missing config means no rosters — nobody resolves `principal`, which is the
+ *  fail-closed direction (a wake must never fail, and never guess an admin). */
+export function loadDomainsForWakeTrust(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve one wake's trust tier from surface facts a route already holds (the Slack routes'
+ * confirmInternal verdict + the event's author facts). `domains` is injectable for tests;
+ * the live callers let it default to the registered config.
+ */
+export function resolveWakeTrust(input: {
+  readonly authorIsBot: boolean;
+  readonly authorId?: string;
+  /** The route's positive internal confirmation for this surface (fail-closed upstream). */
+  readonly surfaceInternal: boolean;
+  /** Domain-grain channel key (`platform/workspace/surface`) for domain-admin matching. */
+  readonly channelKey?: string;
+  readonly domains?: readonly Domain[];
+  /** Injectable for tests; the live callers let it default to the env-parsed set inside
+   *  {@link isAllowlistedDriverAuthor}. */
+  readonly driverAllowlist?: ReadonlySet<string>;
+}): WakeTrust {
+  const domains = input.domains ?? loadDomainsForWakeTrust();
+  // The channelKey's workspace segment and the author id form the `workspace:authorId` pair the driver allowlist stores, so an admitted driver bot resolves `peer` instead of the `relay` floor. Split-on-slash is safe: only the trailing surface segment can contain a slash, so index 1 is always the workspace.
+  const workspace = input.channelKey?.split("/")[1];
+  const isAllowlistedDriver = isAllowlistedDriverAuthor(workspace, input.authorId, input.driverAllowlist);
+  return wakeTrustFor({
+    authorIsBot: input.authorIsBot,
+    authorId: input.authorId,
+    surfaceInternal: input.surfaceInternal,
+    authorIsAdmin: wakeAuthorIsAdmin(input.authorId, input.channelKey, domains),
+    isAllowlistedDriver,
+  });
+}
+
+/**
+ * Resolve one wake's trust tier from a dispatch-time auth context (the non-Slack ambient
+ * legs, which build the SAME auth capture the mention path uses): the surface verdict is
+ * the canonical binding gate (bindFrom → trust, which composes the platform mapper's
+ * verdict, the per-surface vouch register, and OE_TRUST — fail-closed to external), and
+ * the channel key is the binding's own domain-grain key. Never throws: any resolution
+ * failure returns `relay` (the fail-closed floor), because a wake must not die on a
+ * trust lookup.
+ *
+ * FAIL-CLOSED on bot-ness: an author whose human-ness the caller can't POSITIVELY assert
+ * (`isBot` left undefined) is treated as a machine author → `relay`. Only `isBot === false`
+ * grants a human standing (peer/principal, or `unauth` when the human can't be vouched). Every
+ * live caller determines person-ness from its platform facts (GitHub `authorType`, Notion
+ * `created_by.type`, …) and passes it.
+ *
+ * `principalFallback` (opts): ONLY a TRIGGER call site — where the wake's author IS the
+ * bound principal — may fall back to `binding.principalId` when the author id is otherwise
+ * absent. PER-MESSAGE (backscroll sibling) resolution must NOT: a sibling has its own
+ * author, and substituting the trigger's principal id would render an unattributed sibling
+ * as the trigger author's tier (e.g. `principal` for a nameless comment under an admin's
+ * trigger). Defaults OFF (the safe per-message posture); trigger callers opt in.
+ */
+export function resolveWakeTrustFromContext(
+  ctx: BindableContext,
+  author: { readonly id?: string; readonly isBot?: boolean },
+  opts?: { readonly principalFallback?: boolean; readonly domains?: readonly Domain[] },
+): WakeTrust {
+  try {
+    const binding = bindFrom(ctx);
+    // Fail-closed: undefined bot-ness is treated as a bot (relay), never as a human.
+    const authorIsBot = author.isBot !== false;
+    // Principal fallback is trigger-only (author == principal); off for sibling resolution.
+    const authorId = author.id ?? (opts?.principalFallback === true ? binding.principalId : undefined);
+    return resolveWakeTrust({
+      authorIsBot,
+      authorId,
+      surfaceInternal: binding.trust === "internal",
+      channelKey: `${binding.platform}/${binding.workspace}/${binding.domainSurface ?? binding.surface}`,
+      domains: opts?.domains,
+    });
+  } catch {
+    return "relay"; // fail-closed floor — never up
+  }
+}
+
+/**
+ * Build a per-message backscroll trust resolver (backscroll-window.ts BackscrollTrustFor) that a
+ * supervisor first-wake fetch wires so every backscroll SIBLING gets its real tier instead of a
+ * constant (audit-wedge F3 — the "every backscroll message renders as an authorized peer" bug). The
+ * caller passes the SAME surface facts it already holds: the confirmInternal verdict and the
+ * domain-grain channelKey (for domain-admin → principal matching).
+ *
+ * Sender mapping — only a genuine `human` can reach a human tier; `self` (the bot's OWN prior post)
+ * and a foreign `bot` are MACHINE authors, so both take `authorIsBot: true` → the `relay` floor
+ * (the same tier a bot author gets at a trigger site, and what a self post should read as — routing
+ * a self post through the human branch would misread its absent authorId as `unauth`, an
+ * external-human tier that mislabels OUR own words). No `principalFallback`: a sibling has its own
+ * author and must never borrow the trigger's principal id (see resolveWakeTrustFromContext).
+ */
+export function backscrollTrustResolver(surface: {
+  readonly surfaceInternal: boolean;
+  readonly channelKey?: string;
+  readonly domains?: readonly Domain[];
+}): BackscrollTrustFor {
+  return (m) =>
+    resolveWakeTrust({
+      authorIsBot: m.sender !== "human", // self + foreign bot → the machine relay floor
+      authorId: m.authorId,
+      surfaceInternal: surface.surfaceInternal,
+      channelKey: surface.channelKey,
+      domains: surface.domains,
+    });
+}