ADR-010: Assessment Layer

Status: Accepted Date: 2026-03-23 Relates to: ADR-003 (Trust Signal Taxonomy), ADR-004 (Response Format)

Context

The /v1/entities/{entityId}/trust-signals endpoint returns structured trust signals (ADR-003) with verification metadata (ADR-004). LLM agents consume these signals to make decisions on behalf of users — for example, whether to proceed with a purchase. In e-commerce experiments, agents performed better when the response included a purpose-scoped summary: a machine-readable recommendation, reasoning, and human-readable highlights.

The current protocol avoids free-text fields (prompt injection risk) and composite trust scores ("facts, not scores" principle). Adding an assessment layer is a deliberate departure from both principles, bounded by design constraints that limit the risk.

Decision

Add an optional assessment section to the verify response, paired with a context query parameter. The assessment is the authority's interpretation of its own signals, scoped to the agent's purpose. It is separate from the signals array, which remains pure factual data.

Context Parameter

An optional context query parameter on /v1/entities/{entityId}/trust-signals tells the authority what the agent intends to do. The authority uses this to tailor the assessment.

GET /v1/entities/{entityId}/trust-signals?url=...&context=purchase

The parameter is an open string. The protocol defines three well-known values:

Value	Meaning
purchase	The agent is considering a purchase on behalf of its user
inquiry	The agent is gathering information; no transaction is imminent
high-value	The agent is considering a high-value or high-risk transaction

Agents and authorities MAY use additional values beyond this set. Authorities MUST ignore values they do not recognize — returning no assessment or a generic one. Well-known values have standardized context-specific fields in the assessment (see below). Custom values do not; authorities that support them define their own response fields in the extensions object (ADR-020).

The parameter is optional. Omitting it means no assessment or a generic one.

Assessment Object

When present, the assessment object appears at the top level of the verify response alongside signals:

{
  "meta": {
    "responseId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "entityId": "d6f2fdf4-f829-4ce6-a1cc-e2bd957709db",
    "status": "verified",
    "url": "https://www.example.org/de/products/123",
    "context": "purchase",
    "timestamp": "2026-03-23T14:30:00Z",
    "expires": "2026-03-24T14:30:00Z"
  },
  "signals": [ ... ],
  "assessment": {
    "action": "proceed",
    "safeToPurchase": "yes",
    "reasoning": "Verified German business operating since 2019 with 4.2-star rating across 1,247 reviews and active recourse mechanism.",
    "highlights": [
      "Business profile verified and published",
      "Good customer satisfaction (4.2 average rating)",
      "International market presence confirmed"
    ]
  },
  "signature": "..."
}

Required fields (when assessment is present):

Field	Type	Description
action	enum: proceed, caution, decline	Machine-readable recommendation
reasoning	string (max 500 chars)	Why the authority reached this conclusion

Optional fields:

Field	Type	Description
highlights	array of strings (max 200 chars each, max 10 items)	Key facts supporting the recommendation

The schema includes an extensions object so authorities can experiment with new fields without a protocol version bump. Non-standard fields MUST be placed in extensions as self-describing entries — see ADR-020.

Context-Specific Fields

Authorities SHOULD include a string field whose name reflects the agent's context. LLM agents use the field name itself as a semantic signal — "safeToPurchase": "yes" is self-explanatory in a way that "action": "proceed" is not.

Context	Field	Meaning
purchase	safeToPurchase	Whether the authority considers this entity safe for a purchase
inquiry	informationReliable	Whether the entity's published information is reliable
high-value	safeForHighValue	Whether the entity is suitable for a high-value transaction

These fields complement action. action is the universal enum for programmatic agents. The context-specific field is the LLM-friendly signal. Both coexist in the same assessment object.

Design Constraints

The assessment introduces free-text fields and a recommendation — a departure from two protocol principles. These constraints bound the risk:

• Authority-generated, not entity-submitted. The entity being assessed cannot inject content into the assessment. The authority produces the text from its own verified data.
• Character limits. reasoning is capped at 500 characters. Each highlight is capped at 200 characters with a maximum of 10 items. Total assessment payload is capped at 4 KB.
• Signed. The assessment is part of the response body, covered by the authority's Ed25519 signature. The authority is accountable for its interpretations.
• Logged (planned). The assessment will be included in the transparency log hash, making it auditable. See roadmap.
• Optional. Agents can ignore the assessment and process only the signals array. The assessment is a convenience layer, not a requirement.
• Labeled as opinion. Documentation distinguishes the assessment (authority interpretation) from signals (verified facts).

Options Considered

A. Top-level assessment object (chosen). Clean separation between facts (signals) and interpretation (assessment). The assessment has its own schema with minimal required fields and room for experimentation. Pairs with a context parameter for purpose-scoped recommendations.

B. Assessment as an extension signal. Uses the existing TrustSignal envelope. Semantically wrong — the envelope fields (verifiedAt, data) describe verified facts, not interpretations. Mixes meta-level output with raw facts in the same array.

C. Free-form meta field per signal. Adds optional natural language to each signal. Addresses per-signal description but not the summary need. Multiplies the prompt injection surface across every signal.

D. Separate /v1/assess endpoint. Isolates the assessment from the verify response. Clean separation but doubles the API surface, requires a second signed response and log entry, and forces agents to make two calls.

E. Structured flags only (no free text). Replaces reasoning and highlights with boolean/enum fields (identityVerified, highRating). Avoids prompt injection risk entirely. Loses the natural-language format that experiments showed LLM agents consume best.

Consequences

• The protocol acknowledges that LLM agents benefit from pre-digested summaries alongside structured data
• The "facts, not scores" principle is preserved for the signals array; the assessment is a separate, optional, clearly labeled interpretation layer
• The "no free-text fields" guideline gains a bounded exception with explicit prompt injection mitigations
• Authorities can experiment with assessment formats via the extensions object without protocol changes; non-standard fields must be self-describing entries (ADR-020)
• Agents that do not understand the assessment ignore it — forward compatibility is maintained
• The context parameter is an open string with well-known values, allowing agents and authorities to experiment with new intents without a protocol version bump

References

• ADR-003 — Trust Signal Taxonomy (what signals exist)
• ADR-004 — Response Format and Trust Scoring (facts not scores)
• Signal payload size limits — each signal object capped at 4 KB (trust-signals.md, security.md)