splent-feature-spl-registry 0.1.2__tar.gz

splent_feature_spl_registry-0.1.2/MANIFEST.in

@@ -0,0 +1,24 @@
+# Frontend assets: the whole tree, not only the compiled bundles.
+#
+# A feature that registers a plain stylesheet with register_asset("css", …)
+# serves it straight from assets/css, and a vendored library lives under
+# assets/vendor. Shipping assets/dist alone put no stylesheet at all in the
+# built package, so every production image came up without its theme, its
+# skin and its editor, while development looked fine because that path
+# installs the checkout in place and reads the files off disk.
+recursive-include src/splent_io/splent_feature_spl_registry/assets *.css *.js *.map *.json
+recursive-include src/splent_io/splent_feature_spl_registry/assets *.svg *.png *.jpg *.jpeg *.gif *.webp *.ico
+recursive-include src/splent_io/splent_feature_spl_registry/assets *.woff *.woff2 *.ttf *.eot
+
+# Build inputs, never shipped.
+prune src/splent_io/splent_feature_spl_registry/assets/node_modules
+
+# Jinja templates (feature views + hook fragments)
+recursive-include src/splent_io/splent_feature_spl_registry/templates *.html
+
+# Alembic migration config and scripts
+recursive-include src/splent_io/splent_feature_spl_registry/migrations *.py *.ini *.mako
+
+# Translations. The .mo is what gettext reads at runtime; the .po
+# travels with it so the next translator has something to edit.
+recursive-include src/splent_io/splent_feature_spl_registry/translations *.mo *.po *.pot

