@malloy-publisher/server 0.10.6 → 0.11.0

package/dist/app/api-doc.yaml

@@ -30,6 +30,7 @@ info:
     └── Environments
         ├── Connections               schemas, tables, and ad-hoc SQL
         └── Packages
+            ├── Versions              published, immutable versions and `latest`
             ├── Models                query and compile
             ├── Notebooks             execute a cell at a time
             ├── Data Apps             static HTML data apps from public/
@@ -93,6 +94,10 @@ tags:
     description: Real-time file watching for development workflows
   - name: materializations
     description: Package-level materializations for persisting Malloy sources
+  - name: versions
+    description:
+      Published, immutable versions of a package, the package's `latest`
+      pointer, and each version's lifecycle (archive, manifest binding)
   - name: storage-destinations
     description: |
       Table lifecycle inside an environment's storage destinations, for an
@@ -1041,6 +1046,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of schemas available in the connection with metadata
@@ -1050,10 +1056,14 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Schema"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "424":
@@ -1107,6 +1117,7 @@ paths:
             type: array
             items:
               type: string
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of table names available in the specified schema
@@ -1116,10 +1127,14 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Table"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "424":
@@ -1169,6 +1184,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/PathPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: Table information
@@ -1182,6 +1198,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/ConnectionUnavailable"
         "500":
@@ -1219,6 +1237,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       requestBody:
         description: SQL statement to fetch the SQL source
         required: true
@@ -1242,6 +1261,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/ConnectionUnavailable"
         "500":
@@ -1282,6 +1303,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       requestBody:
         description: SQL statement to execute
         required: true
@@ -1326,6 +1348,8 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "413":
           $ref: "#/components/responses/PayloadTooLarge"
         "424":
@@ -1367,6 +1391,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       requestBody:
         description: SQL statement to create the temporary table
         required: true
@@ -1390,6 +1415,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/ConnectionUnavailable"
         "500":
@@ -1417,6 +1444,10 @@ paths:
         This endpoint does not reload. A `reload` query parameter is rejected with 400 rather
         than ignored, because answering 200 here reads as a reload that worked. Reload is
         per-package: use `GET /environments/{environmentName}/packages/{packageName}?reload=true`.
+
+        A package with published versions is listed once, as its `latest` version. A
+        `versionId` other than empty or `latest` is rejected with 400: read one
+        version with `GET /environments/{environmentName}/packages/{packageName}?versionId=`.
       parameters:
         - name: environmentName
           in: path
@@ -1439,8 +1470,6 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
     post:
@@ -1452,6 +1481,50 @@ paths:
         Creates a new Malloy package within the specified environment. A package serves as a
         container for models, notebooks, embedded databases, and other resources. The package
         will be initialized with the provided metadata and can immediately accept content.
+
+        ## Versioned publish
+
+        Package versioning is a server setting, `PUBLISHER_PACKAGE_VERSIONING` (`off` by
+        default; `ServerStatus.packageVersioning` reports it), and a transition: a later release
+        removes the setting and always publishes versions.
+
+        With it off, a request that carries a `location` installs the package in place,
+        replacing the previous publish, as before versions, whatever its `publisher.json`
+        declares; the package has no versions, and the server logs a warning that names it. A
+        package that already has published versions refuses that with 409 (`reason`
+        `PACKAGE_IS_VERSIONED`).
+
+        With it on, a request that carries a `location` publishes an immutable version of the
+        package: the one its own `publisher.json` declares. The request takes no version
+        parameter: the version is that field, the way `npm publish` reads `package.json`, so
+        bumping it is the release action.
+
+        - A `publisher.json` with no `version` is refused with 400 (`reason`
+          `MANIFEST_VERSION_MISSING`), and one whose `version` is not a semantic version with
+          400 (`reason` `MANIFEST_VERSION_INVALID`). Nothing is written.
+        - Publishing a version the package already has, with different content, is refused with
+          409 (`reason` `VERSION_CONFLICT`). The same content again succeeds and writes no
+          files, so re-loading a version onto a server that already holds it is safe to retry;
+          a non-null `manifestLocation` on that request binds the version to it. A re-load
+          leaves `latest` where it is, so a retried publish never undoes a rollback; it sets
+          `latest` only for a package that has none. Re-publishing an archived version is
+          refused with 410 (`reason`
+          `VERSION_ARCHIVED`): unarchive it instead.
+        - A version that does not pass the publish checks (the same ones an unversioned publish
+          applies) is refused with 400, and the versions already published keep serving.
+        - Under `versionPromotion: "on-publish"` (the default), the new version becomes the
+          package's `latest` unless a higher version already is. Under `"explicit"`, publish
+          never moves `latest`; `PUT .../packages/{packageName}/latest` does.
+        - A package mounted for watch mode is the author's own source directory, so it cannot
+          hold immutable versions: publishing a version of it is refused with 400.
+        - The request's `description`, when sent, is the package's description. Each version
+          keeps the `description` from its own publisher.json.
+
+        A request without a `location` registers a directory already in the environment as a
+        single unversioned package, as packages loaded from `publisher.config.json` are with
+        versioning off. A
+        package that already has versions refuses that with 409 (`reason`
+        `PACKAGE_IS_VERSIONED`).
       parameters:
         - name: environmentName
           in: path
