Enhancement proposal EPR-0003 Distribution and provisioning proposed

0 of 2 decisions settled 3 assumptions to confirm pinned at 4fcfb4a pull request #133 tracking issue: none (a baseline proposal describes code that already ships, so there is no milestone to track) started: 2026-10-04feature name: distribution_and_provisioning decides: the owner, who alone sets the status to accepted

EPR-0003 0 of 2 settled 3 to confirm

Enhancement proposal EPR-0003 Distribution and provisioning proposed

pinned at 4fcfb4a pull request #133 tracking issue: none (a baseline proposal describes code that already ships, so there is no milestone to track) started: 2026-10-04feature name: distribution_and_provisioning decides: the owner, who alone sets the status to accepted

EPR-0003: Distribution and provisioning

enhancement proposal: proposed

on this record: read, decide, confirm
Started
2026-10-04
Pinned at
4fcfb4a, the commit every code citation below opens at
Decides
the owner, who alone sets the status to accepted
Proposal PR
#133
Tracking issue
none (a baseline proposal describes code that already ships, so there is no milestone to track)
Feature name
distribution_and_provisioning

Summary

matra ships as one crate on crates.io and one package on PyPI, under one name, one version and one attribution. PyPI gets four prebuilt wheels per release, all against CPython's stable ABI from 3.12, plus a source distribution. The models matra parses and embeds with are not shipped: each is pinned in the source by URL, size and SHA-256, downloaded on first use into a directory matra resolves, verified in memory, and loaded from the bytes that were verified. A failure to fetch is reported as I/O, never as an invalid model. A release runs from one workflow that a person approves for each registry, and every artifact carries build provenance a caller can verify.

This is a baseline proposal. It describes the code at the pinned commit and carries forward the reasons that still hold from RFC-0005, RFC-0010 (decision 6), RFC-0011, RFC-0013, RFC-0014 and RFC-0015. A later proposal that changes any of it says so. Unmarked statements about the code are observed at the pinned commit through the link beside them; a claim that is inferred or assumed says so.

Motivation

A caller meets this foundation before any other: pip install matra, cargo add matra, and the first run that has no model yet. Each decision here was made after that first meeting went wrong.

Wheels for the platforms people actually run. Two clean-room installs before 0.2.0 found that the wheels missed Linux on arm64, required glibc 2.34, and were tied to CPython 3.12, so most first installs fell to a source build, which then failed for want of a C++ compiler (RFC-0014). The stable ABI and a manylinux container fixed all three at once.

A model is pinned, not named. matra downloads exactly one artifact set per model, the one whose digest is a constant in its source. That is what makes a download acceptable in a library at all (RFC-0010 decision 6, as amended by RFC-0011): what matra refuses is unpinned network access, fetching whatever a name resolves to today.

A failed fetch must say what failed. A clean-room pass measured a first run that wrote nothing for up to 35 seconds, had no timeout at all, left a 15 MB orphan on Ctrl-C, and reported DNS, TLS and full-disk failures as "invalid model" (RFC-0015). The provisioning code today answers each of those.

Publishing is irreversible. Every downstream build inherits matra's supply-chain posture, so publishing runs from a least-privilege workflow with no stored registry token and waits for a person (RFC-0005).

Guide-level explanation

Installing

  • pip install matra or uvx matra gets a prebuilt wheel on Linux x86_64 and aarch64 (glibc 2.17 and later), and macOS x86_64 and arm64, for every GIL-enabled CPython from 3.12 on. The wheel carries the library, the Python bindings and the command line, and has no runtime dependencies observed pyproject.toml:5-42.
  • cargo add matra gets the library with UDPipe; cargo install matra --features cli gets the binary.
  • Building from source, by either route, needs Rust 1.88 or later and a C++ compiler, because UDPipe is C++ observed Cargo.toml:1-14 grounds for decision 1.
  • Windows has no wheel.

The first run

The first call that needs the parsing model downloads 16 MB from LINDAT into the model directory (by default ~/.local/share/matra/models; EPR-0004 gives the resolution order). The command line says so on stderr, naming the file, its size, the directory and the model's licence; the library says nothing itself and hands a caller who wants to say something a ProvisionNotice observed domain.rs:34-72:

let engine = matra::Engine::from_config_with_notice(&cfg, |n| {
    eprintln!("fetching {} ({} bytes) into {}", n.artifact, n.bytes, n.destination.display());
})?;

The embedding model, 30 MB across three files from Hugging Face, is fetched the same way the first time Model2Vec::potion_base_8m or Model2Vec::from_config runs, and has no notice form observed domain.rs:34-72.

