From d8dcf45b0fa3c56066b818df4ad83ecacdea6ae7 Mon Sep 17 00:00:00 2001 From: Igor Prilepov Date: Sat, 19 Sep 2026 12:29:44 -0700 Subject: [PATCH] Prepare v0.1.30-rc.3 release notes --- release-notes-v0.1.30-rc.3.md | 194 ++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 release-notes-v0.1.30-rc.3.md diff --git a/release-notes-v0.1.30-rc.3.md b/release-notes-v0.1.30-rc.3.md new file mode 100644 index 0000000..0aa3424 --- /dev/null +++ b/release-notes-v0.1.30-rc.3.md @@ -0,0 +1,194 @@ +# Quarry v0.1.30-rc.3 + +Quarry v0.1.30-rc.3 is a release candidate for the deterministic, +language-neutral schema compiler and BRF serialization framework. Relative to +RC2, this candidate completes the host-side QBS/BRF inspection workflow. It is +an additive tooling and reflection update; it does not introduce a new +serialization architecture. + +## Highlights since RC2 + +- Added public generic-C access to validated QBS strings, record names, field + names, enum type names, and canonical record identities. +- Added the streaming generic BRF printer, `quarry_brf_print()`, built on the + existing generic traversal API. +- Added the installed `quarry-brf-inspect` host tool for schema-independent + inspection of validated BRF records. +- Added reflective QBS generation through `--qbs-reflective`. +- Added QBS record discovery through `--list-records`. +- Added actionable inspector diagnostics for input files, selectors, + malformed data, output limits, and resource failures. + +PR #74 clarified the established release-version policy; it does not change +runtime behavior. + +## Reflective QBS + +Minimal QBS remains the default and remains suitable for runtime selection and +inspection. To include optional record, field, and enum-type display names, +request the existing reflective QBS profile: + +```text +quarry-schema-compiler \ + --emit-qbs schema.qbs \ + --qbs-reflective \ + schema.brd +``` + +Reflective QBS adds display-name metadata already supported by QBS v1. +Canonical record identities remain mandatory independently of reflection. +QBS v1 does not contain symbolic enum-value names; enum values are therefore +shown numerically. + +## Generic BRF printing + +The public generic C API now provides `quarry_brf_print()`. It consumes the +existing `quarry_brf_traverse()` path and produces deterministic, +human-readable diagnostic output. The printer uses a callback-based streaming +writer, caller-owned bounded workspace, and configurable output, work, and +depth limits. It performs no heap allocation in the generic runtime path and +is not a serialization or JSON format. + +## BRF inspection workflow + +The installed host tool can discover records without a BRF input: + +```text +quarry-brf-inspect \ + --qbs schema.qbs \ + --list-records +``` + +Inspect a record by its serialized ID: + +```text +quarry-brf-inspect \ + --qbs schema.qbs \ + --brf record.brf \ + --record-id 1 +``` + +Inspect a record by its canonical identity: + +```text +quarry-brf-inspect \ + --qbs schema.qbs \ + --brf record.brf \ + --record-name benchmark.workload.Workload +``` + +Use `--brf -` to read the BRF record from standard input. + +Canonical identity and display name are distinct. For example, discovery from +the workload schema produces: + +Minimal QBS: + +```text +1 benchmark.workload.Workload +2 benchmark.workload.shared.Child +``` + +Reflective QBS: + +```text +1 benchmark.workload.Workload (Workload) +2 benchmark.workload.shared.Child (Child) +``` + +The canonical identity is the value accepted by `--record-name`; the optional +parenthesized value is only a reflective display name. Minimal QBS therefore +supports record listing, `--record-id`, and canonical `--record-name` without +requiring reflection. QBS has no runtime root-record concept, so discovery +lists every record present in the validated QBS image. + +## Public QBS reflection APIs + +The additive generic C API exposes validated, non-owning string views through +these public operations: + +```text +quarry_qbs_get_string(...) +quarry_qbs_record_name(...) +quarry_qbs_field_name(...) +quarry_qbs_enum_name(...) +quarry_qbs_record_identity(...) +``` + +Returned views refer to the validated QBS input storage. Symbolic enum-value +names remain unsupported because QBS v1 does not store them. + +## Diagnostics + +`quarry-brf-inspect` now identifies input roles and paths, requested selectors, +malformed QBS/BRF data, output-limit exhaustion, and resource failures. For +example: + +```text +quarry-brf-inspect: unable to read QBS file 'schema.qbs': No such file or directory +quarry-brf-inspect: record ID 99 not found +quarry-brf-inspect: output exceeded --max-output-bytes 1024 +``` + +## Compatibility + +- C++ generated-code API epoch: `3`. +- C generated-code API epoch: `2`. +- Python generated-code API epoch: `1`. +- Schema IR version: `1`. +- QBS format version: `1`. +- BRF format version: `2`. + +The post-RC2 changes do not alter these compatibility identities, the QBS +format, the BRF format, or generated-code epochs. + +### Important BRF compatibility warning + +RC2 and RC3 use BRF v2. RC1 used BRF v1. BRF v1 artifacts from +`v0.1.30-rc.1` must not be assumed wire-compatible with the BRF v2 artifacts +in RC2 or RC3. + +Generated code and runtime components should be taken from the same Quarry +release and matching generated-code epoch. Unchanged generated-code epochs do +not by themselves define generic runtime ABI compatibility. + +## Benchmark baseline + +The benchmark baseline from RC2 remains unchanged. Its measurements are +platform-specific and advisory. The comparison of generated-object and QBS +artifact sizes is not a complete application-footprint comparison because both +approaches also require runtime/support code. + +## Known limitations + +- Nested arrays are unsupported. +- Recursive by-value records are unsupported. +- Maps, unions/variants, and bit-fields are outside the current schema model. +- Symbolic enum-value names are not present in QBS v1. +- Protocol Buffers translation remains limited to the documented supported + subset. +- Benchmark timing is advisory and platform-specific. + +## Release version policy + +Normal Git checkouts use the commit-count-derived development version. Official +release artifacts use the numeric version supplied by the release tag through +archive fallback metadata. Accordingly, `v0.1.30-rc.3` artifacts report numeric +version `0.1.30`; the `-rc.3` suffix identifies the release tag and is not part +of the numeric package version. + +## Release and packaging + +The release process builds deterministic source tar and zip archives, Python +wheel and sdist artifacts, release notes, and a SHA-256 checksum manifest. +Official RC3 artifact sizes and checksums will be reported only after the exact +release commit has been tagged and independently validated. RC3 artifacts are +not published to PyPI by this release process. + +## Validation status + +Current main has passed the available native, generic-runtime, interoperability, +strict-C99, packaging, installed-tool, and complete CTest validation, with +CTest currently at `53/53`. The exact RC3 release commit still requires the +separate release-artifact reconstruction, checksum, archive, install, and +publication-readiness audit. Those results are not claimed by these notes.