Aeonite

Neutral specifications and test suites for meaning-aware data interchange.

Status: Draft informative summary for consolidated v1

License: CC-BY-4.0

Available formats: HTML, Markdown

Appendix — Error Model

Status: informative summary for consolidated v1

Canonical topic owners: ../AEON-v1-compliance.md, ../AEOS-spec-v1.md

If this appendix conflicts with the canonical compliance or AEOS spec, those canonical documents win.

1. Existing Diagnostics

Existing prior-release diagnostics remain valid unless superseded in v1.

2. v1 Policy/Behavior Diagnostics (active)

Core/policy diagnostics retained from prior v1-era behavior summaries use legacy uppercase-style codes:

Code Category Phase Trigger
ATTRIBUTE_DEPTH_EXCEEDED PolicyError policy enforcement address-expression attribute selector depth exceeds active max_attribute_depth
SEPARATOR_DEPTH_EXCEEDED PolicyError parse/policy enforcement separator-spec depth exceeds active max_separator_depth
GENERIC_DEPTH_EXCEEDED PolicyError parse/policy enforcement nested generic type depth exceeds active max_generic_depth
EVENT_COUNT_EXCEEDED PolicyError core validation emitted AES event count exceeds active max_events
INVALID_SEPARATOR_CHAR SyntaxError parse forbidden or malformed separator char in separator spec
INVALID_ESCAPE SyntaxError lex/parse malformed quoted escape, malformed Unicode escape, lone surrogate, or out-of-range code point
UNTERMINATED_STRING SyntaxError lex quoted string crosses a raw newline or EOF before closing delimiter
UNTYPED_TOGGLE_LITERAL ModeError mode enforcement strict toggle literal not typed as toggle
UNTYPED_VALUE_IN_STRICT_MODE ModeError mode enforcement strict-mode value lacks required typing

AEOS validation diagnostics use lowercase snake case:

Code Category Phase Trigger
trailing_separator_delimiter PolicyWarning/Error schema validation (optional) optional AEOS policy: separator literal payload ends with declared separator

Reference implementation policy surfaces:

  • Runtime option: trailingSeparatorDelimiterPolicy (off|warn|error)
  • CLI bind flag: --trailing-separator-delimiter-policy <off|warn|error>

3. Separator-Literal Boundary Clarification

Separator literals do not define a raw escape layer. Outside quoted string segments, the payload ends when ordinary grammar or comment syntax resumes, and disallowed raw characters may surface downstream as SYNTAX_ERROR depending on token context. This behavior is deterministic and expected under v1 separator-literal boundary rules.

4. Determinism Requirements

Diagnostics MUST:

  • fail closed where specified by phase contract
  • include stable code and canonical path context when applicable
  • be deterministic under identical input and policy settings

For the Unicode and quoted-string boundaries clarified in Core v1:

  • malformed quoted escapes SHOULD surface as INVALID_ESCAPE;
  • malformed Unicode escapes, lone surrogate escapes, and out-of-range code

points SHOULD surface as INVALID_ESCAPE;

  • raw newlines inside non-backtick quoted strings SHOULD surface as

UNTERMINATED_STRING.

4.1 Undefined-Case Review Guidance

When an implementation encounters an edge case that is not clearly defined by Core, an adopted convention, a profile, or explicit processor policy, the implementation should treat the case as a question of authority before treating it as a question of convenience.

Recommended review questions:

  1. What exactly is being represented?
  2. What can legitimately be concluded from that representation?
  3. Who or what has authority to make that conclusion?

Claims should not be realized as semantic conclusions until a stage with authority realizes their meaning. Examples of authority-bearing stages include a selected convention, validated schema, trusted profile, processor policy, or consuming application policy.

If no authority-bearing stage is selected, implementations should avoid materializing a conclusion. Depending on the active mode and processing surface, the implementation should preserve the claim as opaque data, ignore the unsupported semantic layer, or fail closed with a deterministic diagnostic.

5. Phase Presentation

Human-facing diagnostics SHOULD present the pipeline phase as a readable label rather than as a bare numeric band.

Recommended plain-text form:

  • <Phase Label>: <message> [CODE] path=$.x span=1:1-1:4

Example:

  • Reference Validation: Self reference: '$.a' references itself [SELF_REFERENCE] path=$.a span=1:1-1:4

JSON diagnostics MAY additionally include:

  • phase when the producing phase is explicitly known
  • phaseLabel when a stable human-readable phase name is available

When both are present, code remains the stable machine-facing identifier and phaseLabel is presentation metadata.

6. Payload Expectations

When applicable, diagnostics should include:

  • offending path/type context
  • observed depth
  • active policy limit
  • source span (if available)

7. Reporting Specification Gaps

When an undefined edge case appears to expose a specification gap, report it to the AEON specification authority with enough information for deterministic review.

Reports should include:

  • the smallest AEON input that demonstrates the case
  • the processing stage where the ambiguity appears
  • the active mode, conventions, profiles, schemas, and processor policy
  • observed implementation behavior
  • the expected or proposed behavior, if known
  • whether the issue affects conformance, interoperability, security, or only local implementation behavior

Specification questions belong with aeonite-org/aeonite-specs. Conformance-test questions belong with aeonite-org/aeonite-cts.