---
typeId: req
recordId: benac-agt-010
fields:
  title: Machine-readable errors
  statement: |
    Agent-facing APIs shall return structured errors for validation failures, package authoring failures, package build failures, fixture failures, trust denials, capability denials, missing blobs, artifact CID mismatches, schema failures, WASM package-host calling convention failures, resource-limit failures, encryption failures, storage failures, compute failures, package import failures, Package Bundle ZIP failures, and conformance failures. Structured errors shall use the stable diagnostic format and diagnostic-code registry defined by Benac, and shall include raw diagnostic evidence inline or by CID/encrypted reference where practical and safe, or shall record why such evidence was omitted, redacted, truncated, encrypted, or unavailable.

    An import failure that occurs before a package CID is derivable shall
    return or persist a package import failure record containing operation
    identifier, input artifact kind, observed media type where available,
    observed filename where available, observed size where available,
    failure phase, primary diagnostic classification code, diagnostic code
    list, diagnostic record references or explicit diagnostic-record
    omission disposition, origin-specific error details where available,
    and raw diagnostic evidence disposition.

    The package import failure response returned to an agent shall expose
    the same primary diagnostic classification code that is recorded in the
    package import failure record.

    The package import failure response returned to an agent shall expose
    or reference the same raw or origin-specific evidence lane that is
    recorded in the diagnostic record.
  rationale: Agents need to recover from problems without guessing, while still being able
    to inspect the underlying evidence when a stable classification code is not specific
    enough.
  verification: Invalid package import, missing artifact, unsupported schema keyword,
    fixture mismatch, forbidden WASM import, missing WASM export, resource-limit
    failure, capability denial, malformed Package Bundle ZIP file, and standalone
    JSON package import file return structured errors containing or referencing
    diagnostic records with stable diagnostic classification codes, required context
    bindings, and raw or origin-specific evidence references where practical and safe.
    A package import failure occurring before a package CID is derivable returns a
    package import failure record carrying operation identifier, input artifact kind,
    observed filename/media type/size where available, failure phase, primary
    diagnostic classification code, diagnostic code list, diagnostic record references
    or explicit diagnostic-record omission disposition, and raw diagnostic evidence
    disposition. The primary diagnostic classification code exposed to the agent
    matches the primary diagnostic classification code in the package import failure
    record, and the raw/origin evidence lane exposed to the agent matches the raw
    evidence lane recorded in the diagnostic record.
  testable: true
  status: draft
  area: BENAC-AGT
  sourceDocument: /home/johnb/Downloads/benac_syrs_v0_4_integrated_authentication.md
  sourceVersion: v0.4
  sourceSections:
    - 10.14 Machine-readable client operation
  order: 162
---
