Allow fixtures to start at a later now= instead of refusing it

[scosman]

Summary

This change allows instances of fixtures to start at a later clock time by passing now= to world.instance(), while refusing any now= that is earlier than the fixture's own clock. Previously, now= was rejected entirely for fixtures.

Key Changes

• Clock initialization logic: Reordered the clock creation to check now= parameter first before falling back to the fixture's now, allowing explicit now= to override the fixture's default start time.

• Validation: Replaced the blanket rejection of now= with fixtures with a new _check_not_before_fixture() function that validates the requested now= is not earlier than the fixture's own clock. This prevents instances from starting with rows that appear to be created in the future.

• Error messaging: When a now= earlier than the fixture is provided, the error message now clearly names both the requested time and the fixture's time, helping users understand the constraint.

• Documentation updates: Updated all user-facing documentation (API docs, CLI help, OpenEnv descriptions, and concept guides) to reflect that:

  • now= can be used with fixtures to start later
  • The constraint is that now= must not be earlier than the fixture's own now
  • This enables use cases like evaluating a fixture at different points in time (e.g., three days after the fixture was frozen)

Implementation Details

• The clock is created before the database is built, ensuring that schema-seeded reference rows are also timestamped from the instance's actual start time.
• The validation uses the same _clock_from() helper to normalize both string ISO-8601 and datetime objects for comparison.
• Tests verify both the happy path (starting a fixture at a later time) and the error case (attempting to start earlier than the fixture).

https://claude.ai/code/session_01J18y3rhPWRqMxZtUmBeeh6