splent_feature_spl_registry-0.1.2/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: splent_feature_spl_registry
+Version: 0.1.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# splent_feature_spl_registry
+
+The marketplace's registry of software product lines. It owns which SPLs exist,
+who owns each one, the DOI pointer to the published UVL model, and the relay
+that publishes a model to UVLHub.
+
+It subsumes `splent_catalog`, the git repository that used to hold a
+`metadata.toml` per product line. Everything those files carried (name,
+description and the `{mirror, doi, file}` pointer) now lives in the `spl`
+table, and `GET /api/v1/spls` serves it to the splent CLI and the index
+builder.
+
+## The model
+
+```
+developer --(splent CLI with a splent token)--> MARKETPLACE --(one server-side key)--> UVLHub
+```
+
+A developer authenticates to the marketplace with a token from
+`splent_feature_apikeys` and sends a `.uvl` file. They never hold UVLHub
+credentials, never name a UVLHub dataset and never learn UVLHub is involved.
+The marketplace validates the model, relays it with its single key, and stores
+the DOI pointer. The UVL content itself is never stored here.
+
+Publishing a FEATURE is unchanged: `splent feature:release`, no account, no
+token, the git tag is the publication. This feature is only about product
+lines.
+
+## Ordering
+
+A release row is written **before** the irreversible call to UVLHub, then
+updated with the outcome. This is the point of the design. If the publish call
+times out and nothing was written down first, the marketplace cannot tell
+whether a DOI was minted, and the honest answer ("I do not know") gets replaced
+by the tempting one ("try again"), which mints a second permanent DOI for the
+same model.
+
+A release therefore settles into one of three states, and only one of them is
+safe to retry:
+
+| state       | meaning                                    | retry |
+|-------------|--------------------------------------------|-------|
+| `published` | UVLHub minted a DOI, recorded here         | not needed, republishing the same bytes is idempotent |
+| `failed`    | UVLHub refused. Nothing was minted         | yes   |
+| `unknown`   | No answer after the irreversible call      | **no**, an administrator settles it first |
+
+`splent feature:spl_registry stuck` lists the undetermined ones and
+`... settle <spl> <version> [--doi ...]` records what was found.
+
+## Endpoints
+
+| method | path                            | auth               |
+|--------|---------------------------------|--------------------|
+| GET    | `/api/v1/spls`                  | public             |
+| GET    | `/api/v1/spls/<name>`           | public             |
+| POST   | `/api/v1/spls/<name>/releases`  | Bearer, `write_spl` |
+| GET    | `/marketplace/spls/<name>`      | public page        |
+
+```bash
+curl -X POST https://<marketplace>/api/v1/spls/my_line/releases \
+     -H "Authorization: Bearer splent_..." \
+     -F "file=@my_line.uvl"
+```
+
+## Configuration
+
+Every variable has a working default; the feature runs with no `.env` entry.
+
+| variable                             | default                  | what it does |
+|--------------------------------------|--------------------------|--------------|
+| `UVLHUB_API_KEY`                     | (none)                   | the single server-side key. Without it the write path answers 503 |
+| `UVLHUB_URL`                         | `https://www.uvlhub.io`  | which instance to relay to |
+| `SPL_REGISTRY_PUBLISHING_ENABLED`    | `true`                   | kill switch. `false` closes publishing and leaves every read path up |
+| `SPL_REGISTRY_VERIFY_PUBLISHED`      | `true`                   | download the published file and compare it byte for byte |
+| `SPL_REGISTRY_UVLHUB_TIMEOUT`        | `60`                     | seconds per UVLHub call |
+| `SPL_REGISTRY_QUOTA_WINDOW_HOURS`    | `24`                     | the rolling window every quota is counted over |
+| `SPL_REGISTRY_MAX_RELEASES_PER_USER` | `10`                     | per developer, per window |
+| `SPL_REGISTRY_MAX_RELEASES_PER_SPL`  | `5`                      | per product line, per window |
+| `SPL_REGISTRY_MAX_RELEASES_TOTAL`    | `100`                    | the ceiling that bounds the single key |
+| `SPL_REGISTRY_MAX_SPLS_PER_USER`     | `5`                      | product lines one developer may own |
+
+`UVLHUB_API_KEY` is deliberately never copied into `app.config`: that mapping
+is dumped by `splent product:config`, by the settings screens and by Flask's
+debug pages. It is read from the environment at call time in exactly one place,
+`uvlhub.api_key()`, which is the only place in the whole workspace that reads
+it server side.
+
+Quotas are counted with SQL `COUNT`s, never in-process counters, because
+several workers run in parallel and a per-process counter would multiply every
+allowance by the number of them.
+
+## 403 or 404
+
+Every product line is in the public index unless an administrator withdraws it
+with `visibility <spl> withdrawn`. That one flag decides what the publishing
+endpoint says about a line that is not yours:
+
+| the line is  | answer | why |
+|--------------|--------|-----|
+| listed       | `403`  | admitting the name is taken tells the caller nothing they cannot read in `GET /api/v1/spls` |
+| withdrawn    | `404`  | the same answer, code and wording as a name nobody registered, so the write path cannot be walked to find what the read path hides |
+
+Withdrawing hides a line. It deletes nothing: every release and every DOI stays
+exactly where it is, and the owner can still publish to it.
+
+## Authorship
+
+A publication is credited to the publishing developer's profile, read server
+side and never from a request field, because an author line a stranger can
+choose is an impersonation vector on a permanent record.
+
+The profile feature is **not** required. When the product installs it, the
+credit is the `name` and `surname` on the developer's `UserProfile`, read
+through `UserProfileService.get_by_user_id`. When it does not, or when the
+developer never filled the form in, the credit is `SPLENT MARKETPLACE`. It is
+never the email address, which would put a personal address on a permanent
+public record.
+
+A SPLENT profile holds a name and a surname and nothing else, so that is all
+that is sent. There is no affiliation and no ORCID to send.
+
+## Commands
+
+```bash
+splent db:seed
+splent feature:spl_registry import-catalog [--path ...] [--owner email] [--dry-run]
+splent feature:spl_registry list
+splent feature:spl_registry stuck [--hours 1]
+splent feature:spl_registry settle <spl> <version> [--doi ...] [--note ...]
+splent feature:spl_registry set-owner <spl> <email>
+splent feature:spl_registry visibility <spl> public|withdrawn
+```
+
+`splent db:seed` runs `SplRegistrySeeder`, which **carries the three
+`splent_catalog` lines as data**: their name, description, mirror, DOI and file
+name are written out in `seeders.py`. That is the copy that survives the
+directory being deleted, and it is what rebuilds the registry on a fresh
+database. `import-catalog` does the same job by *reading* the directory, so use
+it for the one-off migration while `splent_catalog` is still on disk and the
+seeder from then on. Both are idempotent.
+
+Neither records a content digest for the lines it brings in. The digest is the
+idempotency key, and a release carrying one is the registry promising these
+exact bytes are what that DOI serves. Nothing has compared them, and one of the
+three does not even point at the file sitting next to it
+(`sample_splent_spl` serves `sample_splent_app.uvl`), so the digest is left
+empty and the local one is recorded as a note instead.
+
+Imported lines arrive with **no owner**, which is what stops any authenticated
+developer from publishing to them; `set-owner` hands one over.
+
+## Requires
+
+`auth` (the User an owner and a publisher point at) and `apikeys` (the
+`write_spl` Bearer token the publishing endpoint is guarded by).
+
+`profile` is **optional**. It improves the credit on a publication and the name
+shown on the public page, and the feature works without it.
+
+## Tests
+
+```bash
+splent feature:test splent_feature_spl_registry
+```
+
+Unit, integration and functional. The suite never reaches UVLHub: the conftest
+replaces the four relay calls **and** the HTTP client underneath them, and it
+does so through its own `MonkeyPatch` rather than the shared fixture. That last
+detail is not decoration. While the shared fixture was used, a single
+`monkeypatch.undo()` inside a test restored the real relay along with the real
+`UVLHUB_API_KEY`, and a test run minted a permanent DOI on production Zenodo.
+Publishing is irreversible, so the guard has to be one a test cannot lift.

