Push the API object boundary into the query, keeping the id list as fallback

[mastacontrola]

Follows #1229, which brought the site boundary to the API by asking the plugin
which object ids the acting user may see and narrowing with that list. Correct,
but it answers "which hosts may this user see" by reading every one of them into
PHP on every request.

What changes

A new event, API_SCOPE_WHERE, asks for the same boundary as a SQL fragment.
It is tried first; API_SCOPE_IDS is the fallback. Both handlers stay
registered in the site plugin and only one is ever applied to a request, so a
third-party plugin that knows only the old event keeps working untouched.

Two tri-states, and they are not the same one.

	no boundary	narrow	deny-all
API_SCOPE_IDS	null	array(1,2,3)	array()
API_SCOPE_WHERE	null	'<sql>'	'1=0'

The fragment has no empty-string state. '' is read as silence and falls
through — an empty fragment is indistinguishable from no answer, and would
otherwise compile to WHERE (). Deny-all has to be said in SQL.

Where each applies

Route	How
names(), ids()	Route builds the SQL, so the fragment is ANDed onto what _buildWhere() produced
listem(), search()	went through the manager, which had no seam — find()/search() take a $scopeWhere argument now
dispatch gate	_requireObjectScope() asks whether one row satisfies the same expression the lists narrow with

The manager seam ANDs the fragment on last, with the caller's own terms
parenthesised and joined by a literal AND, never through $whereOperator —
that parameter takes 'OR', and an OR that can reach outside the boundary is not
a boundary.

Also fixed — same call path, found while proving parity

hostIDsForSites() went through SiteHostAssociation's manager. find() walks
class relationships to build joins, so it pulled in Host's
MACAddressAssociation relationship, which carries array('primary' => 1).
buildQuery() emits that as `hostMAC`.`hmPrimary` = '1' in the WHERE,
turning the LEFT OUTER JOIN into an inner one and silently dropping every host
with no primary MAC — 95 of 1000 in the lab.

It under-returned, so nobody saw anything they should not; but a site-restricted
user could not see hosts in their own site, and the two boundaries disagreed
about which hosts a site holds. A membership lookup has no business joining
Host; it reads the association table directly now.

⚠️ This also changes the management pages, which share the function:
restricted users will now see hosts that were wrongly hidden from them.

Verified against the 1.5 lab, 2079 hosts, a site holding 1000, real site plugin

	id list, as merged	id list + join fix	fragment (this PR)
names host	95	1000	1000
ids host	95	1000	1000
list host	95	95	95
search host	53	53	53
names group	2	2	2
restricted, no site	0	0	0
logged out (daemon)	2079	2079	2079
administrator	126 / 2079	126 / 2079	126 / 2079
per-object gate, in / out	ALLOW / DENY	—	ALLOW / DENY
queries, restricted	4	4	3

The fixed id list and the fragment agree on every line — that is the parity
this was asked for. The first column is the bug above.

_boundedSiteIDs() is memoized per user per request: without it an unrestricted
user paid for the restriction lookup twice on every read (2 → 3 statements for an
administrator), once for the fragment that declines and once for the id list that
declines. Deliberately not memoized on the public userIsRestricted() /
userSiteIDs(), which the management pages call on requests that have just
written the rows they read.

Tests

Characterization tests were written first, against the id-list implementation,
and pass unedited after the port. 65 checks: three states (no boundary, scoped,
deny-all) × four read routes × two classes, plus the dispatch gate out of process
because a denial ends the response by exiting. They assert which objects come
back, never the SQL that produced them, so they hold across either
implementation. The database arm skips rather than degrading into a string match
where no 1.5 schema is reachable.

Every gate is mutation-verified. Two bugs were caught that way and by nothing
else:

• the dispatch gate read PDODB's false for "no rows" through
  count((array)$rows), which is 1 — so it allowed every object it was built
  to refuse;
• the fragment was dropped whenever the caller had supplied a filter of their own,
  because only the empty arm of the append helper was being driven.

Suite: 17 files, 0 failures.

Not in scope

The hmPrimary filter leaking out of Host's relationship into anything that
joins through Host is a wider problem than this call path. Fixed here only where
the boundary depends on it.

Downstream

No route class list change, so FogApi's hardcoded -coreObject list is unaffected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GN7hADN5QLzoxXWDA6xeUk