@@ -1476,12 +1549,14 @@ paths:
           $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/PackageManifestError"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -1494,8 +1569,9 @@ paths:
       description: |
         Retrieves detailed information about a specific package, including its models, notebooks,
         databases, and metadata. The reload parameter can be used to refresh the package state
-        from disk before returning the information. The versionId parameter allows access to
-        specific package versions.
+        from disk before returning the information. The versionId parameter selects one
+        published version of a versioned package; without it, the package's `latest` version
+        is returned.
       parameters:
         - name: environmentName
           in: path
@@ -1509,12 +1585,7 @@ paths:
           required: true
           schema:
             type: string
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
         - name: reload
           in: query
           description: |
@@ -1524,6 +1595,10 @@ paths:
             `true` and `false`. Any other value (`1`, `yes`, `TRUE`, or the
             parameter repeated) is refused with 400 rather than read as `false`,
             which would answer 200 without recompiling.
+
+            A published version is immutable, so it has nothing to reload: on a
+            versioned package `reload=true` returns the version as it is,
+            neither recompiling nor re-fetching it.
           required: false
           schema:
             type: boolean
@@ -1540,12 +1615,12 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/PackageManifestError"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
     patch:
@@ -1553,7 +1628,24 @@ paths:
         - packages
       operationId: update-package
       summary: Update package configuration
+      deprecated: true
       description: |
+        DEPRECATED. In-place mutation of a package contradicts immutable versions, so this
+        operation will be removed. On a package that has published versions it changes only
+        what is not content: a `manifestLocation` URI is bound to the package's `latest` version
+        (as `PUT .../packages/{packageName}/versions/{version}/manifest` does for any version),
+        while a null or empty one leaves the binding as it is (clear it with that route), and
+        `description` is the package's. `name` and the `location` the version was published from
+        may be sent back unchanged. Any other change is refused with 409 (`reason`
+        `PACKAGE_IS_VERSIONED`), as is a package with no `latest` yet: publish a new version to
+        change content.
+
+        It keeps working, so that callers which predate versions do not break, and says it is
+        deprecated: every response carries `Deprecation: true` and a `Link` to the package
+        versions reference, every request is counted in `publisher_deprecated_usage_total`
+        (`feature` `package_patch`), and the server logs a warning, once per package per run,
+        naming the route that replaces it.
+
         Updates the configuration and metadata of an existing package. This allows you to
         modify package settings, update the description, change the location, or update other
         package-level properties. The package must exist and be accessible.
@@ -1604,10 +1696,10 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
     delete:
@@ -1619,6 +1711,13 @@ paths:
         Permanently deletes a package and all its associated resources including models,
         notebooks, databases, and metadata. This operation cannot be undone, so use with caution.
         The package must exist and be accessible for deletion.
+
+        On a versioned package this deletes every published version and its files, then, in the
+        background, cleans up each version as deleting it alone does: its own auto-runs still
+        running are stopped and its own `scope: version` tables reclaimed. To take one
+        version out of service while keeping the rest, archive it with
+        `PATCH .../packages/{packageName}/versions/{version}`; to remove one version for good,
+        delete it with `DELETE .../packages/{packageName}/versions/{version}`.
       parameters:
         - name: environmentName
           in: path
