gnomonlearn
Docs/Registry upload wire contract decision

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.

Use one PUT request with Content-Type: multipart/form-data and exactly two named parts:

  1. manifest: application/json; charset=utf-8, a UTF-8 JSON publish request, distinct from the registry’s completed manifest. Required fields are id, version, digest, and dependencies; optional fields are description and tags. The request does not accept published, publishedBy, status, or artifacts, which are server-owned. The JSON schema and version must be published with RFC-0019 before implementation.
  2. bundle: application/vnd.gnomon.bundle+zip (final media type subject to RFC-0002), containing the exact canonical .gnomonpkg bytes. 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.