Both models are separate works with their own licences. The parsing model is CC BY-NC-SA 4.0, which does not permit commercial use; the notice carries that licence and its URL observed nlp/udpipe.rs:18-108. The embedding model is MIT per its model card assumed grounds for decision 2, which the documentation states and the code does not carry observed embed/model2vec.rs:40-113.

When the first run fails

ConditionErrorKind
No network, unreachable host, refused connectionError::Io, ErrorKind::NotConnected, naming the URLio
Connect or transfer timeoutError::Io, ErrorKind::TimedOutio
TLS certificate rejectedError::Io, with a sentence saying why installing a CA does not helpio
Non-2xx statusError::Ioio
Response over 64 MiBError::InputTooLarge, what = udpipe_download or embedding_downloadinput_too_large
Model directory cannot be created or writtenError::Io, naming the operation and the pathio
Bytes arrived and failed the digest twice, or verified and did not loadError::ModelInvalidmodel_invalid

The rule behind the table: model_invalid is about bytes that arrived observed nlp/udpipe.rs:469-489 (RFC-0015). Behind a proxy that re-signs TLS, matra cannot be made to trust the proxy; the way through is to fetch the pinned file by hand and place it in the model directory, which is exactly as trustworthy because the digest decides.

Loading a model of your own

Udpipe::from_path and Model2Vec::from_dir load caller-supplied files and never touch the network or the pinned digest observed nlp/udpipe.rs:122-138 embed/model2vec.rs:143-174.

Reference-level explanation

Registries and attribution

crates.ioPyPI
Name and versionmatra 0.2.1 (Cargo.toml)matra 0.2.1 (pyproject.toml)
Authormox labs <yza.v@moxlabs.org>mox labs, yza.v@moxlabs.org
LicenceMITMIT

The same organization is the copyright holder in LICENSE, the entity author in CITATION.cff, and the author in .claude-plugin/plugin.json, because registry metadata is immutable per version and attribution that disagrees across files cannot be corrected in place (RFC-0013). The crate excludes blueprints/, site/ and the tests that read site/, and keeps skills/matra/, which the binary embeds observed Cargo.toml:15-37.

The wheel matrix

build-wheels builds four wheels: Linux x86_64 on ubuntu-latest and Linux aarch64 on ubuntu-24.04-arm, both inside ghcr.io/pyo3/maturin pinned by index digest; macOS arm64 natively and macOS x86_64 cross-compiled, both on macos-14 observed release.yml:311-351. pyo3 is built with abi3-py312 observed Cargo.toml:53-57. The workflow fails a release if a wheel is not tagged cp312-abi3 or a Linux wheel is not manylinux2014, and installs each native wheel on CPython 3.13 with --only-binary :all: observed release.yml:402-441. CI asserts the abi3 tag on every push observed ci.yml:359-387.

RUSTUP_TOOLCHAIN=stable in the container run is load-bearing: it keeps rustup from re-syncing the channel inside the image, a rename across the overlay boundary that fails with os error 18 observed release.yml:360-384 (RFC-0014).

Provisioning

The two adapters implement one discipline, each in its own file, as RFC-0015 decided: a shared module would add a third file to the wiring to save a few dozen lines.

UDPipe (nlp/udpipe.rs)Model2Vec (embed/model2vec.rs)
Pinone file: filename, size, SHA-256, URL, licence, licence URLthree files: one SHA-256 over all three in order, three URLs at a fixed Hugging Face commit
Caps64 MiB per response; 300 s end to end; 30 s to connectthe same
Clientureq with https_only (agent)the same
Orderfetch into memory, verify, write through a temporary and one rename, load the verified bytes (provision)fetch all three into memory, verify the set, write as one transaction, load the verified bytes (provision)
Retryone more fetch on a digest mismatch; a transport failure is not retried (fetch_verified)the same
A file already there that is not the pinreplaced only when verified bytes arrive; never deletedthe directory is refused and nothing is written or removed
Leftover temporariesreclaimed when older than 600 s, twice the fetch budget (reclaim)the same rule
Notice_with_notice forms on Udpipe and Enginenone

The asymmetry on a file already present is deliberate. The UDPipe filename names one release, so a file under it that is not that release is matra's own stale cache. The three Model2Vec filenames belong to the artifact format, so a directory holding them may be a caller's own model, and the provisioner refuses rather than overwrite it.

The digest check and the load use the same bytes, so there is no window between verifying and loading in which a file could be swapped observed nlp/udpipe.rs:665-694. Every filesystem failure names the operation and the path observed nlp/udpipe.rs:544-554. Transport failures are classified by transport_failure, and a rejected certificate gets the explanation in download_message observed nlp/udpipe.rs:469-489 nlp/udpipe.rs:491-515. The classification for every binding is stated in spec/tests/corpus/items.json observed items.json:64-81.

