spl:pin

Record which SPL model the active product derives from, by DOI, in its own pyproject.toml.

Usage

splent spl:pin [<spl_name>] [--doi DOI] [--concept-doi DOI] [--version LABEL] [--mirror NAME]

Requires an active product. The block is written into that product.

Options

Option	Description
`--doi`	Version DOI of the model to pin. This is what gets downloaded.
`--concept-doi`	DOI of the line, stable across versions. Used to report drift.
`--version`	Version label, for humans reading the file.
`--mirror`	Defaults to `uvlhub.io`.

With no options it adopts whatever the workspace already knows about the model, which after spl:publish is the DOI that was just minted. With --doi it pins exactly what you say, which is what a deployment reproducing an older build needs.

The name is optional when the product already declares one under [tool.splent].spl.

Why a product records a DOI

A product declares only the name of its SPL, and a name cannot be turned into a download. Something has to map names to DOIs, and that something used to be splent_catalog, a fourth git repository every workspace and every deployment had to clone.

So the product records the DOI itself, next to the name.

[tool.splent]
spl = "cms_spl"

[tool.splent.spl_model]
mirror = "uvlhub.io"
doi = "10.5281/zenodo.21610307"
concept_doi = "10.5281/zenodo.21610306"
version = "v3"

doi pins the exact bytes, the way org/repo@version pins a feature. concept_doi identifies the line rather than one version of it, which is what lets spl:outdated say “you pin v2, the line is on v5” with no directory service in the way.

With that, deriving a product needs the product’s own repository and UVLHub. It never needs the marketplace and never needs the workspace to hold any particular other repository.

How it writes

The block is machine managed. It is replaced wholesale when it is already there, appended at the end of the file when it is not, and never inserted into the middle of [tool.splent], because opening a sub-table there would silently reparent every key that follows it. The file is written atomically and re-parsed to confirm the DOI landed.

Example

splent spl:pin cms_spl

  innosoft_app now pins cms_spl
    doi          10.5281/zenodo.21610307
    concept doi  10.5281/zenodo.21610306
    version      v3
    recorded in  /workspace/innosoft_app/pyproject.toml

When nothing records a DOI yet, the pin is still written and the command warns. That is fine while you are authoring the model locally, but a clone of the product will not be able to resolve it.