feat(integration-registry): schema validator + dangling-linkedTypes surveillance (umbrella PR 2/N)

[rubenvdlinde]

Stacked on #1467. Tasks 7-11 of #1307 — Backend — Schema validator refactor.

Task	What
2.1	Schema::validateLinkedTypesValue() now consults both VALID_LINKED_TYPES (deprecated fallback) AND IntegrationRegistry::listIds(). Registry resolved lazily via \OC::$server->get() since Schema is a Nextcloud Entity, not a service. Falls back to fallback-only when container isn't booted (unit tests). AD-5 backwards-compat preserved.
2.2	VALID_LINKED_TYPES marked @deprecated with pointers to the registry + cleanup-linked-entity-type-map follow-up.
2.3	LinkedEntityService::TYPE_COLUMN_MAP marked @deprecated.
2.4	New PropertyReferenceTypeValidator service that validates the referenceType: <integration-id> marker on schema property definitions (AD-18). Standalone validator so existing schema validation paths don't change; CnFormDialog / CnDetailGrid wire it in tasks 25-46.
2.5	New LogDanglingLinkedTypes repair step — registered under <install> + <post-migration> in info.xml. Scans every schema, logs WARNING for any linkedTypes value not yet registered. Strictly informational; never throws, never modifies data.

Net new files

• lib/Service/Integration/PropertyReferenceTypeValidator.php
• lib/Repair/LogDanglingLinkedTypes.php
• tests/Unit/Service/Integration/PropertyReferenceTypeValidatorTest.php

Modified

• lib/Db/Schema.php — validator + deprecation note
• lib/Service/LinkedEntityService.php — deprecation on TYPE_COLUMN_MAP
• lib/Service/Integration/IntegrationRegistry.php — isValidIntegrationId() helper
• lib/AppInfo/Application.php — DI bindings
• appinfo/info.xml — repair-step entry

Tests

• 34 tests, 48 assertions — all green inside the openregister-postgres dev container
• 9 new for PropertyReferenceTypeValidator; the 25 from PR 1 still pass

Deferred to PR 3

Built-in providers (tasks 12-17 — Files/Notes/Tasks/Tags/AuditTrail wrappers). Keeps this PR a single coherent slice: "registry-driven validation + dangling-id surveillance".

Stacking note

This PR's base is feature/1307/pluggable-integration-registry (PR #1467). When #1467 merges into development, GitHub will retarget this PR to development automatically — no rebase required.

🤖 Generated with Claude Code

[WilcoLouwerse]

[BLOCKER] scan() flags VALID_LINKED_TYPES ids as dangling — false positives on every upgrade

scan() marks a linkedType as dangling when absent from $registeredIds (the live registry). It does NOT consult VALID_LINKED_TYPES. Since built-in Wave-1 providers (FilesProvider, NotesProvider, etc.) are still pending (tasks 3.1–3.5 in plan.json), the registry is empty on any real install. Every schema with linkedTypes=['mail','calendar','talk','files',...] will produce a WARNING on every upgrade, even though validateLinkedTypesValue() in Schema.php accepts those values via the legacy fallback. Fix: pass array_merge(VALID_LINKED_TYPES, $registeredIds) as the accepted set, or suppress the warning when the registry itself is empty.

[WilcoLouwerse]

[BLOCKER] findAll() with no limit OOMs on large installations at upgrade time

loadSchemas() calls $mapper->findAll() with no arguments, fetching the entire openregister_schemas table into memory in one query. On installations with thousands of schemas this is a full unbounded table scan during occ upgrade, risking OOM or timeout. Fix: batch-iterate in pages of e.g. 500 (findAll(500, $offset)).

[WilcoLouwerse]

[BLOCKER] validate() rejects referenceType='files' today — built-in providers not yet registered

PropertyReferenceTypeValidator::validate() calls $this->registry->isValidIntegrationId($value) with no VALID_LINKED_TYPES fallback. Built-in providers (FilesProvider, NotesProvider, etc.) are Wave-1 work still marked pending in plan.json. Any schema that sets referenceType: "files" today will throw InvalidArgumentException. Either include VALID_LINKED_TYPES as an implicit fallback, or block validator calls until at least one built-in provider is registered.

[WilcoLouwerse]

[BLOCKER] SPDX machine-readable headers missing from LogDanglingLinkedTypes.php

LogDanglingLinkedTypes.php only has the @license tag, not SPDX-License-Identifier: EUPL-1.2 and SPDX-FileCopyrightText: 2026 Conduction B.V. machine-readable headers required by hydra-gate-spdx. Add both SPDX lines to the opening docblock.

[WilcoLouwerse]

[BLOCKER] SPDX machine-readable headers missing from PropertyReferenceTypeValidator.php

