Enforce an exact Neural Link local probe projection

Context

Epic #15184 needs a server-pinned Neural Link surface that exposes exactly three read-only operations to a URL-only local client. The approved source contract lives in D#15173.

Live duplicate sweep: checked the latest 20 open issues, broader GitHub search, recent A2A claims, Knowledge Base tickets, and synced issue/discussion content at 2026-07-14T22:03:33.074Z; no equivalent active ticket exists. Closed tickets under #13056 established tier metadata and list/call projection enforcement, but the shipped read tier remains broader than this exact probe.

Self-selection boundary: externally implementation-eligible now that this ticket pins the OpenAPI-owned contract. Neo maintainers retain architecture and review authority.

The Problem

Neural Link's current root OpenAPI policy defines the broad harness-embedded projection through visible capability tiers. ToolService understands only that named mode; any other mode fails closed. The mechanism correctly applies to both listTools() and callTool(), and a server-forced mode already overrides client _meta.

The local interoperability probe must not reuse the full read tier. It needs exactly:

• healthcheck;
• get_worker_topology;
• get_component_tree with depth no greater than 2 and lean structural output.

A client-supplied hint, missing hint, alternate operation name, depth: -1, omitted depth, or lean: false must not widen that surface. A parallel AiConfig allowlist would duplicate OpenAPI authority and drift from tools/list.

The Architectural Reality

• ai/mcp/server/neural-link/openapi.yaml owns operation IDs and per-operation x-neo-tool-tier metadata.
• Its root x-neo-harness-tool-projection owns the existing tier projection.
• ai/mcp/ToolService.mjs parses that policy once, filters tools/list, and rejects hidden operations during tools/call.
• ai/mcp/server/neural-link/Server.mjs makes a launch-time --tool-projection-mode / NEO_NL_TOOL_PROJECTION_MODE value the server-instance ceiling; client _meta.neoToolProjection is ignored when forced.
• GetComponentTreeRequest.depth currently permits integer values including -1 by description, and lean can be set false. The exact profile therefore requires profile-specific input constraints, not name filtering alone.

The Fix

Add a generic OpenAPI-root exact-profile declaration, separate from but adjacent to the existing tier projection, with a named local-readonly-probe profile. The declaration is the sole authority for its operation IDs and input constraints.

Teach ToolService to parse exact profiles from OpenAPI, project the constrained schemas into tools/list, and apply the same profile-specific validation during tools/call. The local-readonly-probe tree call requires explicit depth 1 or 2 and forces or validates lean structural output; it rejects omitted depth, -1, values above 2, non-integers, and lean: false.

Preserve the full trusted developer/operator surface and the existing harness-embedded tier policy unchanged.

Contract Ledger

Decision Record impact

aligned-with ADR 0020; no ADR amendment. If implementation touches AiConfig despite the OpenAPI-only prescription, ADR 0019 becomes a hard AC and the duplicate authority must be rejected.

Decision Record

NOT_NEEDED — consumes existing OpenAPI and server-forced projection authority.

Acceptance Criteria

• Neural Link OpenAPI declares a generic exact-profile substrate and a named local-readonly-probe profile whose operation set is exactly healthcheck, get_worker_topology, and get_component_tree.
• OpenAPI is the sole profile authority; no AiConfig, CLI-side allowlist, service-local array, or second registry repeats the operation set.
• ToolService derives both tools/list visibility and tools/call authorization from the same parsed exact profile.
• A server forced to local-readonly-probe ignores omitted, forged, or alternate client _meta.neoToolProjection values.
• Unknown or malformed profile names fail closed for both listing and calling.
• The listed get_component_tree schema requires explicit integer depth 1 or 2 and lean structural output; call-time validation rejects omitted depth, -1, values above 2, non-integers, and lean: false.
• Every operation outside the exact three is absent from tools/list and refused by tools/call, including aliases.
• Regression evidence proves the unforced trusted developer/operator surface and existing harness-embedded projection retain their current behavior.
• Focused tests prove list/call set equality and the complete metadata/input-widening negative matrix.
• Changed classes/methods/OpenAPI extensions satisfy Contextual Completeness JSDoc/@summary and inline authority documentation.

Out of Scope

• Listener binding, bearer authentication, Origin/Host middleware.
• Mutation, write locking, admin authorization, or a generalized per-client policy language.
• A broad read-tier redesign.
• The BigData oracle, external readiness receipt, or diagnostic deletion journey.

Related

Parent Epic: #15184
Source: D#15173
Refs #13056

Origin Session ID: 5b19219a-d8ad-4505-864f-19b5eab44a45

Retrieval Hint: #15184 local-readonly-probe x-neo-harness-tool-projection ToolService list call parity depth lean