@@ -1645,8 +1744,295 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/versions:
+    get:
+      tags:
+        - versions
+      operationId: list-package-versions
+      summary: List a package's published versions
+      description: |
+        Lists every version published to the package, highest version first, including archived
+        ones (marked by `archiveStatus`). The entry marked `latest` is the version served when a
+        request names no `versionId`. An unversioned package (one registered from a directory,
+        or loaded from `publisher.config.json` or published with versioning off) has no versions
+        and returns an empty list.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+      responses:
+        "200":
+          description: The package's versions, highest first
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PackageVersion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/versions/{version}:
+    get:
+      tags:
+        - versions
+      operationId: get-package-version
+      summary: Get one published version
+      description: |
+        Returns one published version, archived or not. An unknown version answers 404 with
+        `reason` `VERSION_NOT_FOUND`.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/versionPath"
+      responses:
+        "200":
+          description: The version
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PackageVersion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    patch:
+      tags:
+        - versions
+      operationId: update-package-version
+      summary: Archive or unarchive a version
+      description: |
+        Changes a version's lifecycle state. Content is never edited here: a published version
+        is immutable.
+
+        - `archive` takes the version out of service: reads and queries that name it answer 410
+          with `reason` `VERSION_ARCHIVED`, and it is unloaded from memory. The tables its own
+          auto-runs built under `scope: version` are reclaimed in the background, with their run
+          records; tables another version's run still references are kept, and so are an
+          orchestrated run's, whose names and lifetime the caller that assigned them owns. Each
+          table is tried once: one that cannot be dropped is left, and its run record goes all
+          the same. Its
+          files stay on disk, so it can be unarchived. To remove them, delete the version with
+          `DELETE .../versions/{version}`.
+        - `unarchive` puts it back in service. It loads again on its next read, and serves live
+          until it is built again.
+
+        Archiving stops the version's materialization schedule, if it has one, and unarchiving
+        starts it again. An archive is refused with 409 when:
+
+        - the version is the package's `latest` (`reason` `VERSION_IS_LATEST`): move `latest`
+          first;
+        - it is the package's last version in service (`reason` `VERSION_IS_LAST_ACTIVE`): a
+          package always keeps one. To take the whole package out of service, delete it;
+        - a materialization of that version is running (`reason` `VERSION_BUILDING`), since the
+          archive would reclaim the tables that run is writing. A run that starts after the
+          archive fails, and what it built is reclaimed when it ends.
+
+        Sending the state the version is already in changes nothing and answers 200.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/versionPath"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PackageVersionUpdate"
+      responses:
+        "200":
+          description: The version after the change
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PackageVersion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    delete:
+      tags:
+        - versions
+      operationId: delete-package-version
+      summary: Delete a version
+      description: |
+        Removes one version for good, where an archive only takes it out of service. The version
+        is unloaded from memory, and its row and its files are deleted; other versions are
+        untouched. Then, in the background, its own auto-runs still running are stopped and the tables
+        its own auto-runs built under `scope: version` are reclaimed with their run records, as an
+        archive reclaims them. Nothing is dropped before the delete commits, so a refused delete
+        changes nothing. It cannot be undone, and it frees the version id: a later publish of the
+        same version is a new version, with whatever content it carries.
+
+        An archived version can be deleted too; that is how its files are reclaimed. Deleting the
+        package's only version deletes the package with it (its row, run records and ledger), so
+        no package is left with no version; while a publish of another version of the package is
+        running, the package is left to that publish.
+
+        Each table is tried once: one that could not be dropped is left. Tables another run of the
+        package still references are kept, as is an orchestrated run (its tables, and a build of it
+        still running), which the caller that instructed it owns.
+
+        A delete is refused with 409 when:
+
+        - the version is the package's `latest` and other versions remain (`reason`
+          `VERSION_IS_LATEST`): move `latest` first;
+        - it is the package's last version in service and archived versions remain (`reason`
+          `VERSION_IS_LAST_ACTIVE`): a package that has versions always keeps one in service.
+          Delete the archived versions first, or delete the package.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/versionPath"
+      responses:
+        "200":
+          description: The version deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PackageVersion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/versions/{version}/manifest:
+    put:
+      tags:
+        - versions
+      operationId: set-package-version-manifest
+      summary: Bind a version to a build manifest
+      description: |
+        Sets the version's `manifestLocation`, the externally computed build manifest its persist
+        references resolve through, and rebinds that version's models to it right away. A null
+        `manifestLocation` clears the binding and the version serves live. Only this version is
+        affected.
+
+        This is serving state, not package content, which is why it is the one thing about a
+        published version that can change. It replaces the deprecated
+        `PATCH .../packages/{packageName}` for rebinding a manifest.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/versionPath"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PackageVersionManifest"
+      responses:
+        "200":
+          description: >-
+            The version as a package resource (`versionId` set), which is where
+            the binding's outcome is reported: `manifestBindingStatus`,
+            `manifestEntryCount` and `boundManifestUri`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Package"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
+        "424":
+          $ref: "#/components/responses/PackageManifestError"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/latest:
+    put:
+      tags:
+        - versions
+      operationId: set-package-latest-version
+      summary: Point the package's latest at a version
+      description: |
+        Makes the named version the package's `latest`: the version served to every request that
+        names no `versionId`. Nothing is rebuilt or re-fetched; the pointer moves. Pointing it at
+        an earlier version is a rollback, and the next publish still moves `latest` under
+        `versionPromotion: "on-publish"`.
+
+        This is the only way `latest` moves when the server runs with
+        `versionPromotion: "explicit"`, the mode for an orchestrator that decides when a
+        version is ready to serve.
+
+        The version must exist and must not be archived (404 `VERSION_NOT_FOUND`, 410
+        `VERSION_ARCHIVED`), and it is loaded before the pointer moves: a version that fails to
+        load is refused with that load's error, and `latest` stays where it was.
+      parameters:
+        - $ref: "#/components/parameters/environmentName"
+        - $ref: "#/components/parameters/packageName"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PackageLatestVersion"
+      responses:
+        "200":
+          description: The version that is now latest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PackageVersion"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
+        "424":
+          $ref: "#/components/responses/PackageManifestError"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -1680,12 +2066,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
         - $ref: "#/components/parameters/includeHiddenFilesAndSources"
       responses:
         "200":
@@ -1696,14 +2077,16 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Model"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -1748,12 +2131,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/PathPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
         - $ref: "#/components/parameters/includeHiddenFilesAndSources"
       responses:
         "200":
@@ -1762,16 +2140,18 @@ paths:
             "application/json":
               schema:
                 $ref: "#/components/schemas/CompiledModel"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/ModelCompilationError"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
     put:
       tags:
         - models
@@ -1837,6 +2217,12 @@ paths:
         Refused with 403 when `publisher.config.json` has `frozenConfig: true`.
         Like every write on this server, it is unauthenticated and meant to sit
         behind an authenticating gateway; see docs/security-posture.md.
+
+        A published version is immutable, so a package with versions refuses
+        this write with 409 (`reason` `PACKAGE_IS_VERSIONED`), whatever
+        `versionId` names: change the file in the package's source and publish
+        a new version. A `versionId` on a package with no versions answers 404
+        (`reason` `VERSION_NOT_FOUND`).
       parameters:
         - name: environmentName
           in: path