On wasm32 the download half of the embedding adapter is not compiled: every fetch item is behind cfg(not(target_arch = "wasm32")), and ureq is declared under that target predicate observed Cargo.toml:76-84.

Releasing

release.yml is the one release path, dispatched by hand from main with a version observed release.yml:1-66; it verifies, creates an annotated tag, builds the crate, the four wheels and the sdist, attests them, publishes, and smoke-tests what the registries serve. What a caller can rely on:

  • A person approved each upload. publish-crates runs in the crates-io environment and publish-pypi in pypi observed release.yml:522-575 release.yml:577-628; each of the two environments waits for a reviewer before it publishes assumed. The reviewer setting itself lives in the repository settings, not the file; the workflow header documents it as a prerequisite observed release.yml:1-66. Assumed configured, not verifiable from the tree.
  • No registry token is stored. Both uploads use Trusted Publishing through OIDC observed release.yml:522-575 release.yml:577-628.
  • Provenance is verifiable. actions/attest-build-provenance attests the crate, the wheels and the sdist before publishing; the crate job checks the bytes it uploads equal the bytes attested observed release.yml:475-520 release.yml:522-575. Verify with gh attestation verify matra-X.Y.Z.crate --repo mox-labs/matra. PyPI uploads carry PEP 740 attestations observed release.yml:577-628.
  • Actions are pinned by commit SHA in the release workflow, which, like CI, CodeQL and Scorecard, defaults to permissions: read-all and grants more per job observed release.yml:1-66. CI runs cargo-deny over the dependency tree and cargo-semver-checks over the public API on every push (ci.yml). Does not hold at the pinned commit: the cargo-semver-checks job runs on pull requests only, and a push to main skips it observed ci.yml:287-316. The sentence before it is left as written for the owner to rule on.

No longer in force

  • SLSA Build Level 3 through slsa-github-generator. RFC-0005 item 7. Releases attest at SLSA Build Level 2 with actions/attest-build-provenance, because the generator must be referenced by tag and the organization's policy requires SHA pins (attest).
  • Signed tags. RFC-0005 item 8. Release tags are annotated and created through the API, which cannot carry a maintainer's signature; the workflow asserts annotation and reports whether the tag is signed observed release.yml:257-277.
  • Tag-triggered publishing from publish.yml and publish-pypi.yml. RFC-0005 and RFC-0014 name both. They were merged into release.yml, dispatched from main because the crates-io environment's branch policy rejected a tag ref (header).
  • Rust 1.85 as the from-source floor. RFC-0014 states it. The floor is 1.88, checked by the msrv job observed Cargo.toml:1-14 ci.yml:70-100.
  • "No network" for the embedding model. RFC-0010 decision 6 as first written, and EP-0009's "the caller supplies model files". Amended by RFC-0011: a pinned download is allowed, and Model2Vec::potion_base_8m provisions.
  • The UDPipe fetch through udpipe_rs::download_model_from_url. Replaced by matra's own fetch, which is what made the timeouts, the size cap and the classification possible (RFC-0015).
  • book/book.toml as a place attribution lives. RFC-0013 lists it; the mdBook site it configured has been replaced, and the file does not exist.

Drawbacks

  • The stable ABI is a ceiling. Any pyo3 feature outside it is unavailable, and leaving it would multiply the wheel matrix by the CPython versions (RFC-0014).
  • Free-threaded CPython falls to the sdist. A free-threaded interpreter accepts no abi3 tag, and pyo3's free-threaded stable ABI begins at 3.15 assumed (RFC-0014; not re-verified against the current pyo3).
  • Nothing watches the maturin image digest. Dependabot cannot see a digest written inline in a run: step, so bumping it is a person's job on the release checklist observed release.yml:311-351.
  • A proxy that re-signs TLS blocks the download. matra verifies against root certificates compiled into it and never reads the system trust store observed nlp/udpipe.rs:491-515; the documented way through is placing the file by hand.
  • The embedding model's first run is silent, and the code carries neither its size in a notice nor its licence observed domain.rs:34-72 embed/model2vec.rs:40-113.
  • The parsing model's licence is non-commercial. matra is MIT; its default parsing model is not, and a commercial user must read and decide.

