RFC-0019 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0019: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0019.This page is generated from the
lean/Gnomon/Spec/module for RFC-0019. Edit that source and regenerate this catalog.
Title: Module Registry Protocol
Status: draft
Owners: Compiler, Platform
Diagnostic range: M01900-M01999
Proof citations in source: 9 / 9. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Mirror registry | Read-only proxy that caches upstream registry responses for use in air-gapped or restricted environments. |
| Registry manifest | JSON document returned by a registry server describing a published module release at a specific version; the canonical record of a release. |
| Scoped token | Short-lived authentication token restricted to a specific module ID and/or operation (publish, yank, read). |
| Yank | Marking a published version as withdrawn without deleting it; the artifact remains downloadable for locked builds but is skipped by fresh resolution. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
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. |
M01910 | Warning | gnomon publish was run with —skip-lint; semver gate bypassed. |
M01911 | Error | Registry unreachable; publish or resolution cannot proceed. |
Invariants
- A published (id, version) pair is immutable; its artifact, digest, and dependencies cannot be modified after publication. (enforced by: registry)
- A yanked version must remain in the registry indefinitely; deletion is not permitted and yank is the only withdrawal mechanism. (enforced by: registry)
- Artifacts fetched from a mirror must be verified against the digest in module.lock before being accepted. (enforced by: runtime)
- Credentials must not appear in any committed source file; only the §5.2 resolution order may supply them. (enforced by: CLI)
- Publish and resolution select the longest registry.scopes prefix matching a complete module-ID segment; registry.default applies when none matches, after project configuration takes precedence over user configuration. (enforced by: CLI and resolver)
- The digest in module.lock and the registry manifest refer to the same canonical artifact bytes; any mismatch is a hard error. (enforced by: runtime)
- When mirrorFallback is false, a mirror miss must produce a hard error rather than silently falling back upstream. (enforced by: runtime)
- gnomon publish —dry-run runs local build, digest, registry lookup, semver lint, and credential resolution, but performs neither upload nor post-upload confirmation. (enforced by: CLI)
- gnomon publish builds the deterministic bundle and computes its digest before comparing that digest with an existing registry manifest; equal digests are a no-op and unequal digests emit M01901. (enforced by: CLI)
- gnomon publish must not succeed when gnomon lint —semver reports L01401 unless —skip-lint is explicitly provided, which must emit M01910. (enforced by: CLI)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Authentication
- MUST_NOT — Credentials MUST NOT be stored in project.gnm, gnomon.config, module.gnm, or any committed file.
- SHOULD — Implementations SHOULD warn if a credential-shaped string is detected in a committed config file.
- SHOULD_NOT — The —token CLI flag SHOULD NOT be used in automated or CI contexts.
Goals
- MUST — A published module MUST be described by a registry manifest that is human-readable, machine-parseable, and sufficient for RFC-0014 resolution.
- MUST — A yanked version MUST remain resolvable from an existing module.lock but MUST NOT be selected by fresh resolution unless explicitly pinned.
- MUST_NOT — Authentication credentials MUST NOT appear in project.gnm or any committed configuration file.
- MUST — Mirror registries MUST be transparent to resolution; the lockfile digest is computed against canonical artifact content.
- MUST — The registry protocol MUST be implementable over HTTPS with no proprietary transport requirement.
- MUST — gnomon publish MUST be idempotent: republishing the same digest is a no-op. (proof citation:
rfc0019_b20_grounded; verification pending) - MUST — gnomon publish MUST gate on gnomon lint —semver and block on L01401.
Invariants
- MUST — —skip-lint MUST emit diagnostic M01910. (proof citation:
rfc0019_b5_grounded; verification pending) - MUST_NOT — A published (id, version) pair is immutable; artifact, digest, and dependencies cannot be modified after publication. (proof citation:
rfc0019_b1_grounded; verification pending) - MUST — A yanked version MUST remain in the registry indefinitely; deletion is not permitted. (proof citation:
rfc0019_b27_grounded; verification pending) - MUST — Artifacts fetched from a mirror MUST be verified against the digest in module.lock.
- MUST — When mirrorFallback is false, a mirror miss MUST produce a hard error, not a silent fallback. (proof citation:
rfc0019_b16_grounded; verification pending) - MUST_NOT — gnomon publish MUST NOT succeed when gnomon lint —semver reports L01401 unless —skip-lint is explicitly provided. (proof citation:
rfc0019_b13_grounded; verification pending)
Registry Configuration
- MUST — The resolver MUST verify the digest after fetching an artifact from a mirror.
- MUST — gnomon publish MUST write directly to the authoritative registry selected by registry.scopes or registry.default; mirrors are read-only.
Registry Manifest Format
- MAY — Registry implementations MAY add additional endpoints beyond the required minimum.
- MUST — Registry implementations MUST support the five HTTP endpoints listed in §3.3. (proof citation:
rfc0019_b9_grounded; verification pending)
The gnomon publish Command
- MUST — The .gnomonpkg bundle MUST be produced by a deterministic compile so that identical inputs yield identical bytes.
- MUST — gnomon publish MUST execute the pre-publish validation steps in order; any failed step halts publication.
Yanking a Version
- MUST — A locked build MUST still resolve successfully from a yanked version and MUST NOT emit an error.
- SHOULD — A locked build resolving a yanked version SHOULD emit warning M01907. (proof citation:
rfc0019_b24_grounded; verification pending) - MUST — Fresh resolution MUST skip yanked versions; emit M01906 if only yanked versions satisfy a constraint. (proof citation:
rfc0019_b11_grounded; verification pending)
Linked References
(no cross-RFC dependencies)