@open-everywhere/core 0.1.0

package/agent/access/lint.ts

@@ -0,0 +1,638 @@
+// The config lints on the credential plane, pure so the CI gate and the tests both run them over any config. They are policy gates for deliberate-but-dangerous config, unlike assertBundlesValid's objective-misconfig checks, and each reports every problem rather than the first.
+
+import { connectorGrantCredential, connectorGrantName, egressHostsOverlap, normaliseEgressHost, type Binding, type Bundle, type Scope } from "./bundle.js";
+import { GIT_BROKER_HOSTS, RESERVED_BROKER_HOST_REASON } from "./reserved-hosts.js";
+import { isLinkSetRef } from "../identity/link-set-ref.js";
+import type { ConnectorCredentials } from "./connector-credentials.js";
+import { resolveAccess, type EffectiveAccess } from "./resolver.js";
+import type { PluginRegistry } from "../plugins/types.js";
+import { parseSurfaceKeyEntry, surfaceKeyEntryContains } from "../identity/surface-key-grammar.js";
+// Type-only (erased at runtime, so no import cycle): the lint's verdict on a `domain`
+// binding depends on whether that domain's membership is a roster or a tenant claim.
+import { domainContainers, resolveDomainForChannel, type Domain } from "../memory/domain.js";
+import { isLinkSetMember, type Group } from "../identity/groups.js";
+
+/** The member count at which a credentialed group binding stops being a couple of teammates sharing a key and needs an acknowledgement. The number is a judgement, set where the reviewed-diff argument stops carrying its own weight; the escape is cheap on purpose. */
+export const GROUP_BROAD_MEMBERS = 8;
+
+/** The credentialed capability a bundle carries, named per field — empty = credential-less. */
+function credentialedFields(bundle: Bundle): string[] {
+  const fields: string[] = [];
+  if (bundle.connections?.length) fields.push(`${bundle.connections.length} connection(s)`);
+  if (bundle.repos?.length) fields.push(`${bundle.repos.length} repo(s)`);
+  if (bundle.connectors?.length) fields.push(`${bundle.connectors.length} connector credential(s)`);
+  if (bundle.awsRoles?.length) fields.push(`${bundle.awsRoles.length} AWS role(s)`);
+  return fields;
+}
+
+/** The domains whose membership is a claim rather than an enumerated roster. Width here is whether the list can grow with no diff, so a same-level glob counts too, and a reach holding both exact keys and containers is decided by its widest part. */
+function tenantClaims(domains: readonly Domain[]): Map<string, readonly string[]> {
+  const claims = new Map<string, readonly string[]>();
+  for (const d of domains) {
+    const containers = domainContainers(d);
+    if (containers.length > 0) claims.set(d.name, containers);
+  }
+  return claims;
+}
+
+/** Why a person-group counts as broad for a credentialed binding: it holds a link-set member, whose expansion into DMs grows with no diff, or it holds GROUP_BROAD_MEMBERS or more members. Exported because the self-serve grant path must ask the same question at propose time. */
+export function groupWidth(group: Group | undefined): string | undefined {
+  if (!group) return undefined;
+  const sets = group.members.filter(isLinkSetMember).length;
+  if (sets > 0) {
+    // Link-set expansion is live: the DM connector gate resolves through the awaitable expander, so this message must never describe such members as inert.
+    return `it has ${sets} link-set member(s) — each is a HUMAN who resolves to every account they have confirmed, so the DMs this credential reaches grow with no diff to this binding/bundle/group. This is LIVE at runtime: the DM connector gate resolves through the awaitable expander, so confirming a new account into one of these sets grants it this capability in that account's own DM with no change to any file`;
+  }
+  if (group.members.length >= GROUP_BROAD_MEMBERS) {
+    return `it has ${group.members.length} members (at or over the ${GROUP_BROAD_MEMBERS}-member threshold) — every one of them gets this capability in their own DM`;
+  }
+  return undefined;
+}
+
+/** One problem per offending binding and per misused escape. Org and tenant are broad by their address, a domain binding is broad while its domain claims a tenant with a container reach entry, and a group binding while its group is wide; domains defaults to empty, which reproduces the pre-OPE-222 verdict rather than a wrong one. */
+export function lintBroadGrants(
+  bundles: readonly Bundle[],
+  bindings: readonly Binding[],
+  domains: readonly Domain[] = [],
+  groups: readonly Group[] = [],
+): string[] {
+  const byName = new Map(bundles.map((b) => [b.name, b]));
+  const groupByName = new Map(groups.map((g) => [g.name, g]));
+  const claims = tenantClaims(domains);
+  const problems: string[] = [];
+  for (const binding of bindings) {
+    // The claim that makes a `domain` binding broad, or undefined. `scope.domain` is only
+    // populated at `domain` level (bundle.ts), so the level test is what keeps a stray
+    // `domain` field on another level from reaching in.
+    const claimed =
+      binding.scope.level === "domain" && binding.scope.domain !== undefined
+        ? claims.get(binding.scope.domain)
+        : undefined;
+    // The same shape for `group` scope: the width is a property of the named GROUP, not of the
+    // binding's own address. Undefined ⇒ the curated case (a handful of enumerated accounts).
+    const wideGroup =
+      binding.scope.level === "group" && binding.scope.group !== undefined
+        ? groupWidth(groupByName.get(binding.scope.group))
+        : undefined;
+    const broad =
+      binding.scope.level === "org" || binding.scope.level === "tenant" || claimed !== undefined || wideGroup !== undefined;
+    if (binding.allowBroad !== undefined && !broad) {
+      // A `domain` binding reaches this branch when the domain has NO tenant claim — including
+      // the case where it used to have one and the container entry was since removed. Say so,
+      // or the deployer who narrowed their own domain reads this as an unrelated regression.
+      const why =
+        binding.scope.level === "domain"
+          ? ` — a domain binding is only broad while its domain reaches a tenant with a container \`reach\` entry (agent/memory/config/domains/<name>.ts), and "${binding.scope.domain}" reaches none`
+          : binding.scope.level === "group"
+            ? ` — a group binding is only broad while its group holds a link-set member or ${GROUP_BROAD_MEMBERS}+ members (agent/identity/groups.ts), and "${binding.scope.group}" holds neither`
+            : "";
+      problems.push(
+        `binding "${binding.bundle}" (${binding.scope.level} scope) sets allowBroad but isn't a broad scope${why} — remove the escape (it suggests the binding means something it doesn't)`,
+      );
+      continue;
+    }
+    if (!broad) continue;
+    const bundle = byName.get(binding.bundle);
+    if (!bundle) continue; // assertBindingsValid owns unknown-bundle refs
+    const fields = credentialedFields(bundle);
+    if (fields.length === 0) continue; // credential-less broad grant — resolver's warn is enough
+    if (binding.allowBroad !== undefined && binding.allowBroad.trim() === "") {
+      problems.push(`binding "${binding.bundle}" (${binding.scope.level} scope) has an EMPTY allowBroad — the escape must name the reason this broad grant is deliberate`);
+      continue;
+    }
+    if (binding.allowBroad === undefined) {
+      if (wideGroup) {
+        problems.push(
+          `broad credentialed grant (person-group): bundle "${binding.bundle}" carries ${fields.join(" + ")} bound at group scope to "${binding.scope.group}" — ${wideGroup}. ` +
+            `A group grants PEOPLE: every member gets this capability in their own DM. Split the group, name the individuals with \`principal\` bindings, or accept it deliberately with allowBroad: "<reason>" on the binding (access/bundle.ts).`,
+        );
+      } else if (claimed) {
+        // Name BOTH ends. The binding is where the escape goes; the domain file is where the
+        // width actually came from, and the author may have edited only the latter.
+        problems.push(
+          `broad credentialed grant (via domain container): bundle "${binding.bundle}" carries ${fields.join(" + ")} bound at domain scope — but domain "${binding.scope.domain}" reaches ${claimed.join(", ")} as container \`reach\` entries (agent/memory/config/domains/<name>.ts), so this reaches EVERY surface those entries match, including ones created later that nobody will ever list. ` +
+            `The binding reads as narrow; the width comes from the domain. Either enumerate the domain's surfaces as exact \`reach\` entries, or NARROW the container — a same-level glob (\`platform/<tenant>/<prefix>*\`) with \`exclude\` is strictly less reach than a whole-tenant entry (OPE-417) — or accept it deliberately with allowBroad: "<reason>" on the binding (access/bundle.ts).`,
+        );
+      } else {
+        problems.push(
+          `broad credentialed grant: bundle "${binding.bundle}" carries ${fields.join(" + ")} bound at ${binding.scope.level} scope — every surface beneath it (incl. future/public ones) inherits that capability. ` +
+            `Bind it to a domain or specific surface instead, or accept it deliberately with allowBroad: "<reason>" on the binding (access/bundle.ts).`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Lint 2 — method narrowing on credentialed egress connections. Returns one problem per
+ * connection with no `methods` declaration; empty = clean. (Every Connection is
+ * credentialed by construction — credentialType + secretRef are required fields.)
+ */
+export function lintMethodNarrowing(bundles: readonly Bundle[]): string[] {
+  const problems: string[] = [];
+  for (const bundle of bundles) {
+    for (const c of bundle.connections ?? []) {
+      if (!c.methods || c.methods.length === 0) {
+        problems.push(
+          `bundle "${bundle.name}" connection "${c.id}" declares no \`methods\` — an un-narrowed credentialed connection admits GET and DELETE alike on its granted hosts. ` +
+            `Declare the methods it needs: ["GET", "HEAD"] is the read-only standard shape; name mutating methods explicitly so they're a reviewed declaration.`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/** A scope's identity as one comparable string, so two bindings pointing at the same place compare equal. Local to this lint on purpose: the resolver compares scopes by specificity, never by identity. */
+function bindingScopeKey(scope: Binding["scope"]): string {
+  return [scope.level, scope.tenant ?? "", scope.domain ?? "", scope.surface ?? "", scope.group ?? "", scope.principal ?? ""].join("\u0000");
+}
+
+/** Two grants at the SAME scope naming one connector with different credentials resolve by declaration order, which is not a decision anybody made. There is no escape hatch, because whichever key wins the other grant is dead config. */
+export function lintCredentialCollisions(bundles: readonly Bundle[], bindings: readonly Binding[]): string[] {
+  const problems: string[] = [];
+
+  for (const bundle of bundles) {
+    const byConnector = new Map<string, Set<string>>();
+    for (const grant of bundle.connectors ?? []) {
+      const credential = connectorGrantCredential(grant);
+      if (credential === undefined) continue; // the bare slug; assertBundlesValid refuses it
+      const name = connectorGrantName(grant);
+      const set = byConnector.get(name) ?? new Set<string>();
+      set.add(credential);
+      byConnector.set(name, set);
+    }
+    for (const [connector, credentials] of byConnector) {
+      if (credentials.size > 1) {
+        problems.push(
+          `bundle "${bundle.name}" grants connector "${connector}" TWICE with different credentials (${[...credentials].sort().join(", ")}) — ` +
+            `the resolver keys one credential per connector, so the winner is whichever entry is listed last. Declaration order is not a decision: name ONE credential for this connector.`,
+        );
+      }
+    }
+  }
+
+  const byName = new Map(bundles.map((b) => [b.name, b]));
+  const atScope = new Map<string, Map<string, Map<string, Set<string>>>>(); // scopeKey → connector → credential → bundles
+  for (const binding of bindings) {
+    const bundle = byName.get(binding.bundle);
+    if (!bundle) continue; // an unknown bundle is the resolver's warning to give, not this lint's
+    const scopeKey = bindingScopeKey(binding.scope);
+    const connectors = atScope.get(scopeKey) ?? new Map<string, Map<string, Set<string>>>();
+    for (const grant of bundle.connectors ?? []) {
+      const credential = connectorGrantCredential(grant);
+      if (credential === undefined) continue;
+      const name = connectorGrantName(grant);
+      const credentials = connectors.get(name) ?? new Map<string, Set<string>>();
+      const owners = credentials.get(credential) ?? new Set<string>();
+      owners.add(bundle.name);
+      credentials.set(credential, owners);
+      connectors.set(name, credentials);
+    }
+    atScope.set(scopeKey, connectors);
+  }
+  for (const [scopeKey, connectors] of atScope) {
+    for (const [connector, credentials] of connectors) {
+      const bundleNames = new Set<string>();
+      for (const owners of credentials.values()) for (const b of owners) bundleNames.add(b);
+      // Two DISTINCT bundles AND two DISTINCT credentials — one bundle contradicting itself is
+      // shape 1's report, and two bundles agreeing on the credential is a harmless duplicate.
+      if (credentials.size > 1 && bundleNames.size > 1) {
+        problems.push(
+          `bundles ${[...bundleNames].sort().map((b) => `"${b}"`).join(" and ")} are bound at the SAME scope (${scopeKey.replace(/\u0000/g, "/")}) and grant connector "${connector}" with different credentials (${[...credentials.keys()].sort().join(", ")}) — ` +
+            `narrowest-wins cannot separate two grants at one scope, so the surface would authenticate with whichever the config lists last. Bind them at different scopes, or agree on one credential.`,
+        );
+      }
+    }
+  }
+
+  return problems;
+}
+
+/** The room universe of scope levels. resolveAccess never applies the room ladder and the personal levels together, so bindings from the two universes are never paired here. */
+const ROOM_LEVELS: ReadonlySet<Scope["level"]> = new Set(["org", "tenant", "domain", "surface"]);
+
+function tenantOfSurfaceKey(surface: string | undefined): string | undefined {
+  const parts = (surface ?? "").split("/");
+  return parts.length >= 3 ? `${parts[0]}/${parts[1]}` : undefined;
+}
+
+/** Can these two bindings both be in one session's reach? It over-approximates in the safe direction only: true means it cannot be ruled out from the bindings alone, and it never answers false for a pair that can collide. */
+function bindingsCanCoResolve(a: Scope, b: Scope): boolean {
+  const aRoom = ROOM_LEVELS.has(a.level);
+  if (aRoom !== ROOM_LEVELS.has(b.level)) return false;
+  if (aRoom) {
+    if (a.level === "surface" && b.level === "surface") return a.surface === b.surface;
+    if (a.level === "tenant" && b.level === "tenant") return a.tenant === b.tenant;
+    if (a.level === "tenant" && b.level === "surface") return tenantOfSurfaceKey(b.surface) === a.tenant;
+    if (a.level === "surface" && b.level === "tenant") return tenantOfSurfaceKey(a.surface) === b.tenant;
+    return true; // an `org` binding reaches everything; a `domain` binding's reach is the registry's
+  }
+  if (a.level === "principal" && b.level === "principal") {
+    if (a.principal === undefined || b.principal === undefined) return true;
+    if (isLinkSetRef(a.principal) || isLinkSetRef(b.principal)) return true;
+    return a.principal === b.principal;
+  }
+  return true; // a `group` binding's membership is the person-group registry's
+}
+
+/** One connection's claim on one host pattern. Normalised through the resolver's own spelling
+ *  ({@link normaliseEgressHost}) so the lint and the reach map agree on what one host is. */
+interface HostClaim {
+  readonly host: string;
+  readonly via: string;
+}
+
+/** Every credentialed host claim one bundle makes. */
+function hostClaimsOf(bundle: Bundle): readonly HostClaim[] {
+  return (bundle.connections ?? []).flatMap((c) => c.allowedWebsites.map((h) => ({ host: normaliseEgressHost(h), via: c.id })));
+}
+
+/** The clashing pairs between two claim lists: two claims by different connections whose patterns can name one destination. The test is overlap, not equality, and same marks the within-one-bundle call, where the pairing skips the diagonal. */
+function clashingClaims(a: readonly HostClaim[], b: readonly HostClaim[], same: boolean): { ids: string[]; where: string }[] {
+  const out: { ids: string[]; where: string }[] = [];
+  const seen = new Set<string>();
+  for (let i = 0; i < a.length; i++) {
+    for (let j = same ? i + 1 : 0; j < b.length; j++) {
+      const x = a[i]!;
+      const y = b[j]!;
+      if (x.via === y.via) continue; // one connection is one credential, however it spells its reach
+      if (!egressHostsOverlap(x.host, y.host)) continue;
+      const ids = [x.via, y.via].sort();
+      const hosts = [x.host, y.host].sort();
+      const key = `${ids[0]} ${ids[1]} ${hosts[0]} ${hosts[1]}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ ids, where: x.host === y.host ? hosts[0]! : `${hosts[0]} (which overlaps ${hosts[1]})` });
+    }
+  }
+  return out;
+}
+
+/** One credential per host per session: the egress policy stamps the bearer by host alone, so two connections claiming one host is one grant silently killing the other. No escape hatch, and the runtime backstop is resolveAccess, which throws on the same condition. */
+export function lintEgressHostCollisions(bundles: readonly Bundle[], bindings: readonly Binding[]): string[] {
+  const problems: string[] = [];
+  const claimsByBundle = new Map<string, readonly HostClaim[]>();
+  for (const bundle of bundles) claimsByBundle.set(bundle.name, hostClaimsOf(bundle));
+
+  for (const bundle of bundles) {
+    const claims = claimsByBundle.get(bundle.name) ?? [];
+    for (const clash of clashingClaims(claims, claims, true)) {
+      problems.push(
+        `bundle "${bundle.name}" has two connections (${clash.ids.join(", ")}) claiming host ${clash.where} — ` +
+          `the egress policy stamps ONE credential per host, so the grant listed last wins and the other is dead config. ` +
+          `One credential per host per session: give each connection its own host.`,
+      );
+    }
+  }
+
+  const seen = new Set<string>();
+  for (let i = 0; i < bindings.length; i++) {
+    for (let j = i + 1; j < bindings.length; j++) {
+      const a = bindings[i]!;
+      const b = bindings[j]!;
+      if (a.bundle === b.bundle) continue; // one bundle's own clash is shape 1's report
+      if (!bindingsCanCoResolve(a.scope, b.scope)) continue;
+      const aClaims = claimsByBundle.get(a.bundle);
+      const bClaims = claimsByBundle.get(b.bundle);
+      if (aClaims === undefined || bClaims === undefined) continue; // unknown bundle: the resolver's warning
+      for (const clash of clashingClaims(aClaims, bClaims, false)) {
+        const pair = [a.bundle, b.bundle].sort();
+        const key = `${pair[0]}\u0000${pair[1]}\u0000${clash.where}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        problems.push(
+          `bundles "${pair[0]}" and "${pair[1]}" can both be in one session's reach ` +
+            `(${scopeLabel(a.scope)} + ${scopeLabel(b.scope)}) and their connections (${clash.ids.join(", ")}) both claim host ${clash.where} — ` +
+            `the egress policy stamps ONE credential per host, so that session would authenticate with whichever connection resolves last. ` +
+            `One credential per host per session: bind them at scopes that never resolve together, or give each connection its own host.`,
+        );
+      }
+    }
+  }
+
+  return problems;
+}
+
+/** A bundle connection may not claim a host the git read-broker reserves: the broker replaces those hosts' rules mid-turn, so the connection's key is displaced by call order. Unconditional, no escape hatch, and the test is overlap rather than equality. */
+export function lintReservedBrokerHosts(bundles: readonly Bundle[]): string[] {
+  const reserved = GIT_BROKER_HOSTS.map((h) => normaliseEgressHost(h));
+  const problems: string[] = [];
+  for (const bundle of bundles) {
+    for (const claim of hostClaimsOf(bundle)) {
+      const hit = reserved.find((r) => egressHostsOverlap(claim.host, r));
+      if (hit === undefined) continue;
+      problems.push(
+        `  bundle "${bundle.name}" connection "${claim.via}" claims host ${claim.host === hit ? claim.host : `${claim.host} (which overlaps ${hit})`} — ` +
+          RESERVED_BROKER_HOST_REASON,
+      );
+    }
+  }
+  return problems;
+}
+
+/** The tenants with at least one surface actually owned by this domain. A VALID container reach
+ * contributes future members: domain validation refuses an exclusion that consumes its whole set,
+ * while finite narrower exclusions/claims cannot consume the remainder. Exact entries use the
+ * canonical most-specific resolver, so an exclusion or narrower domain transfers ownership first. */
+function domainMemberTenants(
+  domain: Domain,
+  domains: readonly Domain[],
+): Map<string, { future: boolean }> {
+  const tenants = new Map<string, { future: boolean }>();
+  for (const entry of domain.reach ?? []) {
+    const parsed = parseSurfaceKeyEntry(entry);
+    if (!parsed || parsed.kind === "group") continue;
+    const tenant = `${parsed.platform}/${parsed.tenant}`;
+    if (parsed.kind === "surface" && !parsed.glob) {
+      if (resolveDomainForChannel(entry, domains).domain?.name !== domain.name) continue;
+      if (!tenants.has(tenant)) tenants.set(tenant, { future: false });
+      continue;
+    }
+    const fullyExcluded = (domain.exclude ?? []).some((raw) => {
+      const excluded = parseSurfaceKeyEntry(raw);
+      return excluded !== undefined && surfaceKeyEntryContains(excluded, parsed);
+    });
+    if (fullyExcluded) continue;
+    tenants.set(tenant, { future: true });
+  }
+  return tenants;
+}
+
+/** JSON cannot see an approver function. Give each configured function a stable identity for this
+ * lint invocation: the same grant resolving in two tenants stays equal, while two independently
+ * configured decision functions are conservatively different. */
+function approverIdentity(approverIds: Map<Function, number>, fn: Function): number {
+  const found = approverIds.get(fn);
+  if (found !== undefined) return found;
+  const id = approverIds.size + 1;
+  approverIds.set(fn, id);
+  return id;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const record = value as Readonly<Record<string, unknown>>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function unordered(values: readonly unknown[]): readonly string[] {
+  return values.map(stableJson).sort();
+}
+
+function connectionFact(connection: EffectiveAccess["connections"][number]): unknown {
+  return {
+    ...connection,
+    allowedWebsites: [...connection.allowedWebsites].sort(),
+    ...(connection.pathPrefixes === undefined ? {} : { pathPrefixes: [...connection.pathPrefixes].sort() }),
+    ...(connection.methods === undefined ? {} : { methods: [...connection.methods].sort() }),
+  };
+}
+
+function reachableHostFact(host: EffectiveAccess["reachableHosts"][number]): unknown {
+  return {
+    ...host,
+    ...(host.pathPrefixes === undefined ? {} : { pathPrefixes: [...host.pathPrefixes].sort() }),
+    ...(host.methods === undefined ? {} : { methods: [...host.methods].sort() }),
+  };
+}
+
+function setValuedRecord(record: Readonly<Record<string, readonly unknown[]>>): Readonly<Record<string, readonly string[]>> {
+  return Object.fromEntries(
+    Object.entries(record).sort(([a], [b]) => a.localeCompare(b)).map(([key, values]) => [key, unordered(values)]),
+  );
+}
+
+function connectorCredentialFacts(access: EffectiveAccess): unknown {
+  return Object.fromEntries(
+    Object.entries(access.connectorCredentials).sort(([a], [b]) => a.localeCompare(b)).map(([key, credential]) => [
+      key,
+      {
+        ...credential,
+        ...(credential.endpoints === undefined
+          ? {}
+          : {
+              endpoints: {
+                ...credential.endpoints,
+                hosts: [...credential.endpoints.hosts].sort(),
+                ...(credential.endpoints.pathPrefixes === undefined ? {} : { pathPrefixes: [...credential.endpoints.pathPrefixes].sort() }),
+                ...(credential.endpoints.methods === undefined ? {} : { methods: [...credential.endpoints.methods].sort() }),
+              },
+            }),
+      },
+    ]),
+  );
+}
+
+/** Strip request coordinates and provenance labels from a resolve. What remains is the static
+ * capability fact a domain member receives. Scope RUNG is retained for instruction/rule ordering;
+ * the tenant's literal id is provenance rather than a capability difference. */
+function staticCapabilityFingerprint(
+  access: EffectiveAccess,
+  approverIds: Map<Function, number>,
+): string {
+  const scopeRung = (source: string): string => source.split(":", 1)[0] ?? source;
+  return stableJson({
+    connections: unordered(access.connections.map(connectionFact)),
+    reachableHosts: unordered(access.reachableHosts.map(reachableHostFact)),
+    repos: access.repos,
+    repoCapabilities: setValuedRecord(access.repoCapabilities),
+    resourceCapabilities: setValuedRecord(access.resourceCapabilities),
+    awsRoles: unordered(access.awsRoles.map((role) => ({ ...role, allow: [...role.allow].sort() }))),
+    approvers: access.approvers.map((a) => ({
+      name: a.name,
+      source: a.source,
+      mayAllow: a.mayAllow,
+      approve: approverIdentity(approverIds, a.approve),
+    })),
+    plugins: access.plugins,
+    skills: access.skills,
+    subagents: access.subagents,
+    connectors: access.connectors,
+    connectorContentOrigin: access.connectorContentOrigin,
+    connectorCredentials: connectorCredentialFacts(access),
+    instructionStack: access.instructionStack.map((layer) => ({ scope: scopeRung(layer.source), text: layer.text })),
+    preApprovalRules: access.preApprovalRules.map((rule) => ({ scope: scopeRung(rule.scope), id: rule.id, rule: rule.rule })),
+  });
+}
+
+/** A domain is one static capability boundary, independently of whether its seats use unified or
+ * separate windows. Direct surface bindings inside it are forbidden. Broader tenant bindings may
+ * remain only when every tenant represented in the domain resolves to the same capability facts. */
+export function lintDomainCapabilityConsistency(
+  bundles: readonly Bundle[],
+  bindings: readonly Binding[],
+  domains: readonly Domain[] = [],
+  registry: PluginRegistry = {},
+  connectorCredentials: readonly ConnectorCredentials[] = [],
+): string[] {
+  const problems: string[] = [];
+
+  for (const binding of bindings) {
+    if (binding.scope.level !== "surface" || binding.scope.surface === undefined) continue;
+    const owner = resolveDomainForChannel(binding.scope.surface, domains).domain;
+    if (!owner) continue;
+    problems.push(
+      `direct surface binding: surface "${binding.scope.surface}" belongs to domain "${owner.name}", but bundle "${binding.bundle}" is bound directly to that surface. ` +
+        `A domain is one capability boundary even when its sessions are separate: move this grant to { level: "domain", domain: "${owner.name}" }, or remove the surface from that domain before binding it directly.`,
+    );
+  }
+
+  // Surface bindings have already failed above. Excluding them here prevents a synthetic probe key
+  // from making the tenant comparison depend on a sentinel that no deployer configured.
+  const staticBindings = bindings.filter((binding) => binding.scope.level !== "surface");
+  const approverIds = new Map<Function, number>();
+  for (const domain of domains) {
+    if (!domain.reach) continue; // criteria pseudo-domains have no enumerable room membership
+    const tenants = domainMemberTenants(domain, domains);
+    if (tenants.size < 2) continue;
+
+    const byFingerprint = new Map<string, string[]>();
+    for (const tenant of [...tenants.keys()].sort()) {
+      const parsed = parseSurfaceKeyEntry(tenant);
+      if (!parsed || parsed.kind !== "tenant") continue;
+      const access = resolveAccess(
+        {
+          mode: "channel",
+          platform: parsed.platform,
+          workspace: parsed.tenant,
+          channel: "__domain_capability_consistency__",
+          domains: [domain.name],
+        },
+        bundles,
+        staticBindings,
+        registry,
+        connectorCredentials,
+      );
+      const fingerprint = staticCapabilityFingerprint(access, approverIds);
+      const group = byFingerprint.get(fingerprint) ?? [];
+      group.push(tenant);
+      byFingerprint.set(fingerprint, group);
+    }
+    if (byFingerprint.size < 2) continue;
+
+    const facts = [...byFingerprint.values()]
+      .map((group) => group.join(", "))
+      .sort()
+      .map((group, index) => `capability set ${index + 1}: ${group}`)
+      .join("; ");
+    const future = [...tenants.entries()].filter(([, detail]) => detail.future).map(([tenant]) => tenant).sort();
+    problems.push(
+      `domain "${domain.name}" resolves different static capabilities for its member tenants (${facts}). ` +
+        `${future.length > 0 ? `Its container reach includes future surfaces under ${future.join(", ")}. ` : ""}` +
+        `Move tenant-only capability bindings to { level: "domain", domain: "${domain.name}" }, split the domain, or remove the broader grant; every member of one domain must receive the same static capability facts.`,
+    );
+  }
+
+  return problems;
+}
+
+/** A connector admitting a credential grant must declare endpoints.hosts, or an act-with-my-own-account ask withholds nothing and is answered on the team credential. The join is the shared secretRef and the reach test is overlap, so a connection carrying the vendor's key must also reach a declared host. */
+export function ownAccountWithholdingProblems(
+  connectors: readonly string[],
+  catalogues: readonly ConnectorCredentials[],
+  bundles: readonly Bundle[] = [],
+): string[] {
+  const byConnector = new Map(catalogues.map((c) => [c.connector, c]));
+  const problems: string[] = [];
+  for (const connector of [...new Set(connectors)].sort()) {
+    const catalogue = byConnector.get(connector);
+    const hosts = (catalogue?.credentials ?? []).flatMap((c) => c.endpoints?.hosts ?? []).map((h) => normaliseEgressHost(h));
+    if (hosts.length === 0) {
+      problems.push(
+        `  connector "${connector}" admits a credential grant (CREDENTIAL_GRANT_ROLES, access/credential-grant.ts) but ` +
+          `${catalogue === undefined ? "has NO credential catalogue" : "no credential in its catalogue declares `endpoints.hosts`"}` +
+          ` — so the resolver cannot tell which hosts carry this vendor's key, and an "act with my own account" ask on the` +
+          ` egress route withholds nothing and is answered on the TEAM credential (OPE-1549). Declare the vendor's hosts on` +
+          ` at least one of its credentials in agent/access/connector-credentials.ts.`,
+      );
+      continue;
+    }
+    // THE REACH SIDE. Every bundle connection stamping one of this connector's own secrets must
+    // reach at least one catalogue host, or the withholding cannot see it at all.
+    const secrets = new Set((catalogue?.credentials ?? []).map((c) => c.secretRef));
+    for (const bundle of bundles) {
+      for (const c of bundle.connections ?? []) {
+        const stamped = [c.secretRef, ...(c.customHeaders ?? []).map((h) => h.secretRef)];
+        if (!stamped.some((ref) => secrets.has(ref))) continue; // not this vendor's key
+        const claims = c.allowedWebsites.map((h) => normaliseEgressHost(h));
+        if (claims.some((h) => hosts.some((v) => egressHostsOverlap(h, v)))) continue; // the withholding identifies it
+        problems.push(
+          `  bundle "${bundle.name}" connection "${c.id}" stamps a secret that connector "${connector}"'s catalogue also ` +
+            `names, but it reaches none of that catalogue's declared hosts (it reaches ${claims.join(", ")}; the catalogue ` +
+            `declares ${hosts.join(", ")}). The own-account withholding identifies a vendor's connections BY REACH, so it ` +
+            `cannot see this one — an "act with my own account" ask leaves every host it reaches on the TEAM credential ` +
+            `(OPE-1684). Add one of those hosts to \`endpoints.hosts\` in agent/access/connector-credentials.ts, or give ` +
+            `this connection its own secret.`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/** A binding's scope as one short operator-facing phrase, for a message that must name two of them. */
+function scopeLabel(scope: Scope): string {
+  const address = scope.tenant ?? scope.domain ?? scope.surface ?? scope.group ?? scope.principal;
+  return address === undefined ? scope.level : `${scope.level} ${address}`;
+}
+
+/** The config-only lints the CI gate runs. Domains and groups are the registries a domain or group binding's width depends on, and both are optional so older call sites keep their exact old verdict. */
+export function lintAccessConfig(
+  bundles: readonly Bundle[],
+  bindings: readonly Binding[],
+  domains: readonly Domain[] = [],
+  groups: readonly Group[] = [],
+  registry: PluginRegistry = {},
+  connectorCredentials: readonly ConnectorCredentials[] = [],
+): string[] {
+  return [
+    ...lintBroadGrants(bundles, bindings, domains, groups),
+    ...lintDomainCapabilityConsistency(bundles, bindings, domains, registry, connectorCredentials),
+    ...lintMethodNarrowing(bundles),
+    ...lintCredentialCollisions(bundles, bindings),
+    ...lintEgressHostCollisions(bundles, bindings),
+    ...lintReservedBrokerHosts(bundles),
+  ];
+}
+
+/** A connector grant naming a credential its connector does not configure reads as a live capability and resolves to nothing, with no failure anywhere. No escape hatch, and a bare-slug grant is reported here too, because this lint also sees bundle sets that never passed load. */
+export function connectorGrantCredentialProblems(
+  bundles: readonly Bundle[],
+  catalogues: readonly { readonly connector: string; readonly credentials: readonly { readonly id: string }[] }[],
+): string[] {
+  const byConnector = new Map(catalogues.map((c) => [c.connector, c]));
+  const problems: string[] = [];
+  for (const bundle of bundles) {
+    for (const grant of bundle.connectors ?? []) {
+      const name = connectorGrantName(grant);
+      const credential = connectorGrantCredential(grant);
+      if (credential === undefined) {
+        problems.push(
+          `  bundle "${bundle.name}" grants connector "${name}" with no credential — a grant names the identity it reaches the connector as`,
+        );
+        continue;
+      }
+      const catalogue = byConnector.get(name);
+      if (!catalogue) {
+        problems.push(
+          `  bundle "${bundle.name}" grants connector "${name}" as credential "${credential}", but "${name}" has NO credential catalogue` +
+            ` — add one to agent/access/connector-credentials.ts`,
+        );
+        continue;
+      }
+      if (!catalogue.credentials.some((c) => c.id === credential)) {
+        const known = catalogue.credentials.map((c) => c.id).join(", ") || "none";
+        problems.push(
+          `  bundle "${bundle.name}" grants connector "${name}" as credential "${credential}", which that connector does not configure` +
+            ` (configured: ${known}) — the grant resolves to nothing`,
+        );
+      }
+    }
+  }
+  return problems;
+}