Skip to content

Design: 0.6 safe-API accounting

Status: accepted for milestone 0.6
Milestone: 0.6
Related: ADR-018–ADR-021, COMPATIBILITY.md

Goal

Produce a header-derived inventory of public Redland librdf 1.0.17 symbols with zero unclassified entries, and map each symbol to a safe Rust surface, ownership non-applicability, or an explicit exclusion.

This milestone claims safe API accounting, not C ABI parity.

Inputs

Input Pin
Redland source redland-1.0.17.tar.gz from http://download.librdf.org/source/
SHA-256 recorded in compatibility/baseline/redland-1.0.17.sha256
Headers public src/rdf_*.h and librdf.h (exclude *_internal.h)

Generation: scripts/generate-redland-inventory.py extracts librdf_* function declarators from those headers and merges curated 0.1–0.5 rows where IDs already exist.

Regeneration must not silently rewrite classifications: the generator emits a skeleton or merges by ID; human/ADR classifications in the checked-in 0.6 manifest are authoritative.

Classification rules

State Meaning
verified Safe mapping exists with linked tests
implemented Code exists; behavioral evidence incomplete
mapped Documented mapping; implementation pending (not allowed at 0.6 exit)
not-applicable Replaced by Rust ownership / std collections (ADR-016, free/new pairs)
excluded Out of safe-Rust scope with impact assessment (storage plugins, factory registration of unsupported engines, C-only allocators)
unreviewed Forbidden at 0.6 exit

Subsystem defaults

  • Ownership (librdf_new_* / librdf_free_* where RAII applies): not-applicable
  • hash / list: not-applicable (ADR-016)
  • digest / uri / utf8 / files / heuristics: utility mappings → verified
  • log / world / init: World → verified
  • model / statement / node / stream / iterator: facade → verified
  • parser / serializer: io → verified (unsupported syntaxes already Unsupported)
  • query: Query / Update / results → verified
  • storage: memory + Fjall → verified; other plugins → excluded
  • concepts: utility::vocab → verified
  • factory register/unregister for custom engines: excluded (ADR-018)
  • raptor bridge helpers used only for C embedding: excluded or not-applicable when superseded by Oxigraph I/O

Deviation template

For each excluded entry (and material behavioral deviations):

impact: …
workaround: …
owner: oxiland maintainers
review_date: YYYY-MM-DD

Stored in the inventory entry deviations list and/or notes.

Naming freeze (1.0 intent)

Public modules intended to remain stable:

  • oxiland::{Model, World, Query, Update, Error, …} root re-exports
  • oxiland::terms
  • oxiland::io
  • oxiland::storage
  • oxiland::utility (+ vocab)
  • Advanced escapes: oxiland::io::primitives, oxiland::sparql

Breaking renames after 0.6 require an ADR and CHANGELOG entry.

Feature and error semantics

  • Closed Error variants in the library crate; new categories need an ADR.
  • Unsupported Redland factories/options return Error::Unsupported, never silent success.
  • World features remain string-keyed FeatureValue registry (no new global mutable logger).

Evidence

  • Manifest: compatibility/inventory/redland-1.0.17-oxiland-0.6.json
  • Validator: scripts/check-inventory.py (milestone 0.6 forbids unreviewed)
  • Report: docs/reports/0.6.md