Exceptions and Findings

Overview

The framework uses structured findings and typed exceptions to communicate validation issues, evaluation failures and runtime errors.

Unlike traditional error handling based solely on strings, TEKSI framework errors are backed by findings that provide machine-readable severity levels and human-readable messages.

Core Concepts

Findings

A finding represents an individual issue discovered during validation, evaluation or resolution.

Each finding contains:

  • A severity level

  • A human-readable message

Example:

Finding(
    severity=Severity.ERROR,
    message="Provider does not match context provider.",
)

Severity

Severity levels indicate the importance of a finding.

The framework provides three severity levels:

Severity.INFO
Severity.WARNING
Severity.ERROR

Severity values:

  • info

    Informational message. Processing may continue.

  • warning

    Unexpected or undesirable condition. Processing may continue.

  • error

    Invalid state or operation. Processing should fail.

Example:

Finding(
    severity=Severity.WARNING,
    message="Attribute value is deprecated.",
)

Framework Exception Hierarchy

The exception hierarchy is rooted at:

TeksiHookException
└── TeksiHookError
    ├── ValidationError
    │   ├── EffectValidationError
    │   └── SnapshotValidationError
    └── RightsEvaluationError

TeksiHookException

Base class for all framework exceptions.

Applications may catch this exception to handle any TEKSI-related failure.

Example:

try:
    ...
except TeksiHookException:
    ...

TeksiHookError

Base class for framework failures backed by findings.

A TeksiHookError aggregates one or more findings and exposes them through the findings attribute.

Example:

raise TeksiHookError(
    (
        Finding(
            severity=Severity.ERROR,
            message="Invalid provider.",
        ),
    ),
)

Accessing Findings

The findings that caused the exception remain available.

Example:

try:
    ...
except TeksiHookError as error:
    for finding in error.findings:
        print(
            finding.message,
        )

Raising Errors from Findings

The framework provides a convenience method for raising exceptions when error findings are present.

Example:

TeksiHookError.raise_if_errors(
    findings,
)

Only findings with severity ERROR result in an exception.

ValidationError

Base class for validation-related failures.

Validation errors indicate that runtime data, configuration or framework objects violate defined constraints.

Example:

raise ValidationError(
    findings,
)

EffectValidationError

Raised when an effect configuration is invalid.

Examples include:

  • Contradictory effects

  • Invalid effect definitions

  • Unsupported effect combinations

Example:

raise EffectValidationError(
    findings,
)

SnapshotValidationError

Raised when snapshot validation fails.

Examples include:

  • Missing identifiers

  • Invalid snapshot state

  • Inconsistent object state

Example:

raise SnapshotValidationError(
    findings,
)

RightsEvaluationError

Raised when rights evaluation cannot be completed.

Examples include:

  • Invalid rights configuration

  • Unresolvable privilege references

  • Missing ownership information

  • Unsupported evaluation scenarios

Example:

raise RightsEvaluationError(
    findings,
)

Using Findings Instead of Strings

Framework components should prefer findings over unstructured error messages.

Preferred:

Finding(
    severity=Severity.ERROR,
    message="Unknown privilege 'DBW_XYZ'.",
)

Avoid:

raise Exception(
    "Unknown privilege.",
)

Using findings provides:

  • Severity classification

  • Aggregation of multiple issues

  • Consistent reporting

  • Better UI integration

  • Future localization opportunities

Aggregated Errors

A single exception may contain multiple findings.

Example:

raise ValidationError(
    (
        Finding(
            severity=Severity.ERROR,
            message="Unknown privilege.",
        ),
        Finding(
            severity=Severity.ERROR,
            message="Unknown class definition.",
        ),
    ),
)

The exception message is generated from all finding messages.

This allows validators and evaluators to report all discovered errors rather than stopping at the first failure.

Typical Workflow

Validation
     │
     ▼
  Findings
     │
     ▼
raise_if_errors()
     │
     ▼
TeksiHookError
     │
     ▼
  Caller

Design Principles

The exception system is designed around the following principles:

  • Structured error reporting

  • Aggregation of related issues

  • Explicit severity levels

  • Consistent framework-wide behaviour

  • Separation between findings and exception handling