@@ -1856,12 +2242,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/PathPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       requestBody:
         required: true
         content:
@@ -1899,8 +2280,6 @@ paths:
                 $ref: "#/components/schemas/Error"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -1935,7 +2314,7 @@ paths:
           description: Name of the package
           required: true
           schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+            type: string
         - name: path
           in: path
           description: Path to the model within the package
@@ -1964,12 +2343,12 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "413":
           $ref: "#/components/responses/PayloadTooLarge"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "424":
           $ref: "#/components/responses/ConnectionUnavailable"
         "502":
@@ -2041,6 +2420,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/PathPattern"
+        - $ref: "#/components/parameters/versionId"
       requestBody:
         required: true
         content:
@@ -2060,6 +2440,8 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "424":
           $ref: "#/components/responses/PackageManifestError"
         "500":
@@ -2113,12 +2495,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The reports in the package
@@ -2128,14 +2505,16 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Report"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2176,12 +2555,7 @@ paths:
           required: true
           schema:
             type: string
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The report manifest
@@ -2189,14 +2563,16 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ReportManifest"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2236,6 +2612,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The skills in force for the package
@@ -2245,10 +2622,14 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/SkillSummary"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -2289,6 +2670,7 @@ paths:
           required: true
           schema:
             type: string
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The skill and its body
@@ -2296,10 +2678,14 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Skill"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -2331,6 +2717,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The agents the package declares
@@ -2340,10 +2727,14 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/AgentSummary"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -2401,6 +2792,7 @@ paths:
             type: string
             enum: [full, summary]
             default: full
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The resolved agent
@@ -2414,6 +2806,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -2466,6 +2860,7 @@ paths:
           required: true
           schema:
             type: string
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The skill file
@@ -2473,10 +2868,14 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/AgentSkillRead"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -2544,12 +2943,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of dashboards in the package
@@ -2559,14 +2953,16 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Dashboard"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2622,12 +3018,7 @@ paths:
           schema:
             type: string
             minLength: 1
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: The dashboard manifest
@@ -2635,6 +3026,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DashboardManifest"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
@@ -2647,10 +3040,10 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2686,12 +3079,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of notebooks in the package
@@ -2701,14 +3089,16 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Notebook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2745,12 +3135,7 @@ paths:
           required: true
           schema:
             type: string
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A Malloy notebook with raw cell contents.
@@ -2758,14 +3143,16 @@ paths:
             "application/json":
               schema:
                 $ref: "#/components/schemas/RawNotebook"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
 
   /environments/{environmentName}/packages/{packageName}/notebooks/{path}/cells/{cellIndex}:
     get:
@@ -2818,12 +3205,7 @@ paths:
           required: true
           schema:
             type: integer
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
         - name: filter_params
           in: query
           deprecated: true
@@ -2876,12 +3258,12 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "413":
           $ref: "#/components/responses/PayloadTooLarge"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "424":
           $ref: "#/components/responses/ConnectionUnavailable"
         "502":
@@ -2914,12 +3296,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of embedded databases in the package
@@ -2929,14 +3306,16 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Database"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -2969,6 +3348,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: A list of data apps in the package
@@ -2984,10 +3364,10 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
@@ -3013,6 +3393,11 @@ paths:
             package changes.
           - periodic `: heartbeat` comments to keep idle proxies from closing
             the connection.
+
+        `versionId` is accepted so a data app can send it on every call, but a
+        published version never changes: its stream carries `hello`, `mode` and
+        heartbeats and no `changed` event. Watch mode only ever mounts
+        unversioned packages.
       parameters:
         - name: environmentName
           in: path
@@ -3026,6 +3411,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: An open Server-Sent Events stream of change events
@@ -3040,6 +3426,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
         "500":
           $ref: "#/components/responses/InternalServerError"
         "503":
@@ -3194,6 +3582,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Materialization"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "404":
           $ref: "#/components/responses/NotFound"
         "409":
@@ -3202,14 +3592,18 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "410":
+          $ref: "#/components/responses/Gone"
     get:
       tags:
         - materializations
       operationId: list-materializations
       summary: List materializations for a package
-      description:
+      description: >-
         Returns the materialization history for the package, ordered by
-        most recent first.
+        most recent first. For a package with published versions, the runs of
+        one version (the one `versionId` names, or `latest`), together with
+        the runs from before the package's first versioned publish.
       parameters:
         - $ref: "#/components/parameters/environmentName"
         - $ref: "#/components/parameters/packageName"
@@ -3227,6 +3621,7 @@ paths:
             type: integer
             minimum: 0
           description: Number of materializations to skip
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: List of materializations
@@ -3236,8 +3631,12 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Materialization"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
 
   /environments/{environmentName}/packages/{packageName}/materializations/{materializationId}:
     get:
@@ -3245,10 +3644,16 @@ paths:
         - materializations
       operationId: get-materialization
       summary: Get a specific materialization
+      description: >-
+        A run's id is unique, so with no `versionId` the run is found whichever
+        version built it. Naming a version also requires the run to be that
+        version's (or one from before the package's first versioned publish);
+        the same holds for stopping and deleting a run.
       parameters:
         - $ref: "#/components/parameters/environmentName"
         - $ref: "#/components/parameters/packageName"
         - $ref: "#/components/parameters/materializationId"
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: Materialization details
@@ -3256,8 +3661,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Materialization"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "404":
           $ref: "#/components/responses/NotFound"
