Package com.tnsai.agents.validation.validators

Class CapabilityClasspathValidator

java.lang.Object
com.tnsai.agents.validation.validators.CapabilityClasspathValidator
All Implemented Interfaces:
Validator
public final class CapabilityClasspathValidator extends Object implements Validator
AGENT-V007 — Verify every @Capability-annotated interface implemented by an attached role can be fully reflected upon at build time.

The common shape — class MyRole implements Summarizer where Summarizer is a @Capability interface — is already protected by the JVM: if Summarizer were missing from the classpath, MyRole's class loader would fail before the role was ever attached. So the trivial "interface loaded?" check is moot.

What this validator catches is the subtler packaging miss:

  • The capability interface loads, but one of its method's parameter or return types references a class only available in a sibling jar that was excluded from the deployment artifact. Java loads parameter / return types lazily, so class MyRole implements Summarizer can succeed even when Summarizer.summarize(SummaryOptions) would throw NoClassDefFoundError on first reflection.
  • The capability interface declares an annotation whose value references a missing class — getAnnotation() throws TypeNotPresentException at first lookup.

Today these surface at first dispatch as a stack trace whose root cause is far from the actual configuration mistake; this validator surfaces them at build() time with the offending role + capability + missing-type in the issue context.

Scope: walks every role's class, filters getInterfaces() to @Capability-annotated interfaces, and for each one attempts to enumerate methods, resolve generic parameter / return types, and read annotations. Anything that throws TypeNotPresentException, NoClassDefFoundError, or LinkageError during that walk produces an ERROR.

Suppress with AgentBuilder.relaxValidation("AGENT-V007") — useful when the operator deliberately ships a slimmed-down deployment and accepts that some capability methods will never be dispatched at runtime.

Since:
0.5.0 (issue #85 slice)

  • Constructor Details

    • CapabilityClasspathValidator

      public CapabilityClasspathValidator()

  • Method Details

    • id

      public String id()
      Description copied from interface: Validator
      Short, stable id for logging and test assertions (e.g. "llm-presence").
      Specified by:
      id in interface Validator

    • validate

      public List<ValidationIssue> validate(ValidationContext ctx)
      Description copied from interface: Validator
      Inspect the agent configuration and return any issues detected. Returning an empty list means "no problems found by this validator".
      Specified by:
      validate in interface Validator
      Parameters:
      ctx - frozen view of the agent under construction
      Returns:
      zero-or-more issues; never null