splent_feature_spl_registry-0.1.2/README.md

@@ -0,0 +1,172 @@
+# splent_feature_spl_registry
+
+The marketplace's registry of software product lines. It owns which SPLs exist,
+who owns each one, the DOI pointer to the published UVL model, and the relay
+that publishes a model to UVLHub.
+
+It subsumes `splent_catalog`, the git repository that used to hold a
+`metadata.toml` per product line. Everything those files carried (name,
+description and the `{mirror, doi, file}` pointer) now lives in the `spl`
+table, and `GET /api/v1/spls` serves it to the splent CLI and the index
+builder.
+
+## The model
+
+```
+developer --(splent CLI with a splent token)--> MARKETPLACE --(one server-side key)--> UVLHub
+```
+
+A developer authenticates to the marketplace with a token from
+`splent_feature_apikeys` and sends a `.uvl` file. They never hold UVLHub
+credentials, never name a UVLHub dataset and never learn UVLHub is involved.
+The marketplace validates the model, relays it with its single key, and stores
+the DOI pointer. The UVL content itself is never stored here.
+
+Publishing a FEATURE is unchanged: `splent feature:release`, no account, no
+token, the git tag is the publication. This feature is only about product
+lines.
+
+## Ordering
+
+A release row is written **before** the irreversible call to UVLHub, then
+updated with the outcome. This is the point of the design. If the publish call
+times out and nothing was written down first, the marketplace cannot tell
+whether a DOI was minted, and the honest answer ("I do not know") gets replaced
+by the tempting one ("try again"), which mints a second permanent DOI for the
+same model.
+
+A release therefore settles into one of three states, and only one of them is
+safe to retry:
+
+| state       | meaning                                    | retry |
+|-------------|--------------------------------------------|-------|
+| `published` | UVLHub minted a DOI, recorded here         | not needed, republishing the same bytes is idempotent |
+| `failed`    | UVLHub refused. Nothing was minted         | yes   |
+| `unknown`   | No answer after the irreversible call      | **no**, an administrator settles it first |
+
+`splent feature:spl_registry stuck` lists the undetermined ones and
+`... settle <spl> <version> [--doi ...]` records what was found.
+
+## Endpoints
+
+| method | path                            | auth               |
+|--------|---------------------------------|--------------------|
+| GET    | `/api/v1/spls`                  | public             |
+| GET    | `/api/v1/spls/<name>`           | public             |
+| POST   | `/api/v1/spls/<name>/releases`  | Bearer, `write_spl` |
+| GET    | `/marketplace/spls/<name>`      | public page        |
+
+```bash
+curl -X POST https://<marketplace>/api/v1/spls/my_line/releases \
+     -H "Authorization: Bearer splent_..." \
+     -F "file=@my_line.uvl"
+```
+
+## Configuration
+
+Every variable has a working default; the feature runs with no `.env` entry.
+
+| variable                             | default                  | what it does |
+|--------------------------------------|--------------------------|--------------|
+| `UVLHUB_API_KEY`                     | (none)                   | the single server-side key. Without it the write path answers 503 |
+| `UVLHUB_URL`                         | `https://www.uvlhub.io`  | which instance to relay to |
+| `SPL_REGISTRY_PUBLISHING_ENABLED`    | `true`                   | kill switch. `false` closes publishing and leaves every read path up |
+| `SPL_REGISTRY_VERIFY_PUBLISHED`      | `true`                   | download the published file and compare it byte for byte |
+| `SPL_REGISTRY_UVLHUB_TIMEOUT`        | `60`                     | seconds per UVLHub call |
+| `SPL_REGISTRY_QUOTA_WINDOW_HOURS`    | `24`                     | the rolling window every quota is counted over |
+| `SPL_REGISTRY_MAX_RELEASES_PER_USER` | `10`                     | per developer, per window |
+| `SPL_REGISTRY_MAX_RELEASES_PER_SPL`  | `5`                      | per product line, per window |
+| `SPL_REGISTRY_MAX_RELEASES_TOTAL`    | `100`                    | the ceiling that bounds the single key |
+| `SPL_REGISTRY_MAX_SPLS_PER_USER`     | `5`                      | product lines one developer may own |
+
+`UVLHUB_API_KEY` is deliberately never copied into `app.config`: that mapping
+is dumped by `splent product:config`, by the settings screens and by Flask's
+debug pages. It is read from the environment at call time in exactly one place,
+`uvlhub.api_key()`, which is the only place in the whole workspace that reads
+it server side.
+
+Quotas are counted with SQL `COUNT`s, never in-process counters, because
+several workers run in parallel and a per-process counter would multiply every
+allowance by the number of them.
+
+## 403 or 404
+
+Every product line is in the public index unless an administrator withdraws it
+with `visibility <spl> withdrawn`. That one flag decides what the publishing
+endpoint says about a line that is not yours:
+
+| the line is  | answer | why |
+|--------------|--------|-----|
+| listed       | `403`  | admitting the name is taken tells the caller nothing they cannot read in `GET /api/v1/spls` |
+| withdrawn    | `404`  | the same answer, code and wording as a name nobody registered, so the write path cannot be walked to find what the read path hides |
+
+Withdrawing hides a line. It deletes nothing: every release and every DOI stays
+exactly where it is, and the owner can still publish to it.
+
+## Authorship
+
+A publication is credited to the publishing developer's profile, read server
+side and never from a request field, because an author line a stranger can
+choose is an impersonation vector on a permanent record.
+
+The profile feature is **not** required. When the product installs it, the
+credit is the `name` and `surname` on the developer's `UserProfile`, read
+through `UserProfileService.get_by_user_id`. When it does not, or when the
+developer never filled the form in, the credit is `SPLENT MARKETPLACE`. It is
+never the email address, which would put a personal address on a permanent
+public record.
+
+A SPLENT profile holds a name and a surname and nothing else, so that is all
+that is sent. There is no affiliation and no ORCID to send.
+
+## Commands
+
+```bash
+splent db:seed
+splent feature:spl_registry import-catalog [--path ...] [--owner email] [--dry-run]
+splent feature:spl_registry list
+splent feature:spl_registry stuck [--hours 1]
+splent feature:spl_registry settle <spl> <version> [--doi ...] [--note ...]
+splent feature:spl_registry set-owner <spl> <email>
+splent feature:spl_registry visibility <spl> public|withdrawn
+```
+
+`splent db:seed` runs `SplRegistrySeeder`, which **carries the three
+`splent_catalog` lines as data**: their name, description, mirror, DOI and file
+name are written out in `seeders.py`. That is the copy that survives the
+directory being deleted, and it is what rebuilds the registry on a fresh
+database. `import-catalog` does the same job by *reading* the directory, so use
+it for the one-off migration while `splent_catalog` is still on disk and the
+seeder from then on. Both are idempotent.
+
+Neither records a content digest for the lines it brings in. The digest is the
+idempotency key, and a release carrying one is the registry promising these
+exact bytes are what that DOI serves. Nothing has compared them, and one of the
+three does not even point at the file sitting next to it
+(`sample_splent_spl` serves `sample_splent_app.uvl`), so the digest is left
+empty and the local one is recorded as a note instead.
+
+Imported lines arrive with **no owner**, which is what stops any authenticated
+developer from publishing to them; `set-owner` hands one over.
+
+## Requires
+
+`auth` (the User an owner and a publisher point at) and `apikeys` (the
+`write_spl` Bearer token the publishing endpoint is guarded by).
+
+`profile` is **optional**. It improves the credit on a publication and the name
+shown on the public page, and the feature works without it.
+
+## Tests
+
+```bash
+splent feature:test splent_feature_spl_registry
+```
+
+Unit, integration and functional. The suite never reaches UVLHub: the conftest
+replaces the four relay calls **and** the HTTP client underneath them, and it
+does so through its own `MonkeyPatch` rather than the shared fixture. That last
+detail is not decoration. While the shared fixture was used, a single
+`monkeypatch.undo()` inside a test restored the real relay along with the real
+`UVLHUB_API_KEY`, and a test run minted a permanent DOI on production Zenodo.
+Publishing is irreversible, so the guard has to be one a test cannot lift.

