Skip to content

DOC_10_Validation.md

Latest commit

 

History

History
246 lines (191 loc) · 8.55 KB

DOC_10_Validation.md

File metadata and controls

246 lines (191 loc) · 8.55 KB
afad 3.3
version 0.9.0
domain PRIMARY
updated 2026-03-19
route
keywords questions
validation report
validation finding
validation severity
validate book
validate transaction
ftl resource validation
legislative validation
validate fx conversion
fx rate validation
multi-currency validation
how do i validate a transaction?
what is a ValidationReport?
how does finestvx report validation errors?
how do i validate an ftl resource?
how do i validate against a legislative pack?
how do i validate an fx transaction?
how do i check an fx conversion rate?

FinestVX Validation Reference

ValidationSeverity

Enumeration of diagnostic severity levels in a validation report.

Signature

class ValidationSeverity(StrEnum):
    ERROR = "error"
    WARNING = "warning"
    INFO = "info"

Members

Member Value Semantics
ERROR "error" Blocking failure; ValidationReport.accepted returns False
WARNING "warning" Non-blocking advisory
INFO "info" Informational; never blocks acceptance

Constraints

  • Purpose: severity classification for ValidationFinding instances.
  • Type: StrEnum; string-comparable and JSON-serializable.

ValidationFinding

Immutable single finding emitted by a validation workflow.

Signature

@dataclass(frozen=True, slots=True)
class ValidationFinding:
    code: str
    message: str
    severity: ValidationSeverity
    source: str

Constraints

  • All fields are required non-empty strings, except severity which must be ValidationSeverity.
  • source identifies the originating subsystem (e.g. "core.transaction", "ftl.resource", "legislation.lv.standard.2026").
  • Immutable; no mutation after construction.

ValidationReport

Immutable collection of ValidationFinding instances produced by a validation pass.

Signature

@dataclass(frozen=True, slots=True)
class ValidationReport:
    findings: tuple[ValidationFinding, ...] = ()

    @property
    def accepted(self) -> bool: ...

    def require_valid(self, *, component: str, operation: str) -> None: ...

Constraints

  • findings defaults to an empty tuple; an empty report is always accepted.
  • accepted: True when no finding carries ValidationSeverity.ERROR; warnings and info do not block.
  • require_valid: raises ftllexengine.integrity.IntegrityCheckFailedError when not accepted; used at hard-fail boundaries.
  • require_valid populates both monotonic timestamp and wall-clock wall_time_unix in the raised IntegrityContext.
  • Combining reports: ValidationReport(report_a.findings + report_b.findings).

validate_book

Function that validates chart-of-accounts and transaction invariants across a full book aggregate.

Signature

def validate_book(book: Book) -> ValidationReport:

Parameters

Name Type Req Semantics
book Book Y Root aggregate to validate

Constraints

  • Return: ValidationReport with zero or more findings; never raises on validation failures.
  • Runs validate_chart_of_accounts and then validate_transaction for each transaction.
  • Account-reference violations in transactions are collected as separate ERROR findings.
  • Raises: TypeError only if book is not a Book instance (structural precondition).

validate_transaction

Function that validates a single journal transaction within the context of a book.

Signature

def validate_transaction(book: Book, transaction: JournalTransaction) -> ValidationReport:

Parameters

Name Type Req Semantics
book Book Y Provides the known account set
transaction JournalTransaction Y Transaction to validate

Constraints

  • Return: ValidationReport; never raises.
  • Validates balance via validate_transaction_balance; unknown account codes collected as findings.
  • Balance failures are returned as an ERROR finding, not raised.

validate_ftl_resource

Function that runs FTLLexEngine's six-pass static validation pipeline on an FTL source string.

Signature

def validate_ftl_resource(
    source: str,
    *,
    known_messages: frozenset[str] | None = None,
    known_terms: frozenset[str] | None = None,
    known_msg_deps: Mapping[str, frozenset[str]] | None = None,
    known_term_deps: Mapping[str, frozenset[str]] | None = None,
) -> ValidationReport:

Parameters

Name Type Req Semantics
source str Y Raw FTL source text
known_messages frozenset[str] | None N Message IDs already in bundle for cross-resource checks
known_terms frozenset[str] | None N Term IDs already in bundle
known_msg_deps Mapping[...] | None N Existing message dependency maps
known_term_deps Mapping[...] | None N Existing term dependency maps

Constraints

  • Return: ValidationReport; delegates to ftllexengine.validation.validate_resource.
  • Covers all six passes: syntax, structural duplicates, undefined refs, circular refs, chain depth, semantic compliance.
  • Can be used independently of a FluentBundle instance; suitable for CI/CD pipelines.

validate_ftl_resource_schemas

Function that validates FTL message variable contracts against declared expected variable sets.

Signature

def validate_ftl_resource_schemas(
    source: str,
    expected_schemas: Mapping[str, frozenset[str]],
) -> ValidationReport:

Parameters

Name Type Req Semantics
source str Y Raw FTL source text to validate
expected_schemas Mapping[str, frozenset[str]] Y Map of message ID to expected variable name set

Constraints

  • Return: ValidationReport; never raises on contract failures.
  • FTL_SCHEMA_MESSAGE_MISSING (ERROR): a message declared in expected_schemas is absent from source.
  • FTL_SCHEMA_MISMATCH (ERROR): a message exists but its declared variable set differs from the expected set.
  • Uses FluentLocalization.validate_message_variables() internally.
  • Exported from finestvx.validation.

validate_fx_conversion

Function that reconciles cross-currency entries in a journal transaction against a declared exchange rate.

Signature

def validate_fx_conversion(
    transaction: JournalTransaction,
    base_currency: CurrencyCode,
    counter_currency: CurrencyCode,
    rate: Decimal,
) -> ValidationReport:

Parameters

Name Type Req Semantics
transaction JournalTransaction Y Transaction containing entries in both currencies
base_currency CurrencyCode Y Source (debit) currency
counter_currency CurrencyCode Y Target (credit) currency
rate Decimal Y Exchange rate; base_debit_total * rate must equal counter_credit_total within ISO 4217 precision

Constraints

  • Return: ValidationReport; never raises on validation failures.
  • FX_RATE_INVALID (ERROR): rate is not finite and positive.
  • FX_BASE_CURRENCY_ABSENT (ERROR): no entries with base_currency found in transaction.
  • FX_COUNTER_CURRENCY_ABSENT (ERROR): no entries with counter_currency found in transaction.
  • FX_RATE_MISMATCH (ERROR): base_debit_total * rate differs from counter_credit_total beyond ISO 4217 decimal precision for counter_currency.
  • Does not alter the core zero-sum invariant; validates only the cross-currency reconciliation ratio.
  • Exported from finestvx.validation.

validate_legislative_transaction

Function that validates a posted transaction against its book's configured legislative pack.

Signature

def validate_legislative_transaction(
    registry: LegislativePackRegistry,
    book: Book,
    transaction: JournalTransaction,
) -> ValidationReport:

Parameters

Name Type Req Semantics
registry LegislativePackRegistry Y Pack registry used to resolve the book's pack code
book Book Y Supplies book.legislative_pack
transaction JournalTransaction Y Transaction to validate

Constraints

  • Return: ValidationReport; legislative issues map to ERROR findings with source = "legislation.<pack_code>".
  • Raises: KeyError when book.legislative_pack is not registered.
  • Runs in-process (not isolated); for subinterpreter isolation use FinestVXService.validate_transaction_isolated.