Deferred values + @readStdin: the value-returning half of colorless implicit futures

[assapir]

Deferred values + @readStdin — the value-returning half of colorless implicit futures

Fixes #151. Builds on slice-1 (@, @sleep, now()). Adds the first value-returning @ primitive, @readStdin, plus the deferred-value machinery and a generic deferred-value runtime core. The type checker stays byte-identical (no Task/Future type — forcing keys off the operation, never the type; git diff under src/typechecker/ is empty).

What it does

@readStdin() -> Text (in core.io) reads one line from stdin. Calling it launches the read on a background fiber and returns a deferred Text immediately (the caller does not wait). The value threads lazily through bindings / records / calls and is forced on use — the fiber parks until the bytes are ready — only where a strict primitive reads them. At end-of-input it yields "".

<< core.io
<< core.test
^ = () -> Num => <
  line = @readStdin()       ~ launches; returns a deferred Text (no wait)
  assertEq(line, "hello")   ~ the == FORCES it: parks until ready, reads bytes
  0
>
~ echo hello | quilon run examples/readStdin.ql

How it's built

• Generic runtime core (quilon-rt/src/deferred.rs, quilon-rt: generalize the deferred-value launch/promise core (FnOnce producer), not stdin-specific #151): launch<T>(producer) -> *mut Promise<T> spawns a fiber that runs producer (which parks however it needs) and resolves the cell when it returns; force<T: Copy>(cell) -> T is the memoized park-until-ready wait. Promise<T> is GC-allocated so a GC pointer inside T stays scannable. @readStdin is a thin wrapper: __read_launch = launch(|| read_stdin_text(site)), __force_text = force::<QlSlice>. A future value-returning @ primitive (file/socket/HTTP) reuses launch with a different producer — no new park/promise plumbing. The C-ABI boundary stays per-primitive *_launch + per-representation force_* wrappers; only the Rust core is generic.
• Single-reader stdin gate: stdin is one serial stream, so reads are serialized (acquire/release via the scheduler's address-wait) — two concurrent @readStdin launches read consecutive lines instead of racing fd 0 (which would double-register the fd → EEXIST → crash) or corrupting the shared line buffer. The scheduler's Park::Waiting/park_on_address/wake_address is the one rendezvous serving both the value force and the gate. (Correctness-review finding.)
• Hybrid rep, zero-overhead for pure code: a Text is {ptr,i64}; a deferred Text is {promise, -1} (a real byte length is never negative → unambiguous sentinel). Only tainted values carry it.
• Deferred-taint pass (src/deferral.rs): forward dataflow computing the force-set — the strict slots where codegen must force (operands, ?/match scrutinee, print/write/native args incl. the callee expression, indexing, field/method receiver, array/record construction, interpolation holes, function/method/lambda body result). Lazy carriers = = bindings and ?/ternary/match arms. Reads the type oracle, adds no types.
• Codegen (exprs.rs force_deferred_text + a one-line generate_expr seam; calls.rs @readStdin lowering; intrinsics.rs prototypes): forces only at taint-marked spans → pure programs byte-identical.
• Scope join = run-to-completion (allSettled): the scheduler drives every launched read to completion before the program exits.
• Origin site: each @readStdin carries its path:line:col so a read fault reports where the IO was called.
• Corelib @-declaration fix: quilon check corelib/io.ql / corelib/time.ql no longer false-errors — the front-end trusts a bundled corelib source (matched by content) to declare @ primitives, while user code declaring one is still rejected.

Tests / proof

• tests/read_stdin_test.rs — pipes stdin to JIT + AOT: matching input exits 0, non-matching exits 101 (the real value flowed, not a constant); force at a print arg; and two reads serialize into consecutive lines (hello, world).
• quilon-rt deferred tests: launch → park-on-readiness → produce → force over a pipe (delayed writer); force memoization; the stdin gate serialization (at most one reader at a time); line splitting.
• src/deferral.rs: 11 taint-pass tests. Driver/modules: corelib @-decl allowed, user @-decl rejected.
• examples/readStdin.ql — a normal runnable example: with no piped input @readStdin() hits EOF and returns "", so it asserts line == "" and exits 0 in the gate (which feeds it /dev/null stdin so it never blocks). Pipe it a line to watch a value flow.

Deferred to a follow-up (documented)

Cross-source overlap as a showcase (independent reads finishing in max-time) arrives with a networked primitive (@get) — the generic launch is ready for it. Cross-function promise pipelining (a function returning a deferred value) is later; here a promise is forced at any escape (call arg / body result / construction), so it stays within its function body.

Gate: cargo fmt --all --check, cargo clippy --all-targets --all-features -D warnings, and the full suite under RUSTFLAGS=-D warnings (36 test binaries) all green. Checker byte-identical. Rebased on latest main.

Parked — do not merge without explicit approval.