Where the prototype departs from its design, or stops short of it. Written down rather than discovered.
SHACL validation runs on the record being written, before it is committed. Constraints that
would need the rest of the store — sh:class on a referenced node, say — are therefore not
evaluated. That is the price of validating before committing rather than after.
Validation itself is real SHACL: shapes/tar-shapes.ttl is enforced by a SHACL engine, and
editing that file changes what the API accepts with no Rust change. Severity decides:
sh:Violation blocks, sh:Warning never does, and TAR_SHACL_VALIDATE_WRITES=false downgrades
violations to warnings.
Two rules that do need the rest of the graph live in Rust for exactly this reason, and report
through the same sh:ValidationReport: whether an artifact type is a term the registry holds,
and whether a deployment of non-deployable software may carry an endpoint. Neither honours
TAR_SHACL_VALIDATE_WRITES — a half-described record is a trade an operator can make, an
unlookuppable type is not.
The first of those is exactly sh:class, and it was measured rather than assumed. Injecting the
bundles' class assertions into the candidate data graph so the engine can see them takes
validation from 1.9 ms to 9.8 ms per write, plus 2.8 ms to read them back, against the
52 µs the targeted lookup costs — roughly 2 ms a write against 12.6 ms.
The time is the smaller objection. Three things a shape cannot do at all settled it:
sh:message is fixed text and could not name the offending IRI or the way out;
TAR_SHACL_VALIDATE_WRITES=false would switch the rule off; and the allowance for a type cached
from a peer is about which named graph a concept sits in, which the engine's single data graph
cannot express.
The design shows blank nodes. They are minted as IRIs instead, which makes them addressable and
citable. A record still reads as one document, because describe returns them with their parent.
tar:instanceOf and tar:atInstance sit alongside the authoritative
prov:qualifiedAssociation. Every list and count query would otherwise be a two-hop join
through a reified node.
Repository sync is — a record can keep named fields in step with its source repository. What is missing is the liveness signal the design asked for: stars, forks, last commit. The UI degrades by omitting those cells rather than rendering zeros.
Sign-in itself is verified against a live identity provider: a browser was driven through
authorisation code + PKCE, and the curator and admin roles were confirmed to decide what a
signed-in person may do — POST /api/v1/software succeeds for a curator, /api/v1/peers is
403 for a curator and 200 for an admin.
The gap was refresh: the access token was used until it expired with no silent renewal, so a
long editing session ended in a 401 and a re-sign-in with the form's contents lost. The
registry now renews twice over — from a timer set from the token's own exp claim, ahead of
expiry, and reactively when a request comes back 401 for the case the timer missed (a laptop
that slept through it). Concurrent requests that all expire together share one renewal rather
than each spending the refresh token, which matters once a provider rotates it: the first use
would otherwise invalidate it for the rest.
The refresh token itself stays exactly where the design note said it should not go: in memory
only, never sessionStorage, localStorage, or a cookie. A closed tab or a reload ends the
renewable session — the access token in sessionStorage keeps working until it expires, then
sign-in is needed again — which is the trade this file has always made, kept rather than
loosened to get renewal.
A registry API token has no refresh token to renew with, so nothing changes for it: a 401
still means sign in again, exactly as before.
Fan-out is live, and results are not deduplicated across peers beyond the origin chip. Two peers that both cache a stub of the same third-party record produce two rows.
The resolver fetches a whole Turtle document into the peer graph rather than extracting a minimal stub, so a verbose peer can cache considerably more than the type, title, publisher and home registry the design called for.
Which is time-ordered within one registry, because identifiers are UUIDv7. Across origins it interleaves imperfectly.
Deferred. GET /api/v1/graph and GET /api/v1/artifacts/{id}/lineage already return exactly
what a graph view would need.
A write is judged on the whole record it asserts, and a PATCH carries the fields the caller did
not name — so a record citing a term the registry has since retired is refused on an edit to some
other field entirely.
The boot log names every such record and the term, once, rather than deleting a value nobody asked it to delete. Replacing or clearing the named term fixes the record permanently. Nothing shipped is affected; a long-lived store might be.
It is a term this registry holds, so citing it is fine. It carries none of this registry's own classes, so the picker does not list it.
That is the conservative half-answer. Which registry owns a term, and whether adopting a peer's implies agreeing with it, is a federation question this prototype does not settle. The picker's adopt flow is how to make such a term first-class here.
The software page shows what was declared. What a deployment has actually produced is one SPARQL query away, and the two can disagree. Surfacing the disagreement should wait until there is enough run data for it to mean something.
A subscription's webhook URL is checked against private and loopback addresses at registration
and re-resolved at send time. The send-time check used to return only a verdict, leaving the
HTTP client to resolve the name a second time — so a record with a short TTL could answer the
check with a public address and the connection with 169.254.169.254.
The check now returns the addresses it approved and the delivery is pinned to them, so there is no second lookup to win. TLS still verifies the certificate against the hostname: pinning replaces DNS, not identity.
Managing a subscription reuses the rule that governs token management — admin, curator, or the
credential of the owning deployment. There is no subscribe:* scope, so a credential cannot be
issued that may subscribe and nothing else.
GraphStore is a synchronous trait — it predates the second backend, and every read in the
registry is a plain function call because the store used to be in-process. Against
TAR_SPARQL_ENDPOINT, calling one of its methods directly from an async handler occupied that
handler's Tokio worker thread for the whole HTTP round trip: on a multi-threaded runtime with
more concurrent requests than worker threads, one slow remote query delayed every other request
the same worker was about to advance.
Making the trait itself async fn — the fix this entry used to name — turned out to be far
larger than it reads: not 119 call sites, but recolouring most of src/domain, most of
src/api, and src/auth/jwt, converting every synchronous store-layer unit test to
#[tokio::test], and rewriting iterator patterns that call domain functions into stream
combinators. The change actually made is the one Tokio's own documentation recommends for
exactly this shape of problem: every request-path call site — all ~90 API handlers across 18
files, and the three OIDC credential-binding lookups in auth::jwt that run on every
bearer-token request before any handler is reached — passes its synchronous, store-touching
work to [error::blocking], which runs it on Tokio's dedicated blocking thread pool and gives
the worker thread back to the scheduler for the round trip's duration. Ctx moved from
borrowing &AppState to owning an Arc<AppState> clone so it can cross that boundary. Nothing
in src/domain or src/store changed: the same synchronous functions run, just on a different
thread.
Two call sites were deliberately left as they were, both flagged in code comments: the
per-artifact and per-was_derived_from-parent existence checks inside advertise()'s main
loop, and the equivalent one in the OpenLineage adapter's map_dataset. Both interleave a
synchronous exists() check with state.ops.* calls that are already async, inside a loop that
decides its own control flow per iteration — cleanly separating the two would mean restructuring
the loop into two passes, which is a larger and more error-prone change than the check's actual
cost justifies: it is a single fast existence lookup, not a scan.
Also unwrapped, and deliberately: seed.rs, bundles.rs::sync, and the peer-resolver and
health-check background loops. Those run once at boot or pace themselves on their own timer,
never competing with a flood of concurrent user requests for the same worker pool, which is the
specific failure this fix closes.
Embedded Oxigraph, the default, is unaffected either way: those calls never leave the process, so moving them to a different thread pool costs a small fixed dispatch overhead and buys nothing. The behavioural difference only shows up against a remote endpoint under real concurrent load.
A registry write is built into a single SPARQL Update request so that its deletions and insertions are one unit. Fuseki, GraphDB, Virtuoso and Oxigraph's own server execute a request in one transaction, which is what makes this equivalent to the embedded backend's transaction.
SPARQL 1.1 does not require that. Against a server that processes the operations of a request independently, a write is atomic only per operation, and the registry has no way to tell over HTTP which kind of server it is talking to. It does not attempt to detect it and does not claim the guarantee it cannot verify.
Neither affects the embedded default.
A subject deletion follows the ownership closure four levels deep, where the embedded store's walk is unbounded. A record's sub-resources — its distributions, its checksums — are removed with it so that replacing a record does not orphan them, and doing that inside one atomic update request means a fixed-depth pattern rather than a walk that can look at what it found. The deepest nesting the registry writes is two levels, so this is headroom; a sub-resource nested deeper than four would be orphaned against an external endpoint and removed against the embedded one.
/admin/dump and tar dump materialise the whole graph in memory on the external backend,
because there is no streaming path from a SELECT result to the response body. Embedded
Oxigraph streams. For a catalogue-sized registry this is fine and for a very large external
dataset it is not; back that up with the store's own tools instead.
tar dump with no argument writes N-Quads and restores faithfully. tar dump --graph <g> writes
N-Triples — which is what /admin/dump?graph= and peer stub exchange want — so restoring that
file with tar restore puts its triples in the default graph, where nothing looks for them.
Pre-existing behaviour, unchanged by the second backend, and worth knowing before using a
single-graph dump as a backup.