Public dry run release-5ee549dd5fdd

Source commit: 5ee549dd5fddc98e4ee5054679bb0ac405c82529

Public tree identity: sha256:61b170dbdd26d350b8aff072e1792d38afd76bac7881bd42f271864d9662a6d4

docs/artifacts.md

@@ -0,0 +1,36 @@
+# 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, project quota, 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 stricter
+size, concurrency, and period limits or disable relay traffic globally.