Retention

Retention decides how long artifacts live. It is the only setting that bounds what you store, and therefore the only one that bounds what you pay to hold.

A backup with no retention keeps everything forever. That is the default, and it is the right default, but it is not free.

The rule

An artifact is expired when it is both:

1. older than expire_after, and
2. outside the newest keep_last.

retention:
  expire_after: 90d    # nothing older than 90 days
  keep_last: 10        # but always keep the 10 most recent, however old

The two combine with and, never with or.

keep_last is a floor, not a cap

This is the most misread thing in the product.

keep_last: 5 on its own keeps every artifact forever, exactly as if retention were off. It does not mean "keep only five".

The reason is a failure we would rather not ship. Read as a cap, keep_last: 5 deletes your sixth-newest artifact the moment a seventh appears. A source that suddenly runs more often than expected, or a burst of manual triggers during an incident, would quietly destroy every copy older than this afternoon. A floor cannot do that.

There is no hard cap on count, deliberately. Bound by age, and use keep_last to stop the age bound biting during a quiet period.

Two things are never deleted

Whatever the policy says:

• The newest remaining artifact. A backup that has run at least once always has something to restore from.
• Any artifact still inside its lock window.

Retention is write-once

Fixed when you define the backup. Not editable afterwards, not loosened, not tightened, not turned off. A different policy means a new backup.

That constraint is the point rather than a limitation. The retention shown on a backup is the promise made to artifacts already archived under it. A number you could quietly raise next quarter, after an auditor asked, would not be a promise. Making it immutable is what makes it worth reading.

Protection: lock_for

lock_for marks new artifacts as protected for a window, during which our delete path and our retention sweep both refuse to remove them.

A policy that forbids a deletion it also requires is a contradiction, and is refused at definition.

If you need storage-layer immutability, deliver to your own bucket and configure object lock there, where enforcement is under your control.

The sweep

Expiry is done by a daily sweep, not at run time. Nothing in the backup path deletes anything.

• Expiry is not instant. "90 days" is 90 days plus up to one day.
• A backup with no expire_after is skipped entirely. Its artifacts are never examined.
• In your own buckets, the sweep deletes only where you granted allowDelete, which is off by default. With it off, that bucket grows forever and clearing it is your job.

Worked examples

A daily backup, one year in, on day 366.

The last row is where keep_last earns its place: when the age limit is tighter than the number of copies you want on hand.

Next