Errors¶

Every failure bloomery raises derives from BloomeryError — one except BloomeryError catches everything — and every class lives in bloomery.errors, importable without pulling in any pipeline stage.

The hierarchy¶

BloomeryError
├── SpecParseError
├── UnknownTransformError
├── TypeCheckError
├── TransformRegistrationError
├── ResolutionError
│   ├── CircularDerivation
│   └── MissingReference
├── GuardrailError
│   ├── UnitMismatch
│   ├── TaxBasisMismatch
│   ├── CurrencyMismatch
│   ├── GrainMismatch
│   ├── AdditivityViolation
│   ├── AssertLoweringError
│   ├── GrainViolation
│   ├── FanoutRisk
│   ├── NonAdditiveWithoutComponents
│   ├── MartMissingTimeDimension
│   ├── QuarantineRetentionMissing
│   ├── DedupeTieBreakMissing
│   ├── DedupeDispositionConflict
│   ├── IngestionMetadataMissing
│   └── RedactionConflict
├── PlanError
│   ├── ContractViolation
│   └── RenameTargetMissing
├── EmitError
│   └── UnsupportedByTarget
└── PlannerError
    ├── UnknownMember
    ├── UnreachableAtGrain
    ├── AmbiguousDimension
    ├── InvalidRequest
    ├── FilterTypeMismatch
    └── UnsupportedFilter
        ├── UnsupportedSetRelation
        ├── UnsupportedHierarchy
        ├── UnsupportedTextOperator
        ├── FilterTooComplex
        ├── UnsupportedNegation
        ├── InvalidLiteral
        ├── UnsupportedSortNulls
        ├── UnsupportedPagination
        ├── UnsupportedFieldCompare   (adapter-owned)
        └── UnsupportedQuantifier     (adapter-owned)

Per class¶

Data-quality refusals without their own class¶

Five data-quality guardrails have named leaves (above). The rest raise a bare GuardrailError — the design authority names five, and minting further classes would put names in bloomery.errors no RFC has decided on. Each is still a distinct, addressed message inside the same batched aggregate:

Data-quality refusals also happen at emit time rather than compile time, and those are UnsupportedByTarget. Two are about the dialect, both on the absent NULL-on-failure cast: compiling an entity with coercible rules for Postgres (RFC 0016 D30), and — because the ingestion-metadata audit asserts _ingested_at casts to timestamp, which is a TRY_CAST of its own — compiling a dedupe-only entity for Postgres too, even though it carries no quality rules at all (D31). One is about the target: a quarantine: block or a reconcile: check compiled for dbt, which lowers neither in this wave. All of them name the target or dialect that does support the construct.

The closed refusal list¶

The UnsupportedFilter family is a closed, reviewed list (RFC 0015), not drift: every construct the query vocabulary cannot express was refused deliberately, with a named error and a rationale. The stable .reason codes raisable by bloomery's three parse functions (parse_filter_json, parse_sort_json, parse_page_json) are exported as bloomery.planner.KNOWN_UNSUPPORTED and drift-guarded by test — adapters key their refusal handling (HTTP problem responses, UI messages) on .reason, and assert their own refusal sets against the export. Anything not on the list must translate; growing the list is a reviewed decision, never an accident.

A refusal is not the same thing as malformed input. The parse functions raise UnsupportedFilter only for constructs the vocabulary reviewed and declined (some during tree construction, some after the rewrite — see the API reference) — a document that is simply ill-formed (a non-mapping payload, a field map of the wrong shape, an unknown $op, an operand of the wrong type, a nulls value that is neither "first" nor "last", a non-int limit) raises InvalidRequest and never carries a .reason from the closed list. Handle the two separately: a .reason is a product decision to surface, an InvalidRequest is a caller bug to fix.

source_path¶

Every error carries an optional source_path — a dotted/bracketed address into the authored document, prefixed with the document's name (the key you passed to load_project, or a deterministic label like mapping[shop__orders->order] where parsed models no longer know their file):

mappings/shopify.yaml: fields.unit_price.from

The parse stage always sets it; later stages set it best-effort.

Batching¶

The parse, resolution, and guardrail stages batch: they collect every individual failure in the stage and raise one aggregate whose message lists every path, so a spec is fixed in one round-trip rather than one error at a time. On an aggregate, exc.collected holds the individual errors as a tuple for machine consumption; BloomeryError.from_collected(errors) is the constructor that builds one. A stage with a single failure raises that failure directly, uncollected.

Planner errors are deliberately not batched — a request fails on its first problem, because request-time callers want one actionable refusal, not a report.