Module registry 

Phase S (v0.5): registry primitive — verifiable distribution.

A registry is a directory of RegistryEntrys, each one a signed manifest pointing at a frontier publication. Pulling a frontier through a registry verifies:

1. The manifest signature was produced by the owner’s pubkey.
2. The pulled frontier’s snapshot_hash matches the registered value.
3. The pulled frontier’s event_log_hash matches the registered value.

Cross-frontier links (vf_…@vfr_… references) are deferred to v0.6. v0.5’s registry is the npm-tarball-with-a-signature shape: archival, reproducibility, integrity-checked transfer between collaborating institutions.

A registry is NOT a Vela frontier (deferred to v0.6 once cross-frontier semantics exist). For now it’s a flat entries.json + pubkeys.json pair on disk or fetched over HTTP.

Structs

PublishResponse

Server response shape from POST <hub>/entries.

PullResult

Outcome of pull_transitive. The primary frontier and every recursively-resolved cross-frontier dependency end up as files on disk; verified lists the vfr_ids whose snapshot pin matched.

Registry

On-disk registry shape: a JSON file containing the schema marker and an array of entries. Multiple publications of the same vfr_id are appended; readers select the latest by signed_publish_at.

RegistryEntry

A single signed publication of a frontier into a registry. The signature is Ed25519 over the canonical preimage of the entry’s fields minus the signature itself. Two implementations agree on the signing-bytes derivation by following the same canonical-JSON rule already used for vev_…/vpr_….

Constants

ENTRY_SCHEMA

REGISTRY_SCHEMA

Functions

entry_signing_bytes

Build the canonical preimage for an entry’s signature.

event_first_snapshot_locator

Build the event-first snapshot endpoint for a hub registry locator. Returns None for local registries. The caller should still verify the downloaded bytes against the signed manifest.

fetch_frontier_to

Fetch a frontier file from its locator (the network_locator field on a registry entry) into a local destination path. Supports file://, bare paths, and https://. Returns the destination path on success.

fetch_frontier_to_prefer_event_hub

Fetch a frontier for a registry entry, preferring the event-first hub read path when the registry itself came from a hub URL. Falls back to network_locator only for older hubs that do not expose the snapshot endpoint. Verification remains the caller’s job.

find_latest

Find the latest entry for vfr_id in a local registry, by signed_publish_at. Returns None if no entry exists.

load_any

Fetch a registry from anywhere it might live. v0.7 (this phase):

load_local

Load a registry from a local file (JSON). Returns an empty registry if the file does not exist.

publish_entry

Append a signed entry to a registry, replacing any prior entry for the same vfr_id (latest-publish-wins).

publish_remote

Push a signed entry to a remote hub. The transport is doctrine-light: canonical JSON over HTTPS POST. The hub verifies the signature and stores the bytes verbatim.

pull_transitive

Pull a frontier and recursively pull every cross-frontier dependency it declares, verifying each pinned snapshot hash along the way. The primary’s manifest must live in registry.

resolve_local

Resolve a registry URL/path into a local write path. Used by vela registry publish which can only target a local file. v0.6 supports:

save_local

sign_entry

Sign an unsigned entry (with signature as empty string), returning a hex-encoded Ed25519 signature.

verify_entry

Verify an entry’s signature against owner_pubkey.

verify_pull

Pull verification: given a registry entry and the path to a pulled-frontier file on disk, verify that: