Design a Future/Promise Primitive

Design the object model for a Future/Promise pair: a write-once container for a value that will be produced asynchronously. A producer completes the promise later; consumers wait for the result, poll it, or register callbacks that fire on completion.

Operating context. One process, multiple threads. The Promise (write side) is completed exactly once with a value or an error. The Future (read side) offers get() with a blocking and a timed variant, a non-blocking isDone(), and onComplete(callback). A callback may be registered before or after completion and must still run exactly once. Combinators such as then/map return a new future built from this one's result, running the transform on an injected executor. A still-pending future can be cancelled.

Out of scope. Distributed futures or RPC, the executor/thread-pool implementation (assume one is injected), undoing the side effects of already-running work, reactive multi-value streams, and any persistence.

What to produce. The class model (Future, Promise, the completion state, the callback registry), the public API of each side, the write-once state machine (pending to completed-with-value, completed-with-error, or cancelled), and the callback dispatch design. Be explicit about how exactly one completion wins a race, how callbacks run exactly once whether registered before or after completion, and why user callbacks must never run while the internal lock is held.