+        "410":
+          $ref: "#/components/responses/Gone"
     post:
       tags:
         - materializations
@@ -3279,6 +3688,7 @@ paths:
             enum:
               - stop
           description: Action to perform on the materialization
+        - $ref: "#/components/parameters/versionId"
       responses:
         "200":
           description: Materialization cancelled (action=stop)
@@ -3296,6 +3706,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "410":
+          $ref: "#/components/responses/Gone"
     delete:
       tags:
         - materializations
@@ -3325,6 +3737,7 @@ paths:
           schema:
             type: boolean
             default: false
+        - $ref: "#/components/parameters/versionId"
       responses:
         "204":
           description: Materialization deleted
@@ -3338,6 +3751,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "410":
+          $ref: "#/components/responses/Gone"
 
   /environments/{environmentName}/storageDestinations/{destinationName}/schemas/{schemaName}/tables:
     get:
@@ -3497,14 +3912,38 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    InternalServerError:
-      description: The server encountered an internal error
+    Conflict:
+      description: |
+        The request conflicts with the package's current state. `reason` says
+        which conflict:
+          * VERSION_CONFLICT: the version is already published with different
+            content. Bump the `version` in publisher.json and publish again.
+          * PACKAGE_IS_VERSIONED: the package has published versions, which are
+            immutable, so it cannot be changed in place.
+          * VERSION_IS_LATEST: the version is the package's `latest` and cannot
+            be archived, or deleted while other versions remain. Move `latest` first.
+          * VERSION_IS_LAST_ACTIVE: the version is the package's last one in
+            service and cannot be archived, or deleted while archived versions
+            remain. Delete the package instead.
+          * VERSION_BUILDING: a materialization of the version is running, and
+            archiving or deleting it would drop the tables it is writing. Wait for
+            it, or stop it.
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
-    NotImplemented:
-      description: The requested operation is not implemented
+    Gone:
+      description: |
+        The version the request names (by `versionId`, the path, or the
+        publisher.json of the tree being published) has been archived
+        (`reason` VERSION_ARCHIVED). It is out of service until it is
+        unarchived; the package's other versions are unaffected.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    InternalServerError:
+      description: The server encountered an internal error
       content:
         application/json:
           schema:
@@ -3668,8 +4107,168 @@ components:
 
     VersionIdPattern:
       type: string
-      pattern: "^[a-zA-Z0-9_.-]+$"
-      description: Version identifier pattern supporting dots and dashes
+      pattern: '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$'
+      description: >-
+        A package version: a semantic version (SemVer 2.0), MAJOR.MINOR.PATCH
+        with an optional pre-release suffix (`-rc1`, `-alpha.2`) and optional
+        build metadata (`+20231120.deadbeef`). Pre-release and
+        build suffixes are accepted so release-candidate builds can be
+        published. A numeric identifier may have leading zeros (`01.0.0`),
+        which strict SemVer 2.0 does not allow, so a version a system in front
+        of Publisher validated with this same pattern is never refused. Such a
+        version compares equal to the one without the zeros, and a package
+        holds only one of the two: publishing the other is 409
+        `VERSION_CONFLICT`.
+
+    PackageVersion:
+      type: object
+      description: >-
+        One published version of a package. Its content is immutable; what
+        changes over its life is its lifecycle state (`archiveStatus`), whether
+        it is the package's `latest`, and the build manifest it is bound to.
+      required:
+        - resource
+        - packageName
+        - id
+        - latest
+        - archiveStatus
+        - archivedAt
+        - promotedAt
+        - demotedAt
+        - contentHash
+        - manifestLocation
+        - gitCommitSha
+        - gitRef
+        - createdAt
+        - updatedAt
+      properties:
+        resource:
+          type: string
+          readOnly: true
+          description: Resource path to the version
+        packageName:
+          type: string
+          readOnly: true
+          description: The package this version belongs to
+        id:
+          $ref: "#/components/schemas/VersionIdPattern"
+          description: >-
+            The version, from the package's publisher.json: the value a
+            `versionId` names everywhere else.
+        latest:
+          type: boolean
+          readOnly: true
+          description: >-
+            Whether this is the package's `latest` version, the one served when a
+            request names no `versionId`.
+        archiveStatus:
+          type: string
+          readOnly: true
+          enum: [archive, unarchive]
+          description: >-
+            `unarchive` while the version is in service; `archive` once it has
+            been taken out of service (reads that name it answer 410). Each
+            value is named for the action that sets it.
+        archivedAt:
+          type: ["string", "null"]
+          format: date-time
+          readOnly: true
+          description: When the version was archived; null while it is in service.
+        promotedAt:
+          type: ["string", "null"]
+          format: date-time
+          readOnly: true
+          description: >-
+            When the version last became the package's `latest`; null if it
+            never has.
+        demotedAt:
+          type: ["string", "null"]
+          format: date-time
+          readOnly: true
+          description: >-
+            When the version last stopped being the package's `latest`; null if
+            it never has.
+        description:
+          type: string
+          readOnly: true
+          description: The `description` from the version's publisher.json
+        location:
+          type: string
+          readOnly: true
+          description: >-
+            Where the version was published from. A version whose files are
+            missing on disk is fetched again from here, and checked against
+            `contentHash` before it is served.
+        contentHash:
+          type: string
+          readOnly: true
+          description: >-
+            SHA-256 (hex) over the version's files. Publishing the same version
+            with the same content again succeeds and changes nothing; with
+            different content it is refused with 409 VERSION_CONFLICT.
+        manifestLocation:
+          type: ["string", "null"]
+          readOnly: true
+          description: >-
+            The build manifest this version is bound to (see
+            `Package.manifestLocation`); null when it serves live. Set with
+            `PUT .../versions/{version}/manifest`.
+        gitCommitSha:
+          type: ["string", "null"]
+          readOnly: true
+          description: >-
+            Git commit the version was published from, when the publisher
+            recorded it. Reserved: nothing records it yet.
+        gitRef:
+          type: ["string", "null"]
+          readOnly: true
+          description: Git ref the version was published from. Reserved, like `gitCommitSha`.
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the version was published
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the version's lifecycle state or binding last changed
+
+    PackageVersionUpdate:
+      type: object
+      description: A lifecycle change to a published version
+      properties:
+        archiveStatus:
+          type: string
+          enum: [archive, unarchive]
+          description: >-
+            `archive` takes the version out of service; `unarchive` puts it back.
+      required:
+        - archiveStatus
+
+    PackageVersionManifest:
+      type: object
+      description: The build manifest to bind a published version to
+      properties:
+        manifestLocation:
+          type: ["string", "null"]
+          minLength: 1
+          description: >-
+            Where the build manifest to bind is: a gs:// or s3:// URI, a
+            file:// URL, or an absolute path on this server (a mounted volume).
+            Null clears the binding and serves live. An empty string or a
+            relative path is refused with 400.
+      required:
+        - manifestLocation
+
+    PackageLatestVersion:
+      type: object
+      description: The version to make the package's `latest`
+      properties:
+        version:
+          $ref: "#/components/schemas/VersionIdPattern"
+      required:
+        - version
 
     PathPattern:
       type: string
