Module frontmatter 

Frontmatter parsing — port of src/rac/core/frontmatter.py plus the bounded PyYAML-1.1 SafeLoader subset it rides on (PORT-CONTRACT.d/02).

This is parity landmine #1: the oracle is PyYAML 6.0.3’s pure-Python SafeLoader (full YAML 1.1) subclassed with three guards — duplicate-key rejection, alias rejection, and a 32-level node-count depth cap. Byte parity requires reproducing PyYAML’s implicit resolution, its error problem strings, and CPython repr() formatting inside issue messages. The scanner/parser/composer/constructor below are direct ports of the corresponding PyYAML modules (message strings verbatim).

Known oracle crashes (PORT-CONTRACT decision 3): several inputs crash the oracle with uncaught non-YAML exceptions (unhashable mapping keys, explicit-tag/value mismatches like !!int '', out-of-range dates such as 2026-13-01, !!map on a non-empty scalar/sequence, and CPython’s 4300-digit int<->str conversion limit). This port does NOT crash: every such path returns a distinguishable internal issue (code internal-oracle-divergence) whose message mirrors the Python exception ("TypeError: unhashable type: 'list'", …). The marker is intentional and the parity harness treats it as the documented divergence class.

Integers are unbounded like Python’s int: values beyond i64 construct Yaml::BigInt (sign + decimal digits) instead of overflowing, and duplicate-key equality / repr() / validator messages follow CPython semantics for them exactly.

Structs

ArtifactMetadata

ArtifactRead

BigInt

Arbitrary-precision integer (sign + decimal digits), mirroring Python’s unbounded int for values outside i64 (PORT-CONTRACT 02 §4: the YAML 1.1 int constructor never overflows).

FrontmatterSplit

Issue

Enums

FileCap

The per-file byte cap at the READ stage.

SchemaVersion

ArtifactMetadata.schema_version: Python keeps the parsed int as-is, which can exceed i64 (an unsupported-but-integer version is stored with only an issue recorded). Display matches Python str(int).

Yaml

Constants

DEFAULT_MAX_FILE_BYTES

MAX_FRONTMATTER_BYTES

MAX_FRONTMATTER_DEPTH

SUPPORTED_SCHEMA_VERSIONS

Functions

exceeds_byte_cap

exceeds_byte_cap(text, cap): true when text exceeds cap UTF-8 bytes. (The oracle’s char-count shortcuts are a pure optimization; Rust len() is already the UTF-8 byte length.)

file_cap

The per-file byte cap, honoring DECIDED_MAX_FILE_BYTES — Python int() semantics (Unicode digits, underscores, unbounded magnitude; unparseable or non-positive overrides fall back to the default). Shared parser with markdown::max_file_bytes_from so the read and parse stages agree.

file_cap_from

is_valid_id

^[A-Z][A-Z0-9]{1,9}-[0-9A-HJKMNP-TV-Z]{12}$ over the normalized id.

load_frontmatter_mapping

The envelope load (_load_frontmatter_mapping): oversize gate, bounded YAML load, exception→issue mapping, non-mapping rejection. Public so the conformance vectors can compare the loaded value model directly.

non_utf8_issue

normalize_id

Canonical (uppercase) form of an artifact ID (Python strip().upper()).

oversize_file_issue

“file cap” wording — emitted by parse_file for an oversized file.

oversize_parse_issue

“parse cap” wording — emitted by parse for oversized text. Pinned as distinct from the file-cap wording; do not unify.

parse_frontmatter

Parse and schema-validate raw frontmatter YAML.

py_eq

Python == over the constructed values: numeric cross-class equality (1 == True == 1.0), and NaN keys compare equal to each other because PyYAML returns the one shared nan_value object (identity hit in the oracle’s duplicate-key set).

read_artifact_text

The read stage of parse_file: size check, capped read, strict-then-lossy UTF-8 decode (errors="replace", one U+FFFD per bogus byte — Rust’s from_utf8_lossy follows the same WHATWG policy).

split_frontmatter

Split a leading --- frontmatter block from text — LF-only line split (CRLF leaves \r in raw), Python-whitespace .strip() on delimiter lines (BOM and U+200B are NOT whitespace and defeat the delimiter).

unterminated_issue

The unterminated-frontmatter issue markdown.parse appends when split.raw is None and split.unterminated.

yaml_load_config

Full-document YAML load for the strict .decided/config.yaml readers (decided gate, decided.services.init._parse_config_yaml): Ok(root) on a clean parse, Err(problem text) otherwise. The oracle embeds PyYAML’s exact multi-line exception prose in its invalid YAML: <exc> message; that prose is not byte-reproducible here (stderr is out of parity scope), so the error text is the engine’s own parse problem.