gnomonlearn

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 publish CLI — pre-publish validation, digest computation, and registry upload
  • Registry authentication: API key via environment variable and scoped tokens
  • Private registry configuration in project.gnm or gnomon.config
  • Semver linting integration (gnomon publish MUST run gnomon lint --semver before 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 update command — 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

  1. 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.
  2. gnomon publish MUST be idempotent: publishing the same digest twice is a no-op and MUST NOT produce an error.
  3. gnomon publish MUST gate on gnomon lint --semver; a non-zero lint result MUST block publication when lint code L01401 (breaking change under minor/patch bump) is present.
  4. Authentication credentials MUST NOT appear in project.gnm or any committed configuration file; they MUST be supplied via environment variables or a local credential store.
  5. A yanked version MUST remain resolvable from an existing module.lock but MUST NOT be selected by fresh resolution unless explicitly pinned.
  6. Mirror registries MUST be transparent to the resolution algorithm — the lockfile digest value is computed against the canonical artifact content, not the mirror’s response.
  7. 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

FieldRequiredDescription
idYesCanonical module identifier matching module.gnm id:
versionYesExact semver string (RFC-0014 §3)
digestYesSHA-256 content digest of the .gnomonpkg bundle artifact
publishedYesISO-8601 UTC timestamp of publication
publishedByYesIdentity of the publishing principal (email or service account)
statusYesOne of active, yanked. Yanked versions carry a yankReason string.
descriptionNoHuman-readable module description (max 512 chars)
tagsNoArray of freeform string labels
dependenciesYesObject mapping dependency module IDs to version constraints; mirrors the imports block from module.gnm
artifacts.bundleYesHTTPS URL to the compiled .gnomonpkg bundle
artifacts.sourcesNoHTTPS URL to the source archive

3.3 Registry API Surface

Implementations MUST support the following HTTP endpoints:

MethodPathDescription
GET/v1/modules/{id}/versionsList 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}/yankYank a published version (authenticated)
GET/v1/modules/{id}/versions?includeYanked=trueList 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.

  1. Load module identity. Read module.gnm to extract id and version.
  2. Compute digest. Build the module to produce a deterministic .gnomonpkg bundle (RFC-0002), then compute its SHA-256 digest.
  3. 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.
  4. 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.
  5. Authenticate. Resolve credentials using the order defined in §5.2.
  6. Upload. PUT the bundle and manifest to the registry endpoint.
  7. 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:

  1. --token <value> CLI flag (SHOULD NOT be used in automated or CI contexts; the secret appears in shell history and process listings)
  2. GNOMON_REGISTRY_TOKEN environment variable
  3. GNOMON_REGISTRY_API_KEY environment variable
  4. Platform credential store (e.g., macOS Keychain, ~/.gnm/credentials on 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 publish writes directly to the authoritative registry selected by registry.scopes or registry.default — mirrors are read-only.
  • The digest in module.lock is 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.lock exists or gnomon update is 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 run gnomon 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

ScenarioOutcomeDiagnostic
Publishing a version that already exists with a different digestPublish haltsM01901
Registry returns unexpected digest after uploadPublish halts, artifact suspectM01902
Credential exceeds token scopeRegistry returns 403; publish haltsM01903
Mirror registry returns a miss and mirrorFallback: falseResolution haltsM01904
Mirror registry returns a miss and mirrorFallback: trueResolution falls back to upstreamM01905 (warning)
Fresh resolution finds only yanked versions satisfying a constraintResolution haltsM01906
Locked build resolves a yanked versionResolves successfully, advisory warning emittedM01907 (warning)
(reserved)(reserved for future use)M01908 — Reserved
(reserved)(reserved for future use)M01909 — Reserved
gnomon publish run with --skip-lintPublish proceeds without semver gateM01910 (warning)
gnomon lint --semver reports L01401Publish halts— (L01401 is the blocking code)
Registry unreachable during publishPublish halts after timeoutM01911

9. Invariants

  1. 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.
  2. Digest authority. The digest field in module.lock and the registry manifest refer to the same canonical artifact bytes. Any mismatch between them is a hard error.
  3. Semver gate. gnomon publish MUST NOT succeed when gnomon lint --semver reports L01401 unless --skip-lint is explicitly provided. --skip-lint MUST emit M01910.
  4. 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.
  5. Yank durability. A yanked version MUST remain in the registry (artifact and manifest) indefinitely. Deletion is not permitted; yank is the only withdrawal mechanism.
  6. Mirror digest verification. Artifacts fetched from a mirror MUST be verified against the digest in module.lock before being accepted as valid. A mirror cannot substitute a different artifact.
  7. 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.

CodeSeveritySummary
M01901ErrorVersion already published with a different digest; cannot overwrite.
M01902ErrorRegistry-returned digest does not match locally computed digest after upload.
M01903ErrorRegistry rejected credential: token scope does not permit this operation.
M01904ErrorMirror registry returned a cache miss and mirrorFallback is disabled.
M01905WarningMirror cache miss; falling back to upstream registry (mirrorFallback: true).
M01906ErrorNo non-yanked version satisfies the import constraint.
M01907WarningLocked build is resolving a yanked version; run gnomon update to move off it.
M01908—Reserved.
M01909—Reserved.
M01910Warninggnomon publish was run with --skip-lint; semver gate bypassed.
M01911ErrorRegistry unreachable; publish or resolution cannot proceed.