SZL Holdings · Doctrine v11 · Λ = Conjecture 1 (advisory, never "green"/theorem) · canonical a-11-oy.com
yarqa
Control before action. Evidence after.
Product · Proof · GitHub organization
Plug-flow compartmentalization for compartmental models.
yarqa (Quechua: an Andean irrigation canal that divides and routes flowing
water) reduces a resolved CFD velocity field into a small network of plug-flow
compartments — maximal connected regions of velocity-aligned cells spanning a
coherent flow front. It's the classic reactor-engineering reduction of a 3-D
field to a series/network of ideal compartments.
Pure-Python + NumPy. No OpenFOAM dependency required (bring your own mesh as centers + velocities + neighbor lists). Apache-2.0.
Install
yarqa is not on PyPI yet (no release has been published), so install it
from source. NumPy is the only runtime dependency; Python 3.10 or newer.
git clone https://github.com/szl-holdings/yarqa.git
cd yarqa
python -m pip install -e . # library + CLI
python -m pip install -e '.[test]' # adds the test tooling
Without a checkout: python -m pip install "git+https://github.com/szl-holdings/yarqa.git".
Test
python -m pytest tests/ -q
tests/test_space_frontend.py and tests/test_receipt_ledger.py drive Node.js
fixtures, so node must be on PATH. tests/test_attestation.py and
tests/test_prediction_receipt.py skip (never fake) unless the optional
szl_receipt library is installed; see
Surrogate and optional attestation.
The Space endpoint tests need the Space requirements:
python -m pip install -r space/requirements.txt
python -m pytest space/tests/test_space_endpoints.py -q
CI (.github/workflows/space-ci.yml) runs both suites on Python 3.11 from the
hash-locked .github/requirements/space-ci.lock.
Operational runtime
Two public runtimes serve this code:
- Standalone Space
SZLHOLDINGS/yarqa. Its only writer is.github/workflows/hf-space.yml, which calls the org's reusable Dockerfile-derived deployer on each push to protectedmain. The deployer publishes thespace/DockerfileCOPY set, binds the exact source SHA (SZL_GIT_SHA), restarts the Space, and attests the running Hub commit, every published file by sha256, and/,/healthzand/api/build-info. The Space card (the HubREADME.md) is not published from this repository. - Command Lab route
https://szlholdings-szl-command-lab.hf.space/api/yarqa. Command Lab pins an
exact commit from this repository, executes a bounded synthetic
compartmentalization, emits a replayable receipt, and verifies that receipt
before returning
READY.
The standalone publisher was retired on 2026-09-08 (#63), but the Space stayed public and running with no writer, so this repository is again its single source. Both runtimes demonstrate integrity and reproducibility for their disclosed synthetic input; they are not CFD correctness, validation for a customer mesh, or authorization for an external action.
Use
import numpy as np
from yarqa import Mesh, compartmentalize
from yarqa.core import compartment_summary
mesh = Mesh(
centers=cell_centers, # (N, D)
velocities=cell_velocities, # (N, D)
neighbors=face_neighbors, # list of int arrays, length N
corners=cell_corners, # optional list of (K_i, D); falls back to centers
)
labels = compartmentalize(mesh, align_threshold=0.0) # (N,) compartment id per cell
report = compartment_summary(mesh, labels) # counts, mean velocity, centroids
Algorithm (summary)
- Build a symmetric face-adjacency connection map.
- Pick the fastest unassigned cell as a seed; grow a compartment outward through
neighbors that are velocity-aligned with the seed (
dot(û_seed, û_k) ≥ threshold) and straddle the seed's flow front (representative points on both sides of the plane normal to the seed velocity). - Repeat until every cell is assigned. Result: sequential plug-flow slices.
Verifiable provenance receipts (the SZL innovation)
yarqa is, to our knowledge, the first plug-flow compartmentalizer that emits a
signed-ready, replayable provenance receipt for every run — applying SZL's
receipt discipline to CFD:
from yarqa import compartmentalize_with_receipt, verify
labels, receipt = compartmentalize_with_receipt(mesh, align_threshold=0.2)
receipt.receipt_digest() # 64-char SHA-256 — the bytes a signer/cosign would sign
verify(mesh, receipt)["ok"] # True — anyone with the mesh can reproduce + confirm
The receipt records input content-hashes, params, code version, and the result
hash. A third party holding only the mesh + receipt can deterministically
replay the run and confirm the published compartments are exactly what this
code produces — tamper-evident on inputs, params, or results. yarqa.provenance
itself stays dependency-free (NumPy only); keyless signing lives in
yarqa.signing and needs the optional sigstore package (see
Signed provenance receipts).
This is an integrity / reproducibility guarantee, NOT a formal proof of
correctness.
Agentic routing, receipt chains & CLI (v0.4.0, additive)
Everything below is additive — the v0.3.0 API and all prior tests are unchanged.
Sparse top-k routing. Alongside the original argmax route(), route_topk()
routes an observation to its k best-aligned compartments with normalized
softmax gating weights over their cosine scores (k=1 reproduces argmax):
from yarqa import build_experts, route_topk
experts = build_experts(mesh, labels) # one expert per compartment
rk = route_topk(observation_velocity, experts, k=2, temperature=1.0)
rk.compartment_ids, rk.weights # best-first ids; softmax weights summing to 1.0
Concept inspiration only: the sparsely-gated mixture-of-experts idea (Shazeer et al., 2017). All code is original SZL work; the "experts" are physical flow compartments, not learned networks.
Append-only receipt chain. ReceiptChain hash-links AgentStep receipts
(prev_digest -> digest) into a tamper-evident log: editing, reordering,
inserting, or deleting any past step breaks verify(). This is an
integrity / ordering mechanism, not a proof of correctness and not a locked
theorem.
from yarqa import ReceiptChain
chain = ReceiptChain()
for step in agent_steps:
chain.append(step)
chain.verify()["ok"] # True only if the whole chain is intact
CLI. Real entry points over the simple .npz mesh format (numpy-only; no
OpenFOAM dependency). A try_load_openfoam() hook is a guarded, honest stub.
python -m yarqa.cli sample mesh.npz # SAMPLE synthetic mesh
python -m yarqa.cli compartmentalize mesh.npz --receipt r.json
python -m yarqa.cli verify mesh.npz r.json # reproduce + confirm
Surrogate and optional attestation
fit_plugflow_surrogate() runs the real compartmentalize() at a few anchor
thresholds (seven, evenly spaced over 0–0.98, by default) and interpolates the
compartment count between them. Outside the measured anchor range it returns
UNAVAILABLE with value=None instead of extrapolating; inside it reports the
two bracketing measured counts as an indicative interval, not a guarantee.
from yarqa import fit_plugflow_surrogate
from yarqa.meshio import sample_channel_mesh
surrogate = fit_plugflow_surrogate(sample_channel_mesh(12, 8, seed=0))
p = surrogate.predict(0.9)
p.status, p.lower_bound, p.upper_bound # ('PREDICTED', 29, 30); p.value ≈ 29.51
surrogate.predict(0.995).status # 'UNAVAILABLE' (above the 0.98 anchor)
yarqa.attestation (attest_prediction, emit_prediction_receipt, …) wraps a
prediction in the shared SZL receipt shapes by delegating to the szl_receipt
library, which is not on PyPI. Without it those functions raise
AttestationUnavailable rather than build a receipt themselves. To enable them:
python -m pip install "szl_receipt @ git+https://github.com/szl-holdings/szl-receipt.git@v0.2.0"
The adapter's tests also pass against szl-receipt v0.3.4, whose distribution is
named szl-receipt-dsse. emit_prediction_receipt() without a private key
returns an honestly unsigned envelope.
Provenance & honesty
Clean-room implementation from a published algorithm description — no third-party
(incl. AGPL) source copied. See PROVENANCE.md. yarqa is an
engineering/CFD method, not a lutar-lean locked-proven theorem — never surface it
with a "proven" badge or fold it into the locked formula count.
SZL Holdings · Apache-2.0 · Doctrine v11.
Signed provenance receipts (Sigstore keyless)
Every compartmentalize_with_receipt(...) run yields a canonical, reproducible
Receipt. In CI, that receipt is signed as a genuine Sigstore keyless DSSE
attestation — a GitHub Actions OIDC token is exchanged at Fulcio for a
short-lived ECDSA-P256 certificate, the receipt is wrapped as an in-toto v1
Statement and DSSE-signed, and the signature is recorded in the public Rekor
transparency log. No founder key, no stored secret.
# sign (requires a CI context with id-token: write; off-CI use --allow-placeholder)
python scripts/sign_receipt.py --nx 12 --ny 8 --seed 0
# independently verify the signature AND reproduce the run
python scripts/verify_receipt.py attestations/yarqa/<digest>.dsse.json \
--identity "https://github.com/szl-holdings/yarqa/.github/workflows/receipt-sign.yml@refs/heads/main" \
--issuer "https://token.actions.githubusercontent.com" \
--replay
The signed statement embeds a deterministic replay recipe (generator, nx, ny, seed, align_threshold), so any third party can regenerate the mesh,
reconstruct the receipt, and confirm via yarqa.verify() that the result
reproduces — independent of any data we host.
The receipt-sign workflow runs this on pull requests and pushes to main
that change the package, the signing scripts, their lock
(requirements/ci/receipt-sign.txt) or the workflow. On those pushes a
separate publish-ledger job, the only one holding a write token, appends each
verified receipt to the append-only governance-receipts branch
(receipts/<sha256>.dsse.json) and fails the run if it cannot.
Honesty: this signs the receipt, nothing more. yarqa is an
engineering-method / CFD tool — receipts attest integrity + reproducibility,
never correctness, and carry no locked-theorem or "proven" claim. SLSA level is
unchanged (L1). Outside CI there is no ambient identity, so yarqa declines
to sign rather than fabricate a signature (an honest placeholder is emitted only
with --allow-placeholder).
Explore the SZL estate: a11oy console · LLM Router · Receipt format spec · Lean proofs · Docs · 🤗 SZLHOLDINGS
License
Apache-2.0 — see LICENSE. Explore the SZL estate: a11oy console · LLM Router · Receipt format spec · Lean proofs · Docs (archived) · 🤗 SZLHOLDINGS
Metadata
Release files for yarqa 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yarqa-0.5.0.tar.gz | 74.7 kB | With provenance | Details for yarqa-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| yarqa-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for yarqa-0.5.0-py3-none-any.whl |
Total release size: 122.2 kB
Release files / yarqa-0.5.0.tar.gz
| Download URL | yarqa-0.5.0.tar.gz |
|---|---|
| Size | 74.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b79b1033c995f199c80e2ad03f516eeb5bb6adee4a1f233cc112154579dc575e
|
|
BLAKE2b-256 checksum How to use checksums |
1b009f0450d3518138e7ee2dac624b7c01738bc6b7b9c4f57c7231ea28dfacb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / yarqa-0.5.0-py3-none-any.whl
| Download URL | yarqa-0.5.0-py3-none-any.whl |
|---|---|
| Size | 47.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
04fe6ea87ac4aa5c9e7f6337291bde12a406feea37d11d4afa25c23f017e89b1
|
|
BLAKE2b-256 checksum How to use checksums |
bc48232942a5502f078b07387ca27b45069da43ac260840e172ea6aa90933b06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for yarqa 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for yarqa-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.