Rationale and alternatives

  • Document the old wheel matrix honestly instead of fixing it: rejected in RFC-0014; it truthfully documents a bad first install.
  • One wheel per CPython version: twelve jobs growing with each CPython release, and an interpreter released after a publish still falls to the sdist. Rejected in RFC-0014.
  • cibuildwheel: a build orchestrator with QEMU for arm64, for a matrix four explicit jobs cover. Rejected in RFC-0014.
  • RUSTUP_PERMIT_COPY_RENAME=1: works, but rustup documents it as unstable and removable, and it lets the calendar choose the compiler. Rejected in RFC-0014.
  • Keep the upstream UDPipe fetch and patch around it: cannot add a timeout or a size cap to a fetch matra does not perform. Rejected in RFC-0015.
  • A new Error variant for transport failures: grows the kind vocabulary with every place I/O happens, for a distinction io::ErrorKind already carries. Rejected in RFC-0015.
  • An escape hatch to the system trust store: widens what can authorize a model download, when hand placement costs one curl and is exactly as trustworthy. Rejected in RFC-0015 pending a threat model.
  • Attribution to an individual, or to both an individual and the organization: contradicts the repository and homepage, or reintroduces the disagreement in a form that looks intentional. Rejected in RFC-0013.

Prior art

  • ruff and uv ship abi3 wheels built with maturin and pin a single build CPython because of it (RFC-0014's release-validation survey).
  • Trusted Publishing on crates.io and PyPI, and GitHub artifact attestations, are the registry and platform mechanisms used here.
  • RFC-0005, RFC-0013, RFC-0014 and RFC-0015 hold the full history, including the clean-room measurements.

Unresolved questions

For the owner to settle in this proposal's review. Each is a decision of its own.

Prebuilt command-line binaries. RFC-0005 deferred binary releases "if matra ever ships a matra Rust CLI binary". It now does, behind the cli feature observed Cargo.toml:47-50 grounds for decision 1; a Rust user gets it with cargo install, and a Python user through the wheel's launcher, but no release publishes a standalone binary.

Decision · open · reversible

1. Does a release publish a standalone command-line binary?

A Not yet; the two routes stay recommended

cargo install matra --features cli and the wheel's launcher remain the ways to get the command line. The trigger is recorded as fired, and a standalone binary as not yet wanted.

B Yes, from release.yml

Each release attaches a prebuilt binary per platform, built and attested beside the wheels.

Claude recommends A, Not yet; the two routes stay. inferred, a judgment

Each new artifact joins the build, the attestation and the smoke test of a release path that cannot be undone, and nothing at the pinned commit shows a caller who can run neither cargo install nor the wheel's launcher.

The strongest case against it

The trigger RFC-0005 wrote has fired. Building from source needs a C++ compiler, the failure the wheel matrix was rebuilt to avoid, so a user with no Python cannot run the command line without one.

The owner's decision: open. Answer with accept, accept with a reservation, object or redirect, in a comment on this block or on the pull request; Claude then records your ruling here, as a named step in a pull request. A comment is never read as a ruling. Silence is not assent.

The embedding model's licence and notice. The parsing model's licence is pinned beside its URL and travels in the notice observed nlp/udpipe.rs:18-108 grounds for decision 2; the embedding model's is stated only in the documentation, and its provisioning has no notice form observed embed/model2vec.rs:40-113 domain.rs:34-72 grounds for decision 2.

Decision · open · costly to reverse

2. Does the embedding pin carry its licence and a notice, as the parsing pin does?

A Yes, as the parsing pin does recommended

The licence and its URL sit beside the three pinned URLs, and the provisioning Model2Vec constructors gain a notice form that reports the size, the destination and the licence before a fetch.

B No; the documentation is enough

The licence stays in the documentation, and the first run stays silent.

Claude recommends A, Yes, as the parsing pin does. inferred, a judgment

The parsing pin keeps its licence beside its URL because a new model means checking both, a reason that does not depend on which licence it is. A first run of 30 MB with nothing on screen is the state the notice was built to end for the parsing model.

The strongest case against it

The embedding model's licence places no restriction a caller has to decide on, unlike the parsing model's, and a notice form adds constructors to the public surface of an adapter a caller can replace with their own.

The owner's decision: open. Answer with accept, accept with a reservation, object or redirect, in a comment on this block or on the pull request; Claude then records your ruling here, as a named step in a pull request. A comment is never read as a ruling. Silence is not assent.

What the owner should confirm or strike, collected from the claims above that stand on no grounds yet:

3 claims stand on no grounds yet. Confirm or strike each with a comment on it.

  1. The embedding model is MIT per its model card where: The first run bears on decision 2
  2. each of the two environments waits for a reviewer before it publishes where: Releasing bears on no decision
  3. pyo3's free-threaded stable ABI begins at 3.15 where: Drawbacks bears on no decision

Future possibilities

  • A Windows wheel, once the UDPipe C++ build under MSVC is verified.
  • A free-threaded wheel when pyo3's free-threaded stable ABI covers a CPython matra supports.
  • Signed release tags, if the release is ever tagged where a maintainer's key is available.