OpenRegister silently drops portalMessage when it carries x-openregister-mcp — import still reports success

[rubenvdlinde]

portalMessage is the only schema in portaliq_register.json that carried
x-openregister-mcp, and it was the only one of thirteen that OpenRegister
would not import. The E2E seed said so on every run since #112:

[ci-seed] settings#load HTTP 200
{"success":true,"message":"Configuration imported successfully.","version":"0.12.0"}
[ci-seed] schemas present: [... 12 slugs, no portalmessage ...]
##[error]Portaliq schemas missing after import: ['portalMessage']

Note the shape of that: the import reports success, and one schema is
silently absent. Nothing in the response says a schema was rejected.

Bisect

Measured against the E2E job, not inferred:

commit	E2E
ac96e1cc — before #112	success
c287056f — the #112 merge, which adds the dialect	failure
every run since	failure

The dialect looked valid

Which is why this needs someone who knows the importer:

• both verbs declare scope: read and readOnlyHint: true
• both carry agent-facing description prose
• all three search.filters — read, organisation, subjectRef — name real
  declared properties of portalMessage, so McpAnnotationValidator::validateFilters()
  should accept them

So the documented rules appear satisfied and the schema is still dropped.

What was done for now

The dialect is removed (portaliq#153's follow-up) so the register returns to the
shape that last seeded green — 13 schemas, 13 authorization blocks. The portal
inbox has a data surface again.

What is actually wanted

1. Why does OpenRegister reject this schema? If it is a validator rule, the
   error needs to surface — an import that answers "success": true while
   dropping a schema is the worst possible failure mode, and it cost this repo
   every E2E run for as long as the dialect was in place.
2. Once understood, reintroduce MCP on portalMessage. The intent behind portaliq-mcp-adoption: built by hydra for #111 #112
   was sound: a read-only search/get surface over portal inbox messages, with
   portalAccount, portalSession and exampleDocument deliberately excluded
   so no derived tool can return an IdP claims blob or a session jti. That
   exclusion is still asserted by
   PortaliqRegisterConfigTest::testIdentityAndSessionSchemasCarryNoMcpDialect,
   which is kept precisely so it starts doing real work again the moment a
   dialect returns.

[github-actions]

Thank you for opening this issue! It has been assigned to @rubenvdlinde for review.

What happens next:

1. A maintainer will review this issue and determine the appropriate action
2. If accepted, it may be converted into an OpenSpec change for structured development
3. You will be notified of any status changes

Triage labels:

• triage:accept-feature — accepted as a new feature
• triage:accept-bugfix — accepted as a bug fix
• triage:needs-info — more information needed
• triage:wontfix — will not be addressed
• triage:duplicate — duplicate of another issue

[rubenvdlinde]

Root cause found: the dialect requires an enabled gate, and the verbs were outside tools

Ran OpenRegister's own validator against the exact block that shipped, rather
than reasoning from the documented rules:

$v = new \OCA\OpenRegister\Service\Mcp\McpAnnotationValidator();
$v->validate(['properties' => $pm['properties'], 'x-openregister-mcp' => $pm['x-openregister-mcp']]);

error count: 1
  [mcp-missing-enabled] x-openregister-mcp requires an `enabled` boolean (the opt-in gate).

Two faults at once, and they mask each other:

1. enabled is a REQUIRED opt-in gate. McpAnnotationValidator::validateEnabled()
   emits mcp-missing-enabled when the key is absent. The schema then fails
   save-time validation and the importer drops it — while the overall import
   still reports "Configuration imported successfully".

2. The verbs sat at the top level, not under tools. validateTools()
   returns early when tools is absent, so it never looked at search/get
   at all. Even with the gate present, the block declared no tools while
   reading exactly as though it declared two.

That second point is why the block looked well-formed from this side: every
rule the issue checked (both verbs scope: read, readOnlyHint: true, all
three filters naming real properties) is a rule about the inside of a verb
config, and none of those rules were ever reached.

The correct shape

"x-openregister-mcp": {
  "enabled": true,
  "tools": {
    "search": { "scope": "read", "readOnlyHint": true, "description": "...", "filters": ["read", "organisation", "subjectRef"] },
    "get":    { "scope": "read", "readOnlyHint": true, "description": "..." }
  }
}

Re-validated with that shape: 0 errors, across every schema in the register.

The version bump is load-bearing

An import skips a schema whose deployed version already meets the declared
one, and the escape hatch compares only properties / required /
authorization — never the annotation. So an annotation-only correction at an
unchanged version validates cleanly and still never reaches an instance that
already has the schema. portalMessage has to go 0.2.0 -> 0.3.0 alongside
the fix.

Verified end to end by forcing the import on a live instance and watching the
deployed schema move 0.2.0 -> 0.3.0.

Why nothing caught it

testPortalMessageDeclaresReadOnlyMcpDialect asserted
array_keys($dialect) === ['search', 'get'] — i.e. it pinned the broken
shape — and its docblock said that assertion was what made the validator
accept the schema at import. It never ran the validator. The defect had a green
test sitting on top of it.

Suggested follow-up

Reintroducing the dialect on portalMessage is now a small, reviewable change:
the corrected block, portalMessage to 0.3.0, info.version bumped, and the
pinning test rewritten to assert {enabled, tools}.

I have that change working locally but deliberately did not slip it into a
merge resolution on #151 — #153 removed the dialect as a considered decision,
and reversing that belongs in its own reviewed PR rather than inside a conflict
fix. Happy to open it.

Worth adding a guard that walks every x-openregister-mcp in the register
against the dialect shape and fails when it finds nothing to inspect —
"no schema was checked" and "every schema passed" were exactly the two outcomes
this bug made indistinguishable.