Virtual Track Draft Truncation/Retention Policy

app/api/definitions/components/release-tracks.yml

@@ -52,6 +52,18 @@ components:
       type: object
       description: 'A snapshot document for a release track, containing versioned member objects and workflow tiers'
       properties:
+        draft_cleanup:
+          $ref: '#/components/schemas/draft-cleanup-result'
+        snapshot_count:
+          type: integer
+          minimum: 0
+          readOnly: true
+          description: Current registry total, not the size of a filtered history page.
+        tagged_release_count:
+          type: integer
+          minimum: 0
+          readOnly: true
+          description: Current registry release total for virtual Workbench responses.
         alias:
           type: string
           nullable: true
@@ -1005,6 +1017,146 @@ components:
           type: string
           format: date-time
 
+    draft-retention:
+      type: object
+      additionalProperties: false
+      required: [max_drafts]
+      description: |
+        Virtual tracks only. A manual materialization may supply this policy
+        for that operation only; recurring policy belongs inside the cron schedule.
+        Missing policy or max_drafts null disables cleanup. All untagged creation
+        causes count across the track. Tags and protected sources always survive.
+        Saving a cron policy creates no draft and deletes nothing.
+      properties:
+        max_drafts:
+          type: integer
+          nullable: true
+          minimum: 1
+          maximum: 9007199254740991
+
+    draft-squash:
+      type: object
+      readOnly: true
+      required: [lower_bound, upper_bound, eligible_count, protected_count, fingerprint]
+      description: |
+        Read-only preview. Bounds are exclusive snapshot modified timestamps,
+        not tagging times. Null lower_bound means the first release.
+        Submit the fingerprint to the exact upper_bound snapshot endpoint.
+      properties:
+        lower_bound:
+          type: string
+          format: date-time
+          nullable: true
+        upper_bound:
+          type: string
+          format: date-time
+        eligible_count:
+          type: integer
+          minimum: 0
+        protected_count:
+          type: integer
+          minimum: 0
+        fingerprint:
+          type: string
+
+    draft-cleanup-result:
+      type: object
+      readOnly: true
+      required: [operation_id, status, kind, eligible_count, deleted_count, protected_count]
+      description: |
+        Nonpersistent operation response, backed by a durable audit intent.
+        A successful snapshot or release remains committed when cleanup is
+        pending or failed. Retry this operation, never repeat release POST.
+      properties:
+        operation_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [pending, completed, failed]
+        kind:
+          type: string
+          enum: [retention, squash]
+        eligible_count:
+          type: integer
+          minimum: 0
+        deleted_count:
+          type: integer
+          minimum: 0
+        protected_count:
+          type: integer
+          minimum: 0
+        target_modified:
+          type: string
+          format: date-time
+        release_committed:
+          type: boolean
+        error:
+          type: string
+
+    release-request:
+      type: object
+      additionalProperties: false
+      properties:
+        increment:
+          type: string
+          enum: [major, minor]
+          description: Mutually exclusive with version.
+        version:
+          type: string
+          pattern: '^\d+\.\d+$'
+        description:
+          type: string
+          maxLength: 4000
+        squash_drafts:
+          type: boolean
+          default: false
+          description: |
+            Administrator-only virtual-track opt-in. Finish publication before
+            deleting earlier eligible drafts in the reviewed interval.
+        squash_fingerprint:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: Required when squash_drafts is true; stale previews return 409 before tagging.
+
+    release-summary:
+      type: object
+      required:
+        [track_id, type, source_snapshot_modified, release_snapshot_modified, version, releasable]
+      properties:
+        track_id:
+          type: string
+        type:
+          type: string
+          enum: [standard, virtual]
+        source_snapshot_modified:
+          type: string
+          format: date-time
+        release_snapshot_modified:
+          type: string
+          format: date-time
+        version:
+          type: string
+        releasable:
+          type: boolean
+        draft_squash:
+          $ref: '#/components/schemas/draft-squash'
+
+    draft-cleanup-error:
+      type: object
+      description: Release publication did not complete. Inspect release_committed and retry the existing cleanup operation to repair partial publication.
+      properties:
+        message:
+          type: string
+        operation_id:
+          type: string
+          format: uuid
+        release_committed:
+          type: boolean
+        draft_cleanup:
+          $ref: '#/components/schemas/draft-cleanup-result'
+
     snapshot-schedule:
       description: |
         Virtual snapshot-creation schedule. Cron and explicit dates are
@@ -1034,6 +1186,8 @@ components:
               type: string
               description: 'Five-field UTC cron expression'
               example: '0 0 1 1,7 *'
+            draft_retention:
+              $ref: '#/components/schemas/draft-retention'
         - type: object
           additionalProperties: false
           required:

app/api/definitions/openapi.yml

@@ -388,6 +388,12 @@ paths:
   /api/release-tracks/{id}/virtual/schedule:
     $ref: 'paths/release-tracks-paths.yml#/paths/~1api~1release-tracks~1{id}~1virtual~1schedule'
 
+  /api/release-tracks/{id}/virtual/draft-cleanup:
+    $ref: 'paths/release-tracks-paths.yml#/paths/~1api~1release-tracks~1{id}~1virtual~1draft-cleanup'
+
+  /api/release-tracks/{id}/virtual/draft-cleanup/{operationId}/retry:
+    $ref: 'paths/release-tracks-paths.yml#/paths/~1api~1release-tracks~1{id}~1virtual~1draft-cleanup~1{operationId}~1retry'
+
   /api/release-tracks/{id}/virtual/snapshots/create:
     $ref: 'paths/release-tracks-paths.yml#/paths/~1api~1release-tracks~1{id}~1virtual~1snapshots~1create'