@@ -3685,7 +4284,17 @@ components:
           description: Unix timestamp of the status check
         environments:
           type: array
-          description: List of available environments
+          description: >-
+            List of available environments. Each environment's `packages` lists
+            one entry per package, as `GET .../packages` does, except that a
+            versioned package is listed once for EVERY version this server holds,
+            each entry with its own `versionId`, `archiveStatus` and `loaded`. A
+            loaded version's entry also carries its manifest binding
+            (`manifestBindingStatus`, `boundManifestUri`); an unloaded one (an
+            archived version, or one not loaded since the server started) carries only
+            its name and version. An orchestrator reconciles what a server holds
+            from this list, so it names every version rather than only `latest`
+            or only what is in memory; `resource` keeps its shape.
           items:
             $ref: "#/components/schemas/Environment"
         initialized:
@@ -3711,6 +4320,25 @@ components:
             This server's release version, for example "0.8.2". Use it to tell
             which build answered, for instance to rule out an old copy served
             from the npx cache.
+        packageVersioning:
+          type: string
+          enum: ["off", "on"]
+          readOnly: true
+          description: >-
+            "on" when a publish from a location publishes an immutable
+            version (`PUBLISHER_PACKAGE_VERSIONING=on`); "off" when it installs
+            the package in place, as before versions. Reads and the versions
+            routes answer in both. Absent from a server that predates
+            versions, which reads as "off": how an orchestrator talking to
+            servers mid-rollout tells which ones publish native versions.
+        versionPromotion:
+          type: string
+          enum: ["on-publish", "explicit"]
+          readOnly: true
+          description: >-
+            The `versionPromotion` setting this server runs with. With
+            "explicit", a publish never moves a package's `latest`; only
+            `PUT .../packages/{packageName}/latest` does.
         emptyReason:
           type: string
           readOnly: true
@@ -4037,6 +4665,47 @@ components:
         name:
           type: string
           description: Package name
+        versionId:
+          oneOf:
+            - $ref: "#/components/schemas/VersionIdPattern"
+            - type: "null"
+          readOnly: true
+          description: >-
+            The published version this response describes. Absent for a package
+            that has no published versions. A request that names no `versionId`
+            is answered with the package's `latest` version, so this is how a
+            caller learns which version it got. In a package listing it is null
+            for a package none of whose versions is `latest` yet (under
+            `versionPromotion: explicit`, before `PUT .../latest`). Set from the
+            version's publisher.json at publish; never sent by a client.
+        latestVersion:
+          oneOf:
+            - $ref: "#/components/schemas/VersionIdPattern"
+            - type: "null"
+          readOnly: true
+          description: >-
+            The package's `latest` version. Absent for a package that has no
+            published versions, and null while none of its versions is `latest`.
+            Equal to `versionId` unless the request named another one.
+        loaded:
+          type: boolean
+          readOnly: true
+          description: >-
+            Set only on a version's entry in `GET /status`: whether this server
+            holds the version in memory. A published version that is not loaded
+            (an archived one, or one not loaded since the server started) is still
+            held, so it is still listed, with `loaded: false` and only its
+            `resource`, name, version, `latestVersion`, `archiveStatus` and
+            `status`. It loads when a request next names it. A version still
+            being published is listed only under `includeLoading`, with
+            `loaded: false`, no `archiveStatus`, and `status.loading`.
+        archiveStatus:
+          type: string
+          enum: [archive, unarchive]
+          readOnly: true
+          description: >-
+            Set only on a version's entry in `GET /status`, except one still
+            being published: whether the version is archived.
         description:
           type: string
           description: Package description
