Ah, if you’re thinking about contracts, that makes sense.

There are some things you can do in terms of contracts for effects, but you need a lot of runtime support. You might be interested in the work on temporal contracts.

I looked at <https://docs.racket-lang.org/temp-c/index.html#%28part._top%29|the temp-c docs>, and it looks like that may be relevant. However, like most of the contract system, it’s largely over my head. Looks like it’s about time for me to take a deep dive into the workings of the contract system.

There are a lot of ways I can imagine going with something like this. Is there something specific you’d like to aim for as a minimal viable goal? Like, some small set of effects to track and some specific use case that benefits from tracking that information?

From what you say, it sounds like the primary use case you have in mind is documentation clarity. Other use cases could be detecting bugs and enforcing that APIs are used only in forward-compatible ways. API enforcement is usually what I’m interested in. It’s not a goal I’m very optimistic about in Racket since effects are allowed anywhere, but I do like to think that as long as I stick to a pure-enough subset of Racket, I can sort of pretend the enforcement would work. :-p

A long term goal is to make a statically-typed version of my lang, and its type system will track effects. I want to keep the untyped and typed versions in line, so having an approach for managing effects in the untyped lang will be important.

I also like the idea of API enforcement. I’d like a stronger guarantee than convention that programs are only using effects in appropriate contexts and with appropriate resources.

I don’t want to disrupt Racket idioms too much, nor do I want the system to be heavyweight.

I/O, mutation of arguments, and continuations are things that I want to manage.

I’d like to be able to treat a procedure as “pure” if it is referentially-transparent, even if it uses mutable state or continuations internally.

Essentially, I want to track when procedures are effecting things outside of themselves.

Please note that I have very limited knowledge of PL and of effect systems in particular. My views and ideas are quite naïve and not well-formed.