Declare the plugin tables' foreign keys

[mastacontrola]

The plugin half of fogproject ADR 0031. Depends on
FOGProject/fogproject#1469, which is merged — these steps call
SchemaReconciler::sweepOrphans(), which did not exist before it.

22 relationships across five plugins, one commit each.

Plugin	Step	Column change	Constraints
location	4 and 5	lStorageNodeID nullable, 0 -> NULL	4
ou	2	none	2
windowskey	3	none	2
ldap	28	none	6
oidc	9	none	8

Why the relationships are declared in core, not here

Half of them point at core tables — hosts, images, users, roles,
userGroups, nfsGroups — and the map is meant to answer "what points at
hosts?" from one file. What lives here is the act of applying them.

The direction rule holds in the arrows themselves: every one runs plugin ->
core or plugin -> plugin, and nothing in core points back, so uninstalling a
plugin is still just dropping its tables.

Each plugin's group is its own name, a string, where core's groups are
ints. planConstraints() and planSweep() select on ===, which is what
keeps the two spaces apart — and it has to be strict, because PHP 7.4 is
FOG's floor and there 5 == 'ldap' is true. A plugin group written as a
number would be applied by a core schema step, against tables core had not
swept.

Sweep, then add

ADR 0031 decision 8. ADD CONSTRAINT validates the rows already in the table
and answers 1452 if any of them point at a parent that is gone — and
applyConstraints() reports a refusal rather than returning it, so an
install that skipped the sweep would succeed while silently not creating the
constraint. The sweep is the precondition for the statement, not a policy
choice.

Every step is appended, never folded into an earlier one: installdb() skips
the pSchema steps an install has already passed instead of replaying them,
so editing an earlier step is invisible to everyone past it. That is exactly
what LDAP steps 10-16 exist to repair.

Two that needed a decision

• location.lStorageNodeID gets SET NULL, and its 0 becomes NULL. The
  column is a tri-state and always has been — Location::getStorageNode()
  returns the named node when truthy and falls through to the group's optimal
  node when not — so 0 was a documented, load-bearing value. A foreign key
  accepts NULL for "no reference" and nothing else. Nothing reading it
  changed: FOGController::get() reads through isset(), so NULL comes back
  as '' and is falsy exactly as 0 was. createSql() now builds the column
  nullable so a fresh install is not created already needing the migration.
• oidcIdentity is a satellite of both ends. It is the record that this
  external subject is this FOG user, so deleting either end has to take it.
  Left behind, the next user created with a recycled id inherits someone
  else's identity binding.

ldapUserGrant.lugTargetID and oidcUserGrant.ougTargetID stay polymorphic
and take no constraint — the parent table is chosen by a sibling
*TargetType column. Same shape as core's scheduledTasks.stGroupHostID.

LDAP is where this was already visible

Its existing steps 19-21 are this same sweep, hand-written, added because
deleting a user, role or user group did not clear the plugin's rows: an
install upgraded from before LDAPDeleteMassItems existed held mappings
pointing at ids that were gone. Those steps stay as they are, but they only
ever ran once, against a backlog. These constraints stop the backlog forming
again — in the database, rather than in a hook that has to be remembered at
every delete site.

Verification

Against a lab clone of a live database at schema 390, all five applied in
sequence:

Constraints in the database	88
Declared and enabled in the map	89
Not applied	1 — fk_nfsGroupMembers_ngmGroupID, a core relationship

That one gap is the refusal already documented for core group 5: a storage
node sits at group 0 on that data and nothing guesses a group. Every other
declared relationship landed with the exact ON DELETE the map names — no
mismatches, and nothing in the database the map does not declare.

Three properties checked separately, because each can fail while the others
pass:

• Fresh install — every plugin table dropped, all five run from step 0:
  the same 88, with lStorageNodeID built nullable rather than migrated
  afterward.
• Idempotence — every plugin re-run planned no ALTER at all.
• Convergence — the unfiltered reconcile() that follows every core
  schema update, run over the finished install, plans exactly the one known
  refusal and returns true with it collected.

Behavior was probed per plugin against real rows and rolled back, not
inferred from DELETE_RULE. Deleting one LDAP server removed its 2 groups
and the 2 role associations pointing at those groups; deleting an OIDC
provider removed both identities, its group, and the role association
pointing at that group. Two levels, no PHP.

The new gate

tests/foreign-keys-applied-per-plugin.test.php pins, per plugin, that the
sweep is called, that the add is called, that the sweep comes first, and
that neither is called unfiltered. Mutation-tested: dropping either call,
reversing their order, dropping the group argument, reverting the column to
NOT NULL, dropping the 0-to-NULL conversion, and building the column
NOT NULL in createSql() each turn a check red.

It deliberately does not check that SchemaReconciler is fully qualified
— core-references-are-qualified.test.php already does that generically, and
a check written here would pass while one of the two calls kept its
namespace.

🤖 Generated with Claude Code

https://claude.ai/code/session_019Q7gwbNYDmYVFRBrXDXFz5