recon_gen.common.l2.loader

YAML → L2Instance loader.

Single entry point load_instance(path) reads an L2 YAML file, walks the top-level sections (accounts / account_templates / rails / transfer_templates / chains / limit_schedules), and emits a fully-typed L2Instance per the SPEC.

What this module does: - YAML parsing via yaml.safe_load (file/line in syntax errors comes

from PyYAML for free).

Required-field + type-shape checks per primitive (e.g. Account.id is required + must be a string).
Decimal(str(value)) coercion for every Money-typed field via the shared _load_money helper (per F4 — dodges YAML float precision).
InstancePrefix regex + length validation via _load_instance_prefix (per F5 — pinned in SPEC as ^[a-z][a-z0-9_]*$, max 30 chars).
Rail discrimination: presence of source_role / destination_role → TwoLegRail; presence of leg_role / leg_direction → SingleLegRail; both or neither → error.
RoleExpression normalization: a single string YAML value becomes a 1-tuple; a YAML list of strings becomes a tuple.

Cross-entity validation (M.1.3 validate.py) runs automatically as the last step of load_instance (per M.2d.2 — every cross-entity rule is a YAML parse-time error by default). The loader still owns syntactic + per-entity errors; the validator owns reference-resolution, cardinality, state-dependent, vocabulary, and per-leg-Origin rules. Tests that need to construct intentionally-incomplete instances may opt out via load_instance(path, validate=False).

Errors raise L2LoaderError (loader-side) or L2ValidationError (validator-side) with a logical path (e.g. accounts[2].id) so the caller can pinpoint the bad field.

Functions

`default_l2_bytes`()	Raw bytes of the packaged default `spec_example.yaml`.
`default_l2_instance`()	Load + validate the persona-neutral default `spec_example` instance.
`load_instance`(path, *[, validate])	Load + validate an L2 YAML file into an `L2Instance`.

Exceptions

L2LoaderError

Raised when an L2 YAML fails to load or fails per-entity validation.

exception recon_gen.common.l2.loader.L2LoaderError[source]

Bases: ValueError

Raised when an L2 YAML fails to load or fails per-entity validation.

recon_gen.common.l2.loader.default_l2_bytes()[source]

Raw bytes of the packaged default spec_example.yaml.

For the audit fingerprint / provenance hash of the no---l2 case — hashing the exact bytes the default is loaded from keeps the fingerprint deterministic + byte-identical to what the report claims it hashed.

Return type:: bytes

recon_gen.common.l2.loader.default_l2_instance()[source]

Load + validate the persona-neutral default spec_example instance.

The one built-in default every app’s build path uses when the caller doesn’t supply an explicit l2_instance. Pass load_instance(".../sasquatch_pr.yaml") for the canonical persona demo.

Return type:: L2Instance

recon_gen.common.l2.loader.load_instance(path, *, validate=True)[source]

Load + validate an L2 YAML file into an L2Instance.

By default (validate=True), runs the full cross-entity validation pass (common.l2.validate.validate) before returning, so a malformed instance fails at YAML load time rather than at first render. This is the M.2d.2 contract — every cross-entity SHOULD-constraint listed in the SPEC’s Validation Rules section is a parse-time error by default.

Pass validate=False to skip the cross-entity pass — useful for narrow loader tests that intentionally exercise partial fixtures without satisfying every reference-resolution rule.

Loader-side errors (malformed YAML, missing required fields, type shapes, identifier format, Money coercion) raise L2LoaderError. Validator-side errors (reference resolution, uniqueness, cardinality, vocabulary, Origin resolution) raise L2ValidationError.

Y.2.gate.c.12 — when RECON_GEN_RUN_DIR is set, the raw YAML is captured to <run-dir>/l2/<instance-prefix>.yaml for per-run debugging. See _capture_to_run_dir.

Return type:

L2Instance

Parameters:

path (Path | str)
validate (bool)