@@ -4394,9 +5063,12 @@ components:
         manifestLocation:
           type: ["string", "null"]
           description: |
-            URI (gs:// or s3://) of the externally-computed manifest for this package.
-            On (re)load the publisher reads it and binds persist references
-            (sourceEntityId -> physicalTableName). Null = serve live.
+            Where the externally-computed manifest for this package is: a gs://
+            or s3:// URI, a file:// URL, or an absolute path on this server (a
+            mounted volume). On (re)load the publisher reads it and binds
+            persist references (sourceEntityId -> physicalTableName). Null =
+            serve live. For a package with published versions, a relative path
+            is refused with 400.
         queryMetadata:
           oneOf:
             - $ref: "#/components/schemas/QueryMetadata"
@@ -4536,6 +5208,12 @@ components:
             `loadingSince` is when the in-progress load began, so a caller can
             bound one that never completes. Which tables a serving copy answers
             from is a separate question, answered by `manifestBindingStatus`.
+            A publish of a package version is a load from its download until
+            it settles, and while it runs every entry of that package reports
+            `loading`. With `includeLoading=true`, once its tree has named the
+            version, a version the package does not hold yet is listed as its
+            own entry, with its `versionId`, `loaded: false` and `loading`,
+            unless an unversioned copy of the package still serves.
 
             A package that is loading for the first time, so is not yet
             serving, is listed only where a caller asks for it:
@@ -4707,6 +5385,30 @@ components:
             The task file's Markdown. Only on the resolved agent, not the
             listing.
 
+    AgentBudget:
+      type: object
+      readOnly: true
+      description: >-
+        The run limits an agent declares. Validated and exposed only: the
+        server never enforces them. A platform that runs the agent decides
+        how to apply them and may clamp each to its own maximum. Every field
+        is optional and only the fields the manifest sets are present; an
+        unset field keeps the platform's default. Absent when the manifest
+        sets none.
+      properties:
+        turns:
+          type: integer
+          minimum: 1
+        wall_clock_minutes:
+          type: integer
+          minimum: 1
+        llm_tokens:
+          type: integer
+          minimum: 1
+        job_minutes:
+          type: integer
+          minimum: 1
+
     AgentSummary:
       type: object
       readOnly: true
@@ -4724,6 +5426,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgentSchedule"
+        budget:
+          $ref: "#/components/schemas/AgentBudget"
 
     AgentSkillFile:
       type: object
@@ -4777,6 +5481,12 @@ components:
           type: string
         package:
           type: string
+        versionId:
+          $ref: "#/components/schemas/VersionIdPattern"
+          description: >-
+            The published version the definition was read from. Absent for a
+            package that has no published versions. Pass it as `?versionId=`
+            to fetch the same definition again after `latest` moves.
         sourceContentSha:
           type: string
           description: The package's `sourceContentSha` at the load this definition came from.
@@ -4816,6 +5526,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgentSchedule"
+        budget:
+          $ref: "#/components/schemas/AgentBudget"
         warnings:
           type: array
           items:
@@ -5472,6 +6184,22 @@ components:
         packageName:
           type: string
           description: Name of the package containing this data app
+        versionId:
+          oneOf:
+            - $ref: "#/components/schemas/VersionIdPattern"
+            - type: "null"
+          readOnly: true
+          description: >-
+            The published version this data app was listed from. Absent for a
+            package that has no published versions. A link that must keep opening
+            this version after `latest` moves carries it as `?versionId=`, as
+            `resource` does. The static route serving the page reads it only
+            when it names a version the package has: otherwise (a package with
+            no versions, or a `versionId` that is no version of this package)
+            it serves the files of `latest`, so a router that forwards a page's
+            query string unchanged keeps working. The page's queries, through
+            the data-app runtime, follow the same rule. Files the page loads by
+            relative URL carry no `?versionId=`, so they come from `latest`.
         path:
           type: string
           description: Relative path to the HTML file within its package directory
@@ -6141,7 +6869,15 @@ components:
             result with type metadata for rendering.'
         versionId:
           type: string
-          description: Version ID
+          description: >-
+            The published version of the package to query. `latest`, omitted or
+            empty, the query runs against the package's `latest` version. An unknown version
+            answers 404 (`reason` VERSION_NOT_FOUND) and an archived one 410
+            (`reason` VERSION_ARCHIVED). A `versionId` in the request's query
+            string, as a proxy forwarding a page's URL sends, is read the same way;
+            when both name a version they must agree, or the request answers 400.
+            It is not declared as a query parameter, so generated clients keep
+            their argument order.
         filterParams:
           type: object
           deprecated: true
@@ -7560,8 +8296,39 @@ components:
             client generated before it -- on the one field whose purpose is to
             grow. Callers must treat an unrecognized value as absent.
 
