refactor(capability): the tool-grant grammar moves to OpenRegister (ADR-099 §5) (#563)

* refactor(capability): the tool-grant grammar moves to OpenRegister (ADR-099 §5)

The hermiq half of a PR pair. Requires openregister#2868; this cannot merge
until a build carrying OCA\OpenRegister\Service\Capability ships.

ADR-099 §5 keeps two grant axes and forbids merging them. The CAPABILITY axis —
may agent X use tool T — is not agent-specific and resolves against
ToolRegistryFacade, which already lives in OpenRegister, so it moves to sit
beside what it resolves against. The Agent.tools BINDING stays here.

WHAT MOVED: ToolGrantSet, ToolGrantCodec, ToolGrantResolver, ToolReachResolver,
ToolGrantResolutionException, and four of their five test files. Verbatim — only
the namespace changed. That codec carries a measured scar (35 of 87 tools parsed
wrong) and ADR-095's persistence constraint, and a rewrite-while-moving reopens
both.

ToolGrantResolverTest STAYS here, repointed. It builds its catalog from hermiq's
real tool providers — nine of them — so it is an integration test against a
catalog, not a unit test of the grammar. It belongs where the catalog is.

🔴 THERE IS DELIBERATELY NO STUB FOR THE NEW NAMESPACE, and there must never be
one. hermiq's test bootstrap maps OCA\OpenRegister\ at tests/Stubs/, so the naive
move would have resolved the grammar to a stub — and fifteen test classes
exercise its BEHAVIOUR. A stubbed copy would not merely drift, it would make
fifteen test classes validate a fake while reporting green. This repo has already
paid for that on a THREE-METHOD facade: tests/Stubs/.../ToolRegistryFacade.php
drifted by one method and broke a whole matrix leg. This is ~2,400 lines of
security-relevant parsing.

So bootstrap.php, phpstan.neon and psalm.xml all read the REAL source at
../openregister/lib/Service/Capability. Both topologies put OpenRegister beside
hermiq — CI checks additional apps out at server/apps/openregister next to
server/apps/hermiq, and the dev tree mirrors it — so one relative path serves
both, and no CI change is needed. When it is absent nothing is registered: the
class is genuinely missing and the run fails loudly, which is the point.

TWO FILES NEEDED NEW IMPORTS THAT NOTHING WOULD HAVE FLAGGED. FacadeToolInvoker
and ToolLoop referenced these classes with no `use` at all, because they shared
the namespace. A relocation that only rewrote files carrying an explicit import
would have left them referencing classes that no longer exist — and PHP would not
have said so until the line ran, as a fatal in the middle of a tool call.

CheckOpenRegisterCompatibility now names ToolGrantResolver. The grammar used to
live here, so no OpenRegister could be too old to supply it; now one can, and
without this a stale instance surfaces as a bare "Class not found" from inside a
tool call at whatever hour an agent next ran, instead of a clear message at
upgrade time.

CONSERVATION CHECK, measured rather than assumed: development runs 1834 tests /
5776 assertions; this branch runs 1776 / 5623. The difference is 58 tests and 153
assertions — exactly what openregister#2868 gained. Nothing was dropped in
transit. phpcs, phpmd, psalm and phpstan clean; psalm and phpstan were RED on
this branch until they were pointed at the real source, which is how the missing
type resolution was found rather than assumed away.

* fix(capability): declaration-only stubs so static analysis can still see the grammar

CI found the hole my relative path did not cover. `phpstan.neon` and `psalm.xml`
pointed at ../openregister/lib/Service/Capability, which resolves in the PHPUNIT
job — that one checks additional apps out at server/apps/openregister next to
server/apps/hermiq — but the PHP-QUALITY job does a plain actions/checkout with
no additional apps at all. PHPStan aborted with `Scanned directory
/home/runner/work/hermiq/openregister/lib/Service/Capability does not exist`.

I had verified the path against ONE job's layout and generalised from it.

🔴 THE STUBS THROW, AND THAT IS THE WHOLE DESIGN. A stub that RETURNED plausible
values would make fifteen test classes validate a fake while reporting green —
the failure this repo already paid for on a THREE-METHOD facade, where
tests/Stubs/Service/Mcp/ToolRegistryFacade.php drifted by one method and broke a
whole matrix leg. This is ~2,400 lines of security-relevant parsing.

So the split is: signatures for the analysers, behaviour from the real source.

  * php-quality — PHPStan/Psalm resolve the class from tests/Stubs and type-check
    the thirteen call sites. Without this every one is an unknown-class error and
    the gate goes quiet on all of them, which is strictly worse than a stub.
  * phpunit — tests/bootstrap.php maps the REAL source under the longer PSR-4
    prefix, which wins over the blanket tests/Stubs mapping regardless of order.
    Measured both ways: 1776 tests / 5623 assertions green with the real source
    present; 91 loud errors without it. A missing dependency cannot masquerade as
    a passing suite.

A signature drift is therefore caught by the test run, which exercises the real
class. This file can fail to DESCRIBE a drift; it cannot hide one.

ToolGrantResolutionException is the one exception and is constructible: ToolLoop
throws it and ToolLoopTest catches it, so a throwing constructor would break a
test that never touches the grammar. It carries its grants and nothing else —
there is no logic in it to get wrong.

* docs(agent-identity): task 3.2 done, with what the relocation actually cost

Records the two things that were not visible when 3.2 was written: the stub
directory would have swallowed the move silently, and two files referenced the
grammar with no import at all because they shared its namespace. Also records
the conservation check — 58 tests and 153 assertions left hermiq and exactly 58
and 153 arrived in openregister — because that is the measurement that
distinguishes a relocation from a quiet drop.

* fix(manifest): three em-dashes in copy a reader sees (gate-96)

Gate 96 (manifest-copy-style) merged to .github/main today and fires full-tree,
so it lands on hermiq's existing manifest rather than on anything this branch
changed. Three user-visible strings break voice.md section 8 — a page
description, the setup step, and a walkthrough step.

Fixed rather than excluded: an em-dash in shipped copy is the tell the rule
exists for, the rewrite costs a colon or a full stop, and the gate is full-tree
by design so it would keep blocking every future PR until somebody did this.

Verified with the gate's own checker: 3 findings before, 0 after, across all 150
manifest strings including the src/manifest.d/ fragments.

---------

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>

Author: rubenvdlinde

lib/Controller/ChatStreamController.php

@@ -42,8 +42,8 @@
 use OCA\Hermiq\Service\Engine\SanitizesForSaveTrait;
 use OCA\Hermiq\Service\ToolAccessRequestService;
 use OCA\Hermiq\Service\Engine\StreamYieldChannel;
-use OCA\Hermiq\Service\Engine\ToolGrantResolutionException;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolutionException;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
 use OCA\OpenRegister\Db\ObjectEntity;
 use OCA\OpenRegister\Service\ObjectService;
 use OCP\AppFramework\Controller;

lib/Controller/McpRunController.php

@@ -58,7 +58,7 @@
 
 use OCA\Hermiq\AppInfo\Application;
 use OCA\Hermiq\Service\Engine\RunStepBus;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
 use OCA\Hermiq\Service\Engine\ToolLoop;
 use OCA\Hermiq\Service\Llm\RunTokenService;
 use OCA\Hermiq\Service\ToolSearchService;

lib/Controller/ToolOversightController.php

@@ -39,9 +39,9 @@
 use DateTimeImmutable;
 use DateTimeZone;
 use OCA\Hermiq\AppInfo\Application;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
-use OCA\Hermiq\Service\Engine\ToolGrantSet;
-use OCA\Hermiq\Service\Engine\ToolReachResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantSet;
+use OCA\OpenRegister\Service\Capability\ToolReachResolver;
 use OCA\Hermiq\Service\ToolAccessRequestService;
 use OCA\OpenRegister\Db\AuditTrail;
 use OCA\OpenRegister\Db\AuditTrailMapper;

lib/Mcp/HermiqToolProvider.php

@@ -94,7 +94,7 @@
 use OCA\Hermiq\AppInfo\Application;
 use OCA\Hermiq\Service\CourseRecommendationEngine;
 use OCA\Hermiq\Service\DelegationService;
-use OCA\Hermiq\Service\Engine\ToolReachResolver;
+use OCA\OpenRegister\Service\Capability\ToolReachResolver;
 use OCA\Hermiq\Service\MemoryService;
 use OCA\Hermiq\Service\NcNative\MailReadService;
 use OCA\Hermiq\Service\NcNative\NcNativeWriteService;

lib/Mcp/NcMailToolDescriptors.php

@@ -30,7 +30,7 @@
 namespace OCA\Hermiq\Mcp;
 
 use OCA\Hermiq\AppInfo\Application;
-use OCA\Hermiq\Service\Engine\ToolReachResolver;
+use OCA\OpenRegister\Service\Capability\ToolReachResolver;
 use OCA\Hermiq\Service\NcNative\MailReadService;
 
 /**

lib/Mcp/NcNativeWriteToolDescriptors.php

@@ -28,7 +28,7 @@
 namespace OCA\Hermiq\Mcp;
 
 use OCA\Hermiq\AppInfo\Application;
-use OCA\Hermiq\Service\Engine\ToolReachResolver;
+use OCA\OpenRegister\Service\Capability\ToolReachResolver;
 
 /**
  * Descriptor source for the NC-native write tools.

lib/Repair/CheckOpenRegisterCompatibility.php

@@ -45,6 +45,7 @@
 namespace OCA\Hermiq\Repair;
 
 use OCA\OpenRegister\Event\AgentRunRequestedEvent;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
 use OCA\OpenRegister\Service\Mcp\ToolRegistryFacade;
 use OCP\Migration\IOutput;
 use OCP\Migration\IRepairStep;
@@ -81,6 +82,15 @@ class CheckOpenRegisterCompatibility implements IRepairStep {
 	private const REQUIRED_CLASSES = [
 		ToolRegistryFacade::class => 'OCA\OpenRegister\Service\Mcp\ToolRegistryFacade (OpenRegister #297)',
 		AgentRunRequestedEvent::class => 'OCA\OpenRegister\Event\AgentRunRequestedEvent (OpenRegister #306)',
+		// 🔴 ADDED WITH THE ADR-099 §5 RELOCATION. The capability grammar used to
+		// live in this app, so no version of OpenRegister could be too old to
+		// supply it. Now it can — and without this entry a stale instance would
+		// surface as a bare "Class ... not found" from inside a TOOL CALL, at
+		// whatever hour an agent next ran, rather than as a clear message at
+		// upgrade time. `ToolGrantResolver` is the one to name: every other moved
+		// class arrived in the same commit, and listing five would suggest they
+		// can be present independently.
+		ToolGrantResolver::class => 'OCA\OpenRegister\Service\Capability\ToolGrantResolver (ADR-099 §5 relocation)',
 	];
 
 	/**

lib/Repair/SeedHydraTriageAgent.php

@@ -66,7 +66,7 @@
 namespace OCA\Hermiq\Repair;
 
 use OCA\Hermiq\AppInfo\Application;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
 use OCA\OpenRegister\Db\ObjectEntity;
 use OCA\OpenRegister\Db\SchemaMapper;
 use OCA\OpenRegister\Service\ObjectService;

lib/Service/Assistant/AssistantService.php

@@ -38,7 +38,7 @@
 use OCA\Hermiq\Service\Engine\MessageHistoryHandler;
 use OCA\Hermiq\Service\Engine\ResponseGenerationHandler;
 use OCA\Hermiq\Service\Engine\SanitizesForSaveTrait;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
 use OCA\Hermiq\Service\GuardrailBlockedException;
 use OCA\Hermiq\Service\GuardrailPolicyService;
 use OCA\OpenRegister\Db\ObjectEntity;

lib/Service/DelegationService.php

@@ -46,8 +46,8 @@
 use OCA\Hermiq\AppInfo\Application;
 use OCA\Hermiq\Service\Engine\DelegationContext;
 use OCA\Hermiq\Service\Engine\DelegationFrame;
-use OCA\Hermiq\Service\Engine\ToolGrantResolver;
-use OCA\Hermiq\Service\Engine\ToolReachResolver;
+use OCA\OpenRegister\Service\Capability\ToolGrantResolver;
+use OCA\OpenRegister\Service\Capability\ToolReachResolver;
 use OCA\OpenRegister\Db\AuditTrailMapper;
 use OCA\OpenRegister\Db\ObjectEntity;
 use OCA\OpenRegister\Service\ObjectService;