Placement

A draft, a cache and a signed record have different lives. Say where each one lives, per file or as a bucket default.

One landing, then a rule

Every write lands on your deployment first, and your PUT returns once it’s stored. Then its placement applies.

Placement	Where the bytes live	Use it for
Local	Your deployment only	Working data, scratch, anything its backups can recover
Held	Your deployment, until a seal time; replaceable or deletable until then	Drafts, staged submissions, anything that may be withdrawn
Walrus, hot	Walrus, plus a local copy	Records read often
Walrus, archive	Walrus only	Records that must outlive your app, or be readable without us

Local

No network write and no chain record unless you ask for a receipt, so constant rewrites cost nothing extra. A local file is as safe as the deployment and its backups, so promote what you can’t lose with one CopyObject onto itself:

aws s3api copy-object --bucket my-bucket --key data/file.bin \
  --copy-source my-bucket/data/file.bin \
  --metadata-directive REPLACE --metadata permafrost-tier=HOT

aws s3 cp and boto3’s copy() work too, but on large files they copy in parts: same bytes, new ETag.

Held, then sealed

A local file with a seal time. Until then, replace or delete it freely: nothing reaches Walrus or the chain, and a delete is complete. Sealing stores it on Walrus with a receipt. At the seal time the bucket’s policy decides: seal (the default), keep local, or delete.

Walrus

The default for a record: sealed for a stated span the deployment watches and renews, with a receipt. A hot file moves to archive once it goes unread. An archived file comes back on its next GET.

Buckets can archive to S3-compatible storage in your region instead. → Archiving within your region

Read the state back

HEAD and GET say where a file is now and what happens to it next:

Header	Tells you
x-amz-meta-permafrost-state	LOCAL, SEALED (Walrus plus local copy) or ARCHIVED (Walrus only)
x-amz-meta-permafrost-next	what comes next: seal, keep or delete for a hold, release when the local copy goes. Absent when nothing is scheduled
x-amz-meta-permafrost-next-at	when, as Unix time in milliseconds

Receipt only

Write local with a receipt, then delete. The receipt stays on chain. verifiable

Sizes

A single PUT sealed to Walrus has a size cap set per deployment; above it, 400 EntityTooLarge, so use multipart. The same cap applies to each part of a multipart upload sealed to Walrus. Local writes aren’t bound by this. Your deployment’s own limits apply first.

Set it once per bucket

A retention policy, fixed at bucket creation, sets the bucket’s default placement, renewal, span, what a lapsed hold becomes, where archive copies go, and a maximum age for a shared space. Files can still ask for something else. → Headers: S3 compatibility.