Registry upload wire contract decision
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: proposed for owner decision. Owners: specification, registry service,
compiler, and framework CLI. RFC-0019 defines a PUT of a bundle and manifest
at /v1/modules/{id}/versions/{version} but does not define one HTTP request
body, response, or concurrent-create rule. The framework has a tested publish
sequence and manifest GET reader; its upload adapter cannot be interoperable
until those bytes are specified. RFC-0002’s canonical .gnomonpkg schema is
also under reconciliation in BUNDLE_CONTRACT_PROPOSAL.md.
Recommended wire contract
Use one PUT request with Content-Type: multipart/form-data and exactly two
named parts:
manifest:application/json; charset=utf-8, a UTF-8 JSON publish request, distinct from the registry’s completed manifest. Required fields areid,version,digest, anddependencies; optional fields aredescriptionandtags. The request does not acceptpublished,publishedBy,status, orartifacts, which are server-owned. The JSON schema and version must be published with RFC-0019 before implementation.bundle:application/vnd.gnomon.bundle+zip(final media type subject to RFC-0002), containing the exact canonical.gnomonpkgbytes. It is not a base64 string and is never reserialized by the HTTP client.
The request carries Authorization: Bearer <token> and
If-None-Match: *. Its path id and version must equal the JSON fields and
the bundle identity. The server computes SHA-256 over the received bundle
bytes and compares it with the request’s digest; it validates dependency
constraints and checks them against the bundle once RFC-0002 defines the
canonical identity and dependency fields. A mismatch rejects the entire
request without publishing either part. The multipart boundary and headers
are transport framing: they do not enter the artifact digest.
On a new version, the server atomically stores the immutable artifact and a
completed manifest, then returns HTTP 201 with that manifest as JSON. It sets
published from server time, publishedBy from the authenticated principal,
status to active, and artifacts.bundle to its HTTPS artifact URL. A
successful response must already be visible through the required manifest
GET; the CLI still performs its RFC-0019 read-back digest check. The server
does not accept a client-chosen publisher, timestamp, status, or artifact URL.
If another writer creates the same version after the CLI’s initial GET,
conditional PUT returns HTTP 412. The CLI then GETs the manifest: equal
digest is an idempotent no-op; a different digest is M01901. A missing
manifest after 412 is a registry consistency error, not permission to retry an
unconditional write. A server must never replace an existing artifact or
manifest for an (id, version) pair. Authentication and scope failures map to
M01903 where applicable; transport and 5xx failures map to M01911.
The completed JSON manifest remains RFC-0019 §3’s existing schema, so this
proposal adds a publish-request schema rather than changing the response
identity or digest rule. The request’s dependencies object preserves version
constraints; the legacy S3 gnomon-depends-on names-only metadata is not used.
Why this shape
One request gives the server an atomic validation and storage boundary for manifest metadata and canonical bundle bytes. Ordinary multipart parsers can stream the binary part without base64 expansion. Keeping server-owned fields out of the request prevents clients from forging publication metadata. The exact request schema, part names, response, and conditional behavior make the protocol testable by independent clients and registry implementations.
Alternatives considered: a JSON envelope with base64 bundle increases upload size and requires copying the entire artifact through JSON; a binary-only PUT cannot supply dependency constraints or tags without an additional source of truth; two separate PUTs need a transaction protocol to avoid a manifest that points at a missing or mismatched artifact. If RFC-0002 later embeds every publish-request field in canonical bundle bytes, a versioned binary-only request could be designed, but it is not established today.
Acceptance and migration
- Approve the wire format and publish-request schema, then amend RFC-0019 §§3.3–4.1, its companion Q&A, Lean/reference and RDF projections, and registry server API together. Keep existing claim IRIs unless a reviewed semantic change requires new identities.
- Test byte-preserving upload, server digest recomputation, path/JSON/bundle identity mismatch, dependency-range preservation, missing and extra parts, forged server-owned fields, auth/scope failures, 412 races with equal and different digests, atomic failure, and immediate GET confirmation.
- Test the CLI against a real test registry, not only mocked
fetch. Define size limits and streaming behavior. Keep the legacy S3 path and its callers until the public command migration is decided and deployed consumers are verified. - Do not publish this as a stable registry contract while RFC-0002’s deterministic bundle format and identity fields remain unresolved.