---
typeId: req
recordId: benac-int-003
fields:
  title: Stable diagnostic format
  statement: >-
    Benac shall define stable machine-readable diagnostic structures and diagnostic
    classification codes for validation, package authoring, package build, fixture
    execution, trust, capability, cryptographic, missing artifact, artifact CID
    mismatch, schema validation, WASM package-host calling convention, resource limit,
    storage, compute, encryption, decryption, package import, and invocation failures.

    A stable diagnostic classification code shall identify a portable Benac failure
    class or contract boundary, not an exhaustive root cause.

    The meaning of a stable diagnostic classification code shall not silently change
    across conforming implementations.

    Diagnostic records shall support at least diagnostic object type and schema version,
    stable diagnostic classification code, diagnostic code registry identifier where
    relevant, severity, phase or operation class, package CID, descriptor snapshot CID,
    package interface identifier, invocation contract snapshot CID where relevant,
    request snapshot CID, output snapshot CID, schema ruleset identifier, WASM package-
    host calling convention identifier where relevant, resource limit report reference,
    or other applicable context; origin of the diagnostic; origin-specific code,
    message, status, or structured payload where relevant; normalized details for the
    stable diagnostic classification code where defined; raw diagnostic evidence inline
    or by CID/encrypted reference where practical and safe; and redaction, truncation,
    encryption, omission, or unavailability metadata where raw evidence is not fully
    stored.

    Human-readable messages, origin-specific codes, provider responses, stack traces,
    runtime traps, logs, and package-provided error bodies can be useful evidence, but
    they shall not replace the stable diagnostic classification code required for
    recognized failures.

    The diagnostic-code registry shall include at least `package.document.invalid`,
    `package.unknown_required_field`, `package.schema_ref.unresolved`,
    `schema.unsupported_ruleset`, `schema.unsupported_keyword`,
    `schema.validation_failed`, `artifact.missing`, `artifact.cid_mismatch`,
    `invocation_contract.snapshot_mismatch`,
    `operation.not_currently_mediated_by_this_station`, `operation.not_yet_determined`,
    `operation.attempt_denied`, `operation.attempt_failed`, `wasm.import_forbidden`,
    `wasm.export_missing`, `wasm.calling_convention_invalid`,
    `resource.limit_exceeded`, `fixture.invalid`, `fixture.output_mismatch`,
    `fixture.effect_mismatch`, `capability.undeclared`, `capability.denied`,
    `capability.grant_missing`, `capability.expired`, `capability.revoked`,
    `capability.conflicted`, `approval.requirements_not_satisfied`,
    `package_import.input_unsupported`, `package_import.failure_record_required`,
    `package_bundle_zip.invalid`, `package_bundle_zip.unsafe_path`,
    `package_bundle_zip.duplicate_path`, `package_bundle_zip.resource_limit_exceeded`,
    `package_bundle_zip.manifest_missing`, `package_bundle_zip.manifest_invalid`,
    `package_bundle_zip.entry_missing`, `package_bundle_zip.entry_undeclared`,
    `package_bundle_zip.entry_cid_mismatch`,
    `package_bundle_zip.entry_role_unsupported`,
    `package_bundle_zip.object_type_unsupported`,
    `package_bundle_zip.schema_version_unsupported`, `cid.invalid`,
    `cid.codec_unsupported`, `cid.hash_unsupported`, `cid.string_malformed`, and
    `diagnostic.unclassified`.

    Package import diagnostic classification codes shall not depend on filename or file
    extension.

    Diagnostic classification codes shall not classify packages.

    Diagnostic classification codes shall not classify how package work is performed.

    `diagnostic.unclassified` shall be used only when no more specific supported
    diagnostic classification code applies, and diagnostic records using it shall
    include origin, context, and raw or origin-specific evidence where practical and
    safe.
  rationale: >-
    Stable diagnostics let agents, users, and independent implementations distinguish
    content failure, missing grants, unavailable artifacts, not-currently-mediated
    operations, and failed attempts without relying on human text.
  verification: >-
    Diagnostic conformance tests verify each registered diagnostic code, required
    context fields, raw evidence disposition, and no substitution of human-readable
    messages for stable codes.
  testable: true
  status: draft
  area: BENAC-INT
  sourceDocument: user-requested schema-first requirements cleanup
  sourceVersion: 2026-05-06
  sourceSections:
    - Interoperability and conformance
  order: 169
---