+            The package-version values let a caller tell "forgot to bump the
+            version" from "the model is broken", which share a status code:
+
+              * MANIFEST_VERSION_MISSING (400): with package versioning on, a
+                publish whose publisher.json has no `version`.
+              * MANIFEST_VERSION_INVALID (400): such a publish whose `version`
+                is not a semantic version.
+              * VERSION_CONFLICT (409): that version is already published with
+                different content.
+              * PACKAGE_IS_VERSIONED (409): the package has published versions,
+                so it cannot be changed in place (a write, or a publish with
+                package versioning off).
+              * VERSION_IS_LATEST (409): the package's `latest` version cannot be
+                archived, or deleted while other versions remain.
+              * VERSION_IS_LAST_ACTIVE (409): the package's last version in
+                service cannot be archived, or deleted while archived versions
+                remain.
+              * VERSION_BUILDING (409): a materialization of the version is
+                running, so it cannot be archived or deleted yet.
+              * VERSION_ID_INVALID (400): a requested `versionId` is not a
+                semantic version.
+              * VERSION_NOT_LATEST (400): an auto-run of a version other than
+                `latest`, in a package whose versions share their tables. A
+                package with no `latest` yet refuses none.
+              * VERSION_NOT_FOUND (404): the package has no such version.
+              * VERSION_ARCHIVED (410): the version is archived.
+
             Known values: TABLE_NOT_FOUND, CONNECTION_FAILED,
-            CONNECTION_AUTH_FAILED, CONNECTION_NOT_FOUND.
+            CONNECTION_AUTH_FAILED, CONNECTION_NOT_FOUND,
+            MANIFEST_VERSION_MISSING, MANIFEST_VERSION_INVALID,
+            VERSION_CONFLICT, PACKAGE_IS_VERSIONED, VERSION_IS_LATEST,
+            VERSION_IS_LAST_ACTIVE, VERSION_BUILDING, VERSION_ID_INVALID,
+            VERSION_NOT_LATEST, VERSION_NOT_FOUND, VERSION_ARCHIVED.
         problems:
           type: array
           description: |
@@ -7860,6 +8627,38 @@ components:
         caller-assigned names from the package's already-compiled build plan
         (read off `Package.buildPlan`).
       properties:
+        versionId:
+          type: string
+          description: >-
+            The published version of the package to build. `latest`, omitted or
+            empty, the package's `latest` version is built. An unknown version answers 404
+            (`reason` VERSION_NOT_FOUND) and an archived one 410 (`reason`
+            VERSION_ARCHIVED). Carried in the body rather than the query string
+            because the body is optional: a new optional query parameter ahead
+            of it would move the body argument of every generated client.
+
+            The run records the version it built in `metadata.versionId`, with
+            the package's materialization scope in `metadata.scope`, which
+            decides whose tables it builds. Under `scope: "version"` each
+            version builds into tables of its own: a self-assigned name gains
+            the version and a hash of the environment, package and version as
+            a suffix (`order_summary__v1_2_0_3f9c2a1b`), so no other package's
+            version builds the same table. Under
+            `scope: "package"` (the default) the versions share the package's
+            tables, so an auto-run (no `buildInstructions`) of a version other
+            than `latest` is refused with 400 (`reason` VERSION_NOT_LATEST): it
+            would rebuild the table `latest` serves. While the package has no
+            `latest` (`explicit` promotion, before the first `PUT …/latest`),
+            an auto-run of any named version builds. Pass `buildInstructions`
+            to build any version into tables you name, other than the ones the
+            versions share. A run with `buildInstructions`, or under
+            `scope: "version"`, holds its own version's slot, so one such run is
+            active per version at a time; an auto-run under `scope: "package"`
+            writes the shared tables, so one is active per package. A second run
+            where one is already active answers 409, and so does a run with
+            `buildInstructions` that would write a table another active run of
+            the package writes. An auto-run learns its tables only when it
+            starts building, so one that would write such a table fails then.
         buildInstructions:
           oneOf:
             - $ref: "#/components/schemas/BuildInstructions"
@@ -9224,3 +10023,35 @@ components:
       description: ID of the materialization
       schema:
         type: string
+    versionId:
+      name: versionId
+      in: query
+      required: false
+      allowEmptyValue: true
+      description: |
+        The published version of the package to serve, a semantic version such
+        as `1.2.0` or `1.2.0-rc1`. `latest`, omitted or empty (`versionId=`,
+        which a proxy forwarding a page's query string may send), the request
+        is served from the package's `latest` version.
+
+        Any other value that is not a semantic version answers 400 with `reason`
+        VERSION_ID_INVALID, so a malformed value is told apart from a missing
+        version. An unknown version answers 404 with `reason` VERSION_NOT_FOUND,
+        and an archived one answers 410 with `reason` VERSION_ARCHIVED. A
+        package that has no versions (one loaded from `publisher.config.json`
+        or registered from a directory) is served as before when this is
+        omitted, and answers 404 VERSION_NOT_FOUND when it is given.
+
+        Build metadata must be percent-encoded: send `1.2.0+build.5` as
+        `1.2.0%2Bbuild.5`, since a bare `+` in a query string decodes to a space.
+      schema:
+        type: string
+    versionPath:
+      name: version
+      in: path
+      required: true
+      description: |
+        A published version of the package, a semantic version such as `1.2.0`.
+        Percent-encode build metadata (`+` as `%2B`).
+      schema:
+        $ref: "#/components/schemas/VersionIdPattern"