feat: allow to delay auto-Promotion of Freight

[hiddeco]

Fixes: #2069

With this addition, it is possible to configure a duration for which the Freight of an upstream Stage has to be verified, effectively allowing it to "soak" in this Stage.

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: prod
  namespace: guestbook
spec:
  # ...omitted for brevity 
  requestedFreight:
  - origin:
      kind: Warehouse
      name: guestbook
    sources:
      stages: ["staging"]
      # Freight needs to be verified for 12 hours in "staging"
      # before being allowed to be auto-Promoted to "prod".
      verifiedFor: 12h0m

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	6248d3f
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/675718e5d32e4b000825a497
😎 Deploy Preview	https://deploy-preview-3100.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 51.23%. Comparing base (2655a03) to head (6248d3f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3100      +/-   ##
==========================================
+ Coverage   51.21%   51.23%   +0.02%     
==========================================
  Files         283      283              
  Lines       25466    25477      +11     
==========================================
+ Hits        13043    13054      +11     
  Misses      11727    11727              
  Partials      696      696              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[krancour]

This looks like it doesn't comprehensively address the question of a piece of Freight's overall availability to a given Stage. The required soak time isn't, for instance, being enforced in the case of a manual Promotion.

I realize that based on wording of this PR's title and issue #2069, that the scope might have been narrowly about auto-promotion, in which case this PR checks that box perfectly, but imho, the soak time should also be enforced for manual promotions, and if someone absolutely needs to manually Promote a piece of Freight whose soak time hasn't elapsed, they should add a manual Approval to it first. (I don't think soak time should apply to manual approvals.)

cc @jessesuen for his opinion on what the scope is supposed to be.

@hiddeco since you're out for a bit, I will take up any remaining work on this pending @jessesuen's clarification.

[jessesuen]

The required soak time isn't, for instance, being enforced in the case of a manual Promotion.
if someone absolutely needs to manually Promote a piece of Freight whose soak time hasn't elapsed, they should add a manual Approval to it first. (I don't think soak time should apply to manual approvals.)

Thanks for catching this. I agree. We can consider this feature similar to a policy is enforced regardless of auto vs. manual promotion and it would be good to have the guard rail in place for both humans and machines. Manual approval seems like the appropriate way to go around it.

[krancour]

Thanks @jessesuen. I think this is relatively easy to resolve.

[krancour]

I have this well underway now. I should have something ready late tomorrow.