Skip to main content
Publishing verifies a built archive and uploads it. Build is the sole producer of that archive; publish never constructs one on its normal path. This page defines the obligations. Command behavior and prompts are documented at facet publish.

​
Authentication

Publishing is authenticated. If no credential can be resolved, publish MUST fail before any verification or registry request. Errors returned by the registry MUST be rendered verbatim. Implementations show the registry’s own message and suggested fix rather than maintaining a second copy of what each error means.

​
What the author uploads

The complete built archive is uploaded as it exists on disk. No part of it is re-derived at upload time. The name and version addressing the upload MUST come from the verified artifact’s embedded manifest, not from a separate read of the source facet.json. This matters when a user deliberately ships a drifted artifact under its own identity. The private declaration is manifest content, so it travels inside the artifact. There is no separate publish flag for visibility.

​
What the registry does

  1. Verify the upload. The registry runs the same archive verification a consumer would: dispatch on facetVersion, parse the container, verify the integrity hash and every per-entry hash, validate the embedded manifest, and apply the content rules. A verification failure rejects the publish.
  2. Store the artifact. The verified bytes are stored under (name, version), and both the canonical fingerprint and the transport hash are recorded.

​
Review queue

A publish MAY be accepted into a moderation queue rather than published immediately, for example when a name is reserved. This is a success outcome: implementations MUST report that the submission was queued and render the registry’s guidance. The version becomes available once approved.

​
Immutability

Once a version is published, the registry MUST NOT allow republishing that name and version with different content. Because private is manifest content, changing visibility after publication requires a new version like any other content change.

​
When the built artifact is missing

With nothing to ship, the registry MUST NOT be contacted.
  • Interactive contexts MAY offer to build the current source and, on acceptance, verify and upload the result.
  • Non-interactive contexts MUST NOT prompt and MUST fail with guidance to build first.

​
When the built artifact has drifted from source

When the archive’s embedded manifest disagrees with the current source, implementations MUST distinguish two classes: Content drift: same name and version, different content. Either resolution uploads to the same address. Identity drift: a different name or version. Uploads always address the artifact’s embedded identity, so publishing the existing artifact ships it under its own name and version, and collides with immutability if that identity already exists. Interactive contexts MAY offer to rebuild, to publish the existing artifact, or to cancel. Non-interactive contexts MUST NOT prompt: both classes warn and upload the existing artifact unchanged.

​
Build against publish

Neither step modifies the facet manifest.

​
Not in publish

  • MCP server declarations. A declaration is manifest content. It is never independently published, versioned, resolved, or fetched: there is no server registry and no standalone server artifact. Publish never contacts or launches a declared server.
  • Lockfile generation. The lockfile is an install-time artifact.