Public release release-ff7f847f143d

Source commit: ff7f847f143dc67864bed68a86cf259114384bd5

Public tree identity: sha256:bb7dcd2ac78bdbad2f4eba0f49be649d446d67f96f4eb2796941c026412fc032

docs/artifacts.md

@@ -0,0 +1,38 @@
+# Artifacts
+
+Clusterflux separates artifact metadata from artifact bytes.
+
+## Publish metadata
+
+`flush()` makes a VFS artifact visible to downstream tasks and records its
+digest, size, producer task and attempt, and retaining locations. It does not
+upload bytes to the coordinator by default.
+
+Your node retains artifact bytes on a best-effort basis. If every retaining node
+is lost, stale, revoked, or garbage-collects the bytes, the artifact is
+unavailable. Clusterflux reports that state instead of inventing durable
+storage.
+
+## Move bytes explicitly
+
+Use `sync()` or an explicit export when you need another node or your own storage
+system to hold the bytes. Same-node reuse avoids a coordinator transfer.
+
+## Download
+
+~~~bash
+clusterflux artifact list --process <process-id>
+clusterflux artifact download <artifact-id> --to ./output.bin --max-bytes 67108864
+~~~
+
+Before returning a link, the service checks authorization, current retention,
+source-node liveness, live size, per-project and per-account policy, and relay
+capacity. It reserves the affordable ingress and egress budget atomically. The
+scoped link is unguessable, expires, can be revoked, and is bound to the actor,
+tenant, project, process, artifact, and policy context.
+
+The reverse stream counts framing, base64 expansion, failed bytes, and abandoned
+transfers. The CLI verifies the final digest. Hosted policy may impose
+per-project, per-tenant, and per-account size, concurrency, and period limits.
+Operators may disable relay traffic as an emergency safety control; one tenant's
+period usage does not consume a shared customer byte quota.