Docs / Reference

Product surface components

Product-surface components prepare registry, trust, audit, access, verification, and operational-state views before backend behavior exists.

Plain English

These components show how operators should inspect capability state, policy, evidence, and trust without reading raw JSON first.

Why it exists

Public protocol surfaces need product patterns that make unavailable, revoked, empty, loading, and error states explicit before a console or managed provider depends on them.

Formal definition

A product surface is a static or dynamic view over host descriptors, registry rows, policy grants, evidence events, verification status, and operational state.

Concrete example

Ground the concept before the schema.

A registry row can show schedule_technician as verified, approval_required, sync, and evidence-emitting before a caller invokes it.

schedule_technicianVerified

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

Policy boundary

Audited

operator_review

Operators can inspect lifecycle, access, evidence, and trust state before allowing broad capability adoption.

Registry and trust

Expose capability state before invocation.

Product surfaces should let operators scan lifecycle, policy, version, evidence, and verification without opening raw JSON first.

schedule_technician

Verified

Dispatch scheduling is verified for approval-required denial and successful execution paths.

Host
service-ops-host
Version
1.0.0
Checked
2026-06-16
Approval requiredsync

Emits

execution_startedexecution_denied

notify_customer

Deprecated

The current notification contract remains callable while clients migrate to notify_customer.v2.

Host
customer-comms-host
Version
1.4.0
Checked
2026-06-15
Auditedasync

Emits

execution_startedexecution_completed

issue_refund

Unavailable

Refund issuance is visible in discovery, but the current grant is revoked until billing policy is reapproved.

Host
billing-host
Version
0.9.0
Checked
2026-06-14
Revokedsync

Emits

execution_denied

Trust panel

Review

service-ops-host

Trust is a composed view of descriptor validity, policy handling, lifecycle enforcement, and evidence quality.

Descriptor

Pass

HostDescriptor validates and protocol_version is 0.1.

Evidence

Pass

ExecutionEvidence includes event_type, correlation, sequence, and assurance metadata.

Policy

Review

approval_required paths are covered; revoked access still needs operator review.

Lifecycle

Pass

Deprecated and unavailable capabilities remain discoverable with structured outcomes.

Verification seal

Verified

schedule_technician v1.0.0

Conformance evidence covers success, approval_required denial, and replay by correlation ID.

Evidence
18 events
Case
approval_required_denial
Checked
2026-06-16

Access

Make subject policy inspectable.

Access views should distinguish allowed, approval-required, revoked, and blocked states without relying on color alone.

Access matrix

Dispatch operations grants

SubjectCapabilityAccessPolicyEvidence
agent://planning-assistantschedule_technicianApproval requiredmanager_approvalexecution_denied
user://dispatch-managerschedule_technicianAllowedservice:dispatchexecution_completed
agent://billing-helperissue_refundRevokedgrant_2026_04 revokedexecution_denied
agent://ops-summarydelete_service_jobBlockedrisk_tier_exceededexecution_denied

Audit

Preserve the protocol trail.

Audit traces should expose event type, outcome, denial or error code, actor, sequence, and timestamp in one scan path.

Audit trace

session-abc

  1. 01

    execution_started

    15:14:20.000Z

    success

    InvocationEnvelope accepted for schedule_technician.

    actor: agent://planning-assistant

  2. 02

    execution_denied

    15:14:22.104Z

    denied

    manager_approval must approve before execution.

    code: approval_required

    actor: service-ops-host

  3. 03

    execution_skipped

    15:15:02.402Z

    skipped

    issue_refund exists but is unavailable for the current grant.

    code: capability_disabled

    actor: billing-host

Operational states

Design empty, loading, unavailable, revoked, and error states first.

These states carry protocol meaning and should be ready before a registry, console, or managed provider surface depends on them.

Product state

Empty

No capabilities match the filter

Keep the registry frame visible and explain which filter produced an empty result.

Product state

Loading

Refreshing host descriptors

Loading states should preserve table dimensions so registry rows do not jump.

Product state

Unavailable

Capability unavailable

The capability exists, but lifecycle state prevents invocation.

denial.code = capability_disabled

Product state

Revoked

Access grant revoked

A subject may have existed before, but current policy denies the invocation.

denial.code = entitlement_denied

Product state

Error

Host evidence failed validation

Runtime or validation failures need a stable error code and next inspection target.

error.code = host_error

Developer reference

Product-prep component inventory

These components are static candidates for future registry, console, provider, and trust surfaces.

ComponentProtocol sourceState coverage
CapabilityRegistryRowHostDescriptor + CapabilityDescriptor

Lifecycle, policy, version, mode, and emitted evidence.

TrustPanelConformance + evidence checks

Pass, review, and fail states with visible reasons.

AuditTraceExecutionEvidence

event_type, outcome, code, actor, sequence, and timestamp.

AccessMatrixPolicyDescriptor + host grants

Allowed, approval_required, revoked, and blocked access states.

VerificationSealConformance record

Verified, candidate, stale, and failed trust labels.

OperationalStatePanelRegistry and invocation state

Empty, loading, unavailable, revoked, and error states.

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

Registry rows derive from HostDescriptor and CapabilityDescriptor fields.

Trust panels summarize conformance, lifecycle, policy, and evidence checks.

Audit traces and access matrices expose InvocationResult and ExecutionEvidence facts for operators.

Visual model

  1. 01Registry makes capability state discoverable.
  2. 02Trust and verification explain whether the state is reliable.
  3. 03Access, audit, and operational states explain why a caller may proceed, wait, or stop.

Implementation notes

  • Keep product-prep examples static until backend contracts are ready.
  • Represent empty, loading, unavailable, revoked, and error states before shipping registry or console behavior.
  • Use protocol terms in visible labels so operators can connect the UI back to evidence and conformance.

Common mistakes

  • Showing only green or red status without lifecycle or policy labels.
  • Hiding revoked access inside a generic authorization failure.
  • Building a registry table without empty, loading, unavailable, and error states.

Related concepts

Keep reading through the boundary.

Lifecycle reference →Policy states →Evidence events →