---
typeId: req
recordId: benac-aud-003
fields:
  title: Queryable inspection
  statement: Benac inspection APIs shall support machine-readable querying or filtering
    of inspectable records by object type, CID, package CID, invocation contract snapshot CID,
    descriptor snapshot CID, interface identifier, request snapshot CID, output snapshot
    CID, actor principal, authenticated session, invocation status, diagnostic
    classification code, capability or effect class, data class, storage lease, compute
    lease, time range, and causal reference where applicable. Large evidence bodies may
    be returned by CID or encrypted reference. Responses shall support host-defined size
    limits, pagination, truncation metadata, redaction metadata, encryption metadata,
    omission metadata, and follow-up retrieval of referenced evidence where authorized.
  rationale: Inspectability is the feedback surface for agent experimentation. Agents
    should be able to ask focused questions such as show failed invocations for this
    package, show diagnostics for this fixture, show denied effects for this descriptor,
    or show raw evidence for this validation failure without depending on prose logs or
    unbounded database dumps.
  verification: Agent API and Host API conformance tests query failed invocations by
    package CID, diagnostics by stable classification code, denied effects by capability
    class, fixture results by package/interface context, and evidence by causal
    reference. Tests verify pagination, redaction metadata, truncation metadata,
    encrypted evidence references, and denied retrieval for unauthorized evidence.
  testable: true
  status: draft
  area: BENAC-AUD
  sourceDocument: operator ticket 266e382d-cab9-4be7-b70c-6cfb7b49dccb
  sourceVersion: 2026-05-04
  sourceSections:
    - 10.10 Invocation, evidence, effects, audit, and tamper-evidence
  order: 115.2
---
