fix(async): preserve cancellation and add revision-aware job gate

packages/async/README.mdmodified+25-0

Changes to packages/async/README.md

		⋯95 linesShow the 95 lines above this hunk@@ -96,3 +96,28 @@ scripts/async-runtime-tsan.sh 1 10000 1024
96	96	## License
97	97
98	98	Part of the Home programming language project.
	99	+
	100	+## Terminal job state and event completion
	101	+
	102	+Task cancellation is terminal: an in-flight future poll returning Ready or Pending
	103	+cannot overwrite Cancelled, and cancelling an already completed/failed task does
	104	+not replace its result. JoinHandle.await returns TaskFailed immediately for a
	105	+failed task. Cancellation does not interrupt a currently executing poll or make
	106	+its storage safe to free; quiesce/join the polling owner before deinit.
	107	+
	108	+`CompletionGate` is a small allocation-free two-phase event-job helper. It ignores
	109	+events from older revisions and terminal outcomes before an active phase has been
	110	+observed. Success, failure, cancellation and stop are immutable terminal states.
	111	+The caller owns synchronization; it is not an executor or a generic Future.
	112	+zig-utils/zig-camera uses this Home module for autofocus scan gating under its
	113	+native session mutex without allocating or running consumer work in callbacks.
	114	+
	115	+Regression tests cover cancellation between poll reservation and both Ready and
	116	+Pending results, late cancellation, failed joins, stale event revisions, and
	117	+terminal immutability. Focused task/gate tests pass on Zig 0.15.2 and Home's current
	118	+0.17 development toolchain. The complete async root suite also passes locally with
	119	+its threading_futex module supplied:
	120	+
	121	+```sh
	122	+zig test -lc --dep threading_futex -Mroot=packages/async/src/async.zig -Mthreading_futex=packages/runtime/src/threading/Futex.zig
	123	+```