diff --git a/compilers/openapi/internal/load/load.go b/compilers/openapi/internal/load/load.go
index aae8b0db..56e7f623 100644
--- a/compilers/openapi/internal/load/load.go
+++ b/compilers/openapi/internal/load/load.go
@@ -35,8 +35,8 @@ import (
 
 // Options is what Load needs from the compiler's own options. It is a separate
 // type rather than the compiler's, because openapi.Options is public API whose
-// shape is fixed by ir-design §10 and most of it describes lowering, which
-// nothing here can see.
+// shape is a published contract (its own doc comment says why) and most of it
+// describes lowering, which nothing here can see.
 type Options struct {
 	// AllowExternalRefs lets reference resolution reach outside the document —
 	// off the filesystem or over the network. Off is the default, so the zero
diff --git a/compilers/openapi/openapi.go b/compilers/openapi/openapi.go
index b1feb110..b7a40374 100644
--- a/compilers/openapi/openapi.go
+++ b/compilers/openapi/openapi.go
@@ -142,8 +142,8 @@ func optionsFrom(opts compilers.Options) (Options, error) {
 
 // loadOptions projects Options onto the subset the load phase reads. It exists
 // so the mapping lives in one place: load.Options is that package's own input,
-// deliberately not this public type, whose shape ir-design §10 fixes and most of
-// which describes lowering the loader cannot see.
+// deliberately not this public type, whose shape is a published contract (see
+// Options) and most of which describes lowering the loader cannot see.
 func loadOptions(o Options) load.Options {
 	out := load.Options{AllowExternalRefs: o.AllowExternalRefs}
 	if o.Overlay != nil {
diff --git a/compilers/openapi/options.go b/compilers/openapi/options.go
index 35c6b812..eb4a7f1d 100644
--- a/compilers/openapi/options.go
+++ b/compilers/openapi/options.go
@@ -25,8 +25,8 @@ const (
 //
 // It stays whole here while each phase below takes its own input projected from
 // it — load.Options, and the strategy the lowering context carries. Its shape is
-// a published contract (ir-design §10), and most of it describes work no single
-// phase does.
+// a published contract, since a caller outside this package constructs this
+// exact type by field, and most of it describes work no single phase does.
 type Options struct {
 	// Grouping selects the operation-grouping strategy.
 	Grouping GroupingStrategy `json:"grouping,omitempty"`