design: define time and Clock capability contract

[vycdev2]

Summary

Define the canonical current-time API, value model, and Clock capability boundary before extending or extracting the time module.

Source documentation

• docs/progress.md, Phase K: Full Standard Library records time.now_ms and time.now_s as the partial current surface.
• docs/design.md, date and time examples instead use Clock.now(view clock) with Time and Duration plus higher-level time.* helpers.
• docs/design.md, Rule Set 16 defines Clock as the capability for reading current time and requires effects to be explicit.
• docs/architecture.md, capability analysis requires capability-free functions and verify blocks to remain pure.
• docs/architecture.md, standard library describes time.format as source-defined and Clock.now as runtime-backed.

Current state

The checker exposes zero-argument time.now_ms() -> int64 and time.now_s() -> int64 builtins, and the shared interpreter reads SystemTime::now() directly. These calls have no Clock parameter, are treated as pure, and can execute in verify blocks; the current fixture verifies host-clock-dependent thresholds. Before the Unix epoch the interpreter silently returns zero, while large unsigned durations are cast to int64 without a checked range policy. There is no stdlib/time.jett, no Clock.now implementation, and no dedicated time/Clock tracker.

The design and architecture instead describe Clock.now(view clock), Time, Timestamp, Duration, date formatting/arithmetic helpers, and platform-specific runtime lowering. The relationship between that intended surface and the current builtins is not defined.

Scope

This issue selects and documents the time boundary before implementation. It includes the canonical current-time entry point; Clock ownership and purity rules; wall-clock versus monotonic semantics; epoch, precision, range, and failure behavior; the relationship among Time, Timestamp, and Duration; deterministic testing and verify/comptime policy; compatibility for time.now_ms and time.now_s; and the source-defined versus runtime-backed split.

It does not implement the full calendar/timezone library, scheduler timers, async sleep, or native code generation. Those should be staged as separate implementation work after the contract is selected.

Acceptance criteria

• One canonical current-time API and compatibility policy for time.now_ms / time.now_s are selected.
• Wall-clock and monotonic use cases, units, epoch, precision, range, and pre-epoch/overflow behavior are specified.
• The Time, Timestamp, and Duration value model is defined or the unused spellings are retired.
• Clock capability ownership, interpreter/runtime injection, purity, and verify/comptime rules are specified.
• The minimum runtime-backed kernel and source-defined time helper boundary is documented, with deferred calendar/timezone work explicit.
• Focused implementation/test slices and future-backend handoff are identified.
• docs/design.md, docs/architecture.md, and docs/progress.md are aligned with the decision while the originating documentation remains in place.

Dependencies / open questions

Coordinate deterministic capability testing with #67. Future native lowering remains downstream of the HIR and MIR work tracked by #20 and #22.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.