PropertyReferenceTypeValidator.php uses the @license docblock tag but omits the machine-readable SPDX-License-Identifier: EUPL-1.2 and SPDX-FileCopyrightText: 2026 Conduction B.V. lines required by hydra-gate-spdx.

[WilcoLouwerse]

[CONCERN] Repair step runs unconditionally even when registry has zero providers — alert fatigue

run() scans all schemas unconditionally. When the registry is empty (standard state before Wave-1 providers land), it will warn on every type in every schema. Consider short-circuiting: if $registeredIds === [] then skip the scan entirely or restrict warnings to types not in VALID_LINKED_TYPES to prevent alert fatigue.

[WilcoLouwerse]

[CONCERN] resolveIntegrationRegistryIds() swallows all Throwable silently — masking misconfiguration

The catch block catches \Throwable and returns [] with no log entry. If the registry binding throws unexpectedly (not just NotFoundExceptionInterface for missing service), validation silently degrades to the legacy list only. Fix: distinguish NotFoundExceptionInterface (expected) from other \Throwable (log at WARNING level).

[WilcoLouwerse]

[CONCERN] No unit tests for LogDanglingLinkedTypes — surveillance step has zero test coverage

The test file covers only PropertyReferenceTypeValidator. LogDanglingLinkedTypes has three non-trivial private methods (loadSchemas, scan, extractLinkedTypes) but no tests. At minimum: a test for scan() with a mix of registered and legacy-only types to confirm the false-positive problem, and a test for the graceful skip path when loadSchemas() returns null.

[WilcoLouwerse]

[CONCERN] Repair step injects registry at construction time — providers registered after boot are invisible

IntegrationRegistry is injected in the constructor and listIds() called once in run(). Built-in providers self-register via addProvider() at app bootstrap. If repair steps execute before app boot completes during occ upgrade, listIds() may return an incomplete set and produce spurious warnings. Recommend adding an $output->info() line printing the count of registered ids so operators can cross-check.

[WilcoLouwerse]

Review

🔴 Blockers (5)

• scan() flags VALID_LINKED_TYPES ids as dangling — false positives on every upgrade — lib/Repair/LogDanglingLinkedTypes.php:334
• findAll() with no limit OOMs on large installations at upgrade time — lib/Repair/LogDanglingLinkedTypes.php:311
• validate() rejects referenceType='files' today — built-in providers not yet registered — lib/Service/Integration/PropertyReferenceTypeValidator.php:569
• SPDX machine-readable headers missing from LogDanglingLinkedTypes.php — lib/Repair/LogDanglingLinkedTypes.php:184
• SPDX machine-readable headers missing from PropertyReferenceTypeValidator.php — lib/Service/Integration/PropertyReferenceTypeValidator.php:471

🟡 Concerns (4)

• Repair step runs unconditionally even when registry has zero providers — alert fatigue — lib/Repair/LogDanglingLinkedTypes.php:266
• resolveIntegrationRegistryIds() swallows all Throwable silently — masking misconfiguration — lib/Db/Schema.php:159
• No unit tests for LogDanglingLinkedTypes — surveillance step has zero test coverage — tests/Unit/Service/Integration/PropertyReferenceTypeValidatorTest.php:690
• Repair step injects registry at construction time — providers registered after boot are invisible — lib/Repair/LogDanglingLinkedTypes.php:276

🟢 Minor (1)

• Test stub class named _ValidatorStubProvider — leading underscore violates PHPCS PSR-2 (tests/Unit/Service/Integration/PropertyReferenceTypeValidatorTest.php:734)
  PHP naming conventions (PSR-2 / PHPCS) prohibit leading underscores in class names. _ValidatorStubProvider will trigger a PHPCS sniff. Rename to ValidatorStubProvider or FakeIntegrationProvider.

Reviewed by WilcoLouwerse via automated batch review.

[WilcoLouwerse]

🔍 Retrospective audit finding — surfaced from #1515

While reviewing integration rollup PR #1515, one 🔴 blocker traces back to LogDanglingLinkedTypes in this PR:

LogDanglingLinkedTypes::loadSchemas() calls findAll() with no limit — the repair step is an IRepairStep (runs on every occ upgrade / app re-enable) and pulls every schema row into memory in a single call. On a multi-tenant deployment with thousands of schemas this will exhaust PHP memory mid-upgrade and leave the app in a half-migrated state — the exact failure mode the step exists to warn about. Either page via findAll($limit, $offset) in a loop, or stream via a generator/yield. Inline comment on #1515

The PR body of #1515 surfaced this under "#1468 false-positive risk" as a concern — confirming it merged unaddressed. Worth a fixup PR.