splent_feature_spl_registry-0.1.2/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=80.3.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "splent_feature_spl_registry"
+version = "0.1.2"
+readme = "README.md"
+requires-python = ">=3.13"
+
+dependencies = [
+    # The relay to UVLHub. Declared even though the runtime image already
+    # carries it, because this feature does not work without it.
+    "requests>=2.31",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["*.tests", "*.tests.*"]
+
+[tool.splent]
+cli_version = "1.14.0"
+
+# ── Feature Contract (auto-generated) ────────────────────────────────────────
+# Do not edit manually — re-run `splent feature:contract --write` to refresh.
+# Preserved across refreshes: description, category, tags, env,
+# requires.features_manual (dependencies invisible to static analysis)
+# and provides.routes_manual (routes built from configuration at
+# registration time, which have no literal path to find in source).
+[tool.splent.contract]
+description = "Registry of software product lines, and the relay that publishes their UVL models to UVLHub"
+archetype = "full"
+
+[tool.splent.contract.provides]
+routes     = ["/api/v1/spls", "/api/v1/spls/<name>", "/api/v1/spls/<name>/releases", "/marketplace/spls/<name>"]
+blueprints = []
+models     = ["Spl", "SplKeyCall", "SplRelease"]
+commands   = ["import-catalog", "list", "set-owner", "settle", "stuck", "visibility"]
+hooks      = []
+services   = ["SplRegistryService"]
+signals    = []
+translations = ["es"]
+docker     = []
+
+[tool.splent.contract.requires]
+features = ["apikeys", "auth"]
+env_vars = ["SPLENT_CATALOG_PATH", "SPL_REGISTRY_GATE_TIMEOUT_SECONDS", "SPL_REGISTRY_MAX_RELEASES_PER_SPL", "SPL_REGISTRY_MAX_RELEASES_PER_USER", "SPL_REGISTRY_MAX_RELEASES_TOTAL", "SPL_REGISTRY_MAX_SPLS_PER_USER", "SPL_REGISTRY_PUBLISHING_ENABLED", "SPL_REGISTRY_QUOTA_WINDOW_HOURS", "SPL_REGISTRY_UVLHUB_TIMEOUT", "SPL_REGISTRY_VERIFY_PUBLISHED", "UVLHUB_API_KEY", "UVLHUB_URL"]
+signals  = []
+
+[tool.splent.contract.extensible]
+services  = ["SplRegistryService"]
+templates = ["spl_registry/detail.html", "spl_registry/not_found.html"]
+models    = ["Spl", "SplKeyCall", "SplRelease"]
+hooks     = []
+routes    = false
+
+# ── Configuration ─────────────────────────────────────────────────────────
+[tool.splent.config]
+UVLHUB_URL = "https://www.uvlhub.io"
+# The instance's publishing credential, so the default is empty. The real
+# value belongs in the deployment's .env, which is not committed. The code
+# reads it from the environment at call time and never copies it into
+# app.config, so config dumps and debug pages cannot leak it.
+UVLHUB_API_KEY = ""
+# Publishing is off until a deployment turns it on, so an instance brought
+# up to look around cannot push to a public registry by accident.
+SPL_REGISTRY_PUBLISHING_ENABLED = "false"
+# Whether a release is read back after publishing to confirm it landed.
+SPL_REGISTRY_VERIFY_PUBLISHED = "true"
+# Timeouts, in seconds: the gate check is meant to be quick, the upload is
+# not, because a model with its files takes a while.
+SPL_REGISTRY_GATE_TIMEOUT_SECONDS = 10
+SPL_REGISTRY_UVLHUB_TIMEOUT = 60
+# Quotas. The window they are counted over, then the ceilings: per user, per
+# SPL, and across the instance, so one account cannot spend a shared
+# registry's budget.
+SPL_REGISTRY_QUOTA_WINDOW_HOURS = 24
+SPL_REGISTRY_MAX_RELEASES_PER_USER = 10
+SPL_REGISTRY_MAX_RELEASES_PER_SPL = 5
+SPL_REGISTRY_MAX_RELEASES_TOTAL = 100
+SPL_REGISTRY_MAX_SPLS_PER_USER = 5
+# Where the catalog of SPL definitions is read from.
+SPLENT_CATALOG_PATH = "/workspace/splent_catalog"

splent_feature_spl_registry-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

splent_feature_spl_registry-0.1.2/src/splent_feature_spl_registry.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: splent_feature_spl_registry
+Version: 0.1.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# splent_feature_spl_registry
+
+The marketplace's registry of software product lines. It owns which SPLs exist,
+who owns each one, the DOI pointer to the published UVL model, and the relay
+that publishes a model to UVLHub.
+
+It subsumes `splent_catalog`, the git repository that used to hold a
+`metadata.toml` per product line. Everything those files carried (name,
+description and the `{mirror, doi, file}` pointer) now lives in the `spl`
+table, and `GET /api/v1/spls` serves it to the splent CLI and the index
+builder.
+
+## The model
+
+```
+developer --(splent CLI with a splent token)--> MARKETPLACE --(one server-side key)--> UVLHub
+```
+
+A developer authenticates to the marketplace with a token from
+`splent_feature_apikeys` and sends a `.uvl` file. They never hold UVLHub
+credentials, never name a UVLHub dataset and never learn UVLHub is involved.
+The marketplace validates the model, relays it with its single key, and stores
+the DOI pointer. The UVL content itself is never stored here.
+
+Publishing a FEATURE is unchanged: `splent feature:release`, no account, no
+token, the git tag is the publication. This feature is only about product
+lines.
+
+## Ordering
+
+A release row is written **before** the irreversible call to UVLHub, then
+updated with the outcome. This is the point of the design. If the publish call
+times out and nothing was written down first, the marketplace cannot tell
+whether a DOI was minted, and the honest answer ("I do not know") gets replaced
+by the tempting one ("try again"), which mints a second permanent DOI for the
+same model.
+
+A release therefore settles into one of three states, and only one of them is
+safe to retry:
+
+| state       | meaning                                    | retry |
+|-------------|--------------------------------------------|-------|
+| `published` | UVLHub minted a DOI, recorded here         | not needed, republishing the same bytes is idempotent |
+| `failed`    | UVLHub refused. Nothing was minted         | yes   |
+| `unknown`   | No answer after the irreversible call      | **no**, an administrator settles it first |
+
+`splent feature:spl_registry stuck` lists the undetermined ones and
+`... settle <spl> <version> [--doi ...]` records what was found.
+
+## Endpoints
+
+| method | path                            | auth               |
+|--------|---------------------------------|--------------------|
+| GET    | `/api/v1/spls`                  | public             |
+| GET    | `/api/v1/spls/<name>`           | public             |
+| POST   | `/api/v1/spls/<name>/releases`  | Bearer, `write_spl` |
+| GET    | `/marketplace/spls/<name>`      | public page        |
+
+```bash
+curl -X POST https://<marketplace>/api/v1/spls/my_line/releases \
+     -H "Authorization: Bearer splent_..." \
+     -F "file=@my_line.uvl"
+```
+
+## Configuration
+
+Every variable has a working default; the feature runs with no `.env` entry.
+
+| variable                             | default                  | what it does |
+|--------------------------------------|--------------------------|--------------|
+| `UVLHUB_API_KEY`                     | (none)                   | the single server-side key. Without it the write path answers 503 |
+| `UVLHUB_URL`                         | `https://www.uvlhub.io`  | which instance to relay to |
+| `SPL_REGISTRY_PUBLISHING_ENABLED`    | `true`                   | kill switch. `false` closes publishing and leaves every read path up |
+| `SPL_REGISTRY_VERIFY_PUBLISHED`      | `true`                   | download the published file and compare it byte for byte |
+| `SPL_REGISTRY_UVLHUB_TIMEOUT`        | `60`                     | seconds per UVLHub call |
+| `SPL_REGISTRY_QUOTA_WINDOW_HOURS`    | `24`                     | the rolling window every quota is counted over |
+| `SPL_REGISTRY_MAX_RELEASES_PER_USER` | `10`                     | per developer, per window |
+| `SPL_REGISTRY_MAX_RELEASES_PER_SPL`  | `5`                      | per product line, per window |
+| `SPL_REGISTRY_MAX_RELEASES_TOTAL`    | `100`                    | the ceiling that bounds the single key |
+| `SPL_REGISTRY_MAX_SPLS_PER_USER`     | `5`                      | product lines one developer may own |
+
+`UVLHUB_API_KEY` is deliberately never copied into `app.config`: that mapping
+is dumped by `splent product:config`, by the settings screens and by Flask's
+debug pages. It is read from the environment at call time in exactly one place,
+`uvlhub.api_key()`, which is the only place in the whole workspace that reads
+it server side.
+
+Quotas are counted with SQL `COUNT`s, never in-process counters, because
+several workers run in parallel and a per-process counter would multiply every
+allowance by the number of them.
+
+## 403 or 404
+
+Every product line is in the public index unless an administrator withdraws it
+with `visibility <spl> withdrawn`. That one flag decides what the publishing
+endpoint says about a line that is not yours:
+
+| the line is  | answer | why |
+|--------------|--------|-----|
+| listed       | `403`  | admitting the name is taken tells the caller nothing they cannot read in `GET /api/v1/spls` |
+| withdrawn    | `404`  | the same answer, code and wording as a name nobody registered, so the write path cannot be walked to find what the read path hides |
+
+Withdrawing hides a line. It deletes nothing: every release and every DOI stays
+exactly where it is, and the owner can still publish to it.
+
+## Authorship
+
+A publication is credited to the publishing developer's profile, read server
+side and never from a request field, because an author line a stranger can
+choose is an impersonation vector on a permanent record.
+
+The profile feature is **not** required. When the product installs it, the
+credit is the `name` and `surname` on the developer's `UserProfile`, read
+through `UserProfileService.get_by_user_id`. When it does not, or when the
+developer never filled the form in, the credit is `SPLENT MARKETPLACE`. It is
+never the email address, which would put a personal address on a permanent
+public record.
+
+A SPLENT profile holds a name and a surname and nothing else, so that is all
+that is sent. There is no affiliation and no ORCID to send.
+
+## Commands
+
+```bash
+splent db:seed
+splent feature:spl_registry import-catalog [--path ...] [--owner email] [--dry-run]
+splent feature:spl_registry list
+splent feature:spl_registry stuck [--hours 1]
+splent feature:spl_registry settle <spl> <version> [--doi ...] [--note ...]
+splent feature:spl_registry set-owner <spl> <email>
+splent feature:spl_registry visibility <spl> public|withdrawn
+```
+
+`splent db:seed` runs `SplRegistrySeeder`, which **carries the three
+`splent_catalog` lines as data**: their name, description, mirror, DOI and file
+name are written out in `seeders.py`. That is the copy that survives the
+directory being deleted, and it is what rebuilds the registry on a fresh
+database. `import-catalog` does the same job by *reading* the directory, so use
+it for the one-off migration while `splent_catalog` is still on disk and the
+seeder from then on. Both are idempotent.
+
+Neither records a content digest for the lines it brings in. The digest is the
+idempotency key, and a release carrying one is the registry promising these
+exact bytes are what that DOI serves. Nothing has compared them, and one of the
+three does not even point at the file sitting next to it
+(`sample_splent_spl` serves `sample_splent_app.uvl`), so the digest is left
+empty and the local one is recorded as a note instead.
+
+Imported lines arrive with **no owner**, which is what stops any authenticated
+developer from publishing to them; `set-owner` hands one over.
+
+## Requires
+
+`auth` (the User an owner and a publisher point at) and `apikeys` (the
+`write_spl` Bearer token the publishing endpoint is guarded by).
+
+`profile` is **optional**. It improves the credit on a publication and the name
+shown on the public page, and the feature works without it.
+
+## Tests
+
+```bash
+splent feature:test splent_feature_spl_registry
+```
+
+Unit, integration and functional. The suite never reaches UVLHub: the conftest
+replaces the four relay calls **and** the HTTP client underneath them, and it
+does so through its own `MonkeyPatch` rather than the shared fixture. That last
+detail is not decoration. While the shared fixture was used, a single
+`monkeypatch.undo()` inside a test restored the real relay along with the real
+`UVLHUB_API_KEY`, and a test run minted a permanent DOI on production Zenodo.
+Publishing is irreversible, so the guard has to be one a test cannot lift.