RFC-0019 · Module Registry Protocol
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Scope
This RFC defines the Gnomon module registry protocol: the format of registry manifests, the gnomon publish command, authentication, private registry configuration, semver-lint gating, version yanking, and mirror/cache registries for air-gapped environments.
This RFC covers:
- Registry manifest format (how a published module is described in a registry entry)
gnomon publishCLI — pre-publish validation, digest computation, and registry upload- Registry authentication: API key via environment variable and scoped tokens
- Private registry configuration in
project.gnmorgnomon.config - Semver linting integration (
gnomon publishMUST rungnomon lint --semverbefore upload) - Yanking a published version: marking a release as withdrawn without deleting the artifact
- Mirror and cache registry configuration for air-gapped or restricted environments
This RFC does not cover:
- Module resolution or the lockfile format — those are defined in RFC-0014
- The
gnomon updatecommand — defined in RFC-0014 §9 - Import constraint syntax — defined in RFC-0014 §5
- Per-module access control models beyond scoped tokens (reserved for a future security RFC)
- Package signing or supply-chain provenance beyond SHA-256 content digests
2. Goals
- A published module MUST be described by a registry manifest that is both human-readable and machine-parseable, and that includes the information needed for RFC-0014 resolution without additional fetches.
gnomon publishMUST be idempotent: publishing the same digest twice is a no-op and MUST NOT produce an error.gnomon publishMUST gate ongnomon lint --semver; a non-zero lint result MUST block publication when lint code L01401 (breaking change under minor/patch bump) is present.- Authentication credentials MUST NOT appear in
project.gnmor any committed configuration file; they MUST be supplied via environment variables or a local credential store. - A yanked version MUST remain resolvable from an existing
module.lockbut MUST NOT be selected by fresh resolution unless explicitly pinned. - Mirror registries MUST be transparent to the resolution algorithm — the lockfile
digestvalue is computed against the canonical artifact content, not the mirror’s response. - The registry protocol MUST be implementable over HTTPS with no requirement for a proprietary transport.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Registry Manifest Format
A registry manifest is a JSON document returned by a registry server when a client queries a module at a specific version. It is the canonical record of a published release.
3.1 Manifest Schema
{
"id": "com.example.hr",
"version": "1.4.2",
"digest": "sha256:a3f1c2d4...",
"published": "2026-04-29T12:00:00Z",
"publishedBy": "operator@example.com",
"status": "active",
"description": "Human-readable description of the module.",
"tags": ["stable", "reviewed"],
"dependencies": {
"com.example.core": "^1.9.0"
},
"artifacts": {
"bundle": "https://registry.example.com/modules/com.example.hr/1.4.2/bundle.gnomonpkg",
"sources": "https://registry.example.com/modules/com.example.hr/1.4.2/sources.tar.gz"
}
}
3.2 Field Definitions
| Field | Required | Description |
|---|---|---|
id | Yes | Canonical module identifier matching module.gnm id: |
version | Yes | Exact semver string (RFC-0014 §3) |
digest | Yes | SHA-256 content digest of the .gnomonpkg bundle artifact |
published | Yes | ISO-8601 UTC timestamp of publication |
publishedBy | Yes | Identity of the publishing principal (email or service account) |
status | Yes | One of active, yanked. Yanked versions carry a yankReason string. |
description | No | Human-readable module description (max 512 chars) |
tags | No | Array of freeform string labels |
dependencies | Yes | Object mapping dependency module IDs to version constraints; mirrors the imports block from module.gnm |
artifacts.bundle | Yes | HTTPS URL to the compiled .gnomonpkg bundle |
artifacts.sources | No | HTTPS URL to the source archive |
3.3 Registry API Surface
Implementations MUST support the following HTTP endpoints:
| Method | Path | Description |
|---|---|---|
GET | /v1/modules/{id}/versions | List all non-yanked versions of a module |
GET | /v1/modules/{id}/versions/{version} | Fetch the manifest for a specific version |
PUT | /v1/modules/{id}/versions/{version} | Publish a new version (authenticated) |
POST | /v1/modules/{id}/versions/{version}/yank | Yank a published version (authenticated) |
GET | /v1/modules/{id}/versions?includeYanked=true | List all versions including yanked |
Registry implementations MAY add additional endpoints. The above five are the minimum required for the Gnomon toolchain.
4. The gnomon publish Command
4.1 Pre-Publish Validation Steps
gnomon publish executes the following steps in order. Any step that fails halts publication with a non-zero exit code.
- Load module identity. Read
module.gnmto extractidandversion. - Compute digest. Build the module to produce a deterministic
.gnomonpkgbundle (RFC-0002), then compute its SHA-256 digest. - Check version uniqueness. Query the selected authoritative registry for an existing manifest at this (id, version). If one exists and its digest matches the local bundle digest, publication is a no-op (exit 0). If the digests differ, emit M01901 and halt.
- Run semver lint. Execute
gnomon lint --semver. If L01401 is present (breaking change under minor/patch bump), halt with a diagnostic. If L01402 is present (warn-only), log the warning and continue. - Authenticate. Resolve credentials using the order defined in §5.2.
- Upload. PUT the bundle and manifest to the registry endpoint.
- Confirm. GET the manifest back and verify the digest matches the locally computed digest. Emit M01902 if mismatch.
4.2 CLI Interface
gnomon publish # Publish current module using configured registry
gnomon publish --registry <url> # Override registry URL for this invocation
gnomon publish --dry-run # Run steps 1–5; skip upload and confirmation
gnomon publish --skip-lint # Skip semver lint (not recommended; emits M01910 warning)
gnomon publish --tag <tag> # Add a tag label to the registry manifest
4.3 Digest Computation
The digest is computed over the canonical byte content of the .gnomonpkg bundle (RFC-0002). The bundle MUST be produced by a deterministic compile (same source, same compiler version, same resolved lockfile → same bytes). The digest format is sha256:<hex>.
--dry-run executes the local build, digest computation, registry lookup, semver lint, and credential resolution. It does not upload a bundle or perform the post-upload GET confirmation. A same-digest publication is a no-op after step 3 and does not require the remaining steps.
5. Authentication
5.1 Authentication Model
The registry authenticates publishers using either:
- API key: A long-lived secret associated with a registry account.
- Scoped token: A short-lived token scoped to a specific module ID and/or operation (publish, yank, read).
All credentials are transmitted via the Authorization: Bearer <token> HTTP header.
5.2 Credential Resolution Order
gnomon publish resolves credentials in this order:
--token <value>CLI flag (SHOULD NOT be used in automated or CI contexts; the secret appears in shell history and process listings)GNOMON_REGISTRY_TOKENenvironment variableGNOMON_REGISTRY_API_KEYenvironment variable- Platform credential store (e.g., macOS Keychain,
~/.gnm/credentialson Linux)
Credentials MUST NOT be stored in project.gnm, gnomon.config, module.gnm, or any file that may be committed to version control. Doing so is a security violation and implementations SHOULD warn if a credential-shaped string is detected in a committed config file.
5.3 Scoped Tokens
Scoped tokens restrict the operations a credential may perform:
{
"tokenId": "tok_abc123",
"scope": {
"moduleId": "com.example.hr",
"operations": ["publish"]
},
"expiresAt": "2026-07-01T00:00:00Z"
}
A token scoped to publish on com.example.hr cannot yank a different module or publish to com.example.payroll. Tokens that exceed their scope produce M01903 from the registry server.
6. Registry Configuration
6.1 Configuration Location
The active registry is configured in project.gnm (project-level) or ~/.gnm/config (user-level). Project-level configuration takes precedence.
// project.gnm
registry {
default: "https://registry.gnomon.sh"
scopes {
"com.example": "https://registry.internal.example.com"
}
}
6.2 Private Registry
A private registry URL is declared in the registry.scopes map under a module-ID namespace prefix. Both gnomon publish and the resolver select the longest matching prefix, where a match is the complete module ID or is followed by .. If no prefix matches, they use registry.default. This rule is applied to the effective configuration after project-level settings take precedence over user-level settings. The single-URL registry.private key is not part of this contract.
registry {
default: "https://registry.gnomon.sh"
scopes {
"com.example": "https://registry.internal.example.com"
}
}
6.3 Mirror and Cache Registries (Air-Gapped Environments)
A mirror registry is a read-only proxy that caches upstream registry responses. It is configured via registry.mirror:
registry {
default: "https://registry.gnomon.sh"
mirror: "https://mirror.internal.example.com"
mirrorFallback: false // If true, fall back to default registry on mirror miss
}
When a mirror is configured:
- All resolution reads are directed to the mirror.
gnomon publishwrites directly to the authoritative registry selected byregistry.scopesorregistry.default— mirrors are read-only.- The digest in
module.lockis always the SHA-256 of the canonical artifact, not the mirror’s cached copy. The resolver MUST verify the digest after fetching from a mirror. - If
mirrorFallback: false(the default), a mirror miss is a hard error M01904. This is the correct setting for strict air-gapped environments. - If
mirrorFallback: true, the resolver falls back to the upstream registry on a mirror miss and emits a warning M01905.
7. Yanking a Version
Yanking marks a published version as withdrawn without deleting it from the registry. The artifact remains downloadable to consumers who have it in their module.lock, but gnomon update and fresh resolution will skip yanked versions unless explicitly pinned.
7.1 Yank Command
gnomon yank <module-id>@<version> --reason "security vulnerability CVE-2026-001"
The --reason flag is required. Its value is stored in the manifest yankReason field.
7.2 Yank Semantics
- A yanked version remains in the registry manifest with
"status": "yanked". - Fresh resolution (when no
module.lockexists orgnomon updateis run) MUST skip yanked versions. If the only version satisfying a constraint is yanked, the resolver emits M01906. - A locked build (resolved from
module.lock) MUST still resolve successfully from a yanked version and MUST NOT emit an error. It SHOULD emit a warning M01907 advising the operator to rungnomon update. - Yanks cannot be undone. A corrected release requires a new version number.
- Only the original publisher or a registry admin may yank a version.
8. Failure Modes
| Scenario | Outcome | Diagnostic |
|---|---|---|
| Publishing a version that already exists with a different digest | Publish halts | M01901 |
| Registry returns unexpected digest after upload | Publish halts, artifact suspect | M01902 |
| Credential exceeds token scope | Registry returns 403; publish halts | M01903 |
Mirror registry returns a miss and mirrorFallback: false | Resolution halts | M01904 |
Mirror registry returns a miss and mirrorFallback: true | Resolution falls back to upstream | M01905 (warning) |
| Fresh resolution finds only yanked versions satisfying a constraint | Resolution halts | M01906 |
| Locked build resolves a yanked version | Resolves successfully, advisory warning emitted | M01907 (warning) |
| (reserved) | (reserved for future use) | M01908 — Reserved |
| (reserved) | (reserved for future use) | M01909 — Reserved |
gnomon publish run with --skip-lint | Publish proceeds without semver gate | M01910 (warning) |
gnomon lint --semver reports L01401 | Publish halts | — (L01401 is the blocking code) |
| Registry unreachable during publish | Publish halts after timeout | M01911 |
9. Invariants
- Immutability of published releases. A published (id, version) pair is immutable. The artifact, its digest, and its dependencies cannot be modified after publication. A corrected release requires a new version number.
- Digest authority. The
digestfield inmodule.lockand the registry manifest refer to the same canonical artifact bytes. Any mismatch between them is a hard error. - Semver gate.
gnomon publishMUST NOT succeed whengnomon lint --semverreports L01401 unless--skip-lintis explicitly provided.--skip-lintMUST emit M01910. - Credential isolation. Credentials MUST NOT appear in any committed source file. The credential resolution order defined in §5.2 is authoritative; no other mechanism may supply credentials.
- Yank durability. A yanked version MUST remain in the registry (artifact and manifest) indefinitely. Deletion is not permitted; yank is the only withdrawal mechanism.
- Mirror digest verification. Artifacts fetched from a mirror MUST be verified against the digest in
module.lockbefore being accepted as valid. A mirror cannot substitute a different artifact. - No silent fallback. When
mirrorFallback: false, a mirror miss MUST produce a hard error, not a silent fallback. Air-gapped environments rely on this guarantee.
10. Diagnostic Codes (M019xx)
All diagnostics introduced by this RFC occupy the M01900–M01999 range.
| Code | Severity | Summary |
|---|---|---|
| M01901 | Error | Version already published with a different digest; cannot overwrite. |
| M01902 | Error | Registry-returned digest does not match locally computed digest after upload. |
| M01903 | Error | Registry rejected credential: token scope does not permit this operation. |
| M01904 | Error | Mirror registry returned a cache miss and mirrorFallback is disabled. |
| M01905 | Warning | Mirror cache miss; falling back to upstream registry (mirrorFallback: true). |
| M01906 | Error | No non-yanked version satisfies the import constraint. |
| M01907 | Warning | Locked build is resolving a yanked version; run gnomon update to move off it. |
| M01908 | — | Reserved. |
| M01909 | — | Reserved. |
| M01910 | Warning | gnomon publish was run with --skip-lint; semver gate bypassed. |
| M01911 | Error | Registry unreachable; publish or resolution cannot proceed. |