Merge pull request #36 from Kiln-AI/claude/lucid-lovelace-wgcgml

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

Author: scosman

src/seahaven/cli/mcp.py

@@ -145,8 +145,8 @@ def add_parser(subcommands: argparse._SubParsersAction[argparse.ArgumentParser])
         metavar="ISO",
         default=None,
         help=(
-            f"the clock a blank instance starts at (${CONVENIENCE['now']}); "
-            "not allowed with a fixture, which carries its own"
+            f"the clock the instance starts at (${CONVENIENCE['now']}); "
+            "with a fixture, no earlier than the fixture's own now"
         ),
     )
     # A string, not `choices=`: an unknown mode is `world.instance()`'s one-line

src/seahaven/docs/clock.md

@@ -6,9 +6,9 @@ starts, the four modes that say how it moves, and what they mean for the timesta
 
 ## Modes
 
-An instance's clock starts at a **start instant**: the fixture's `now`, or for a blank instance the
-`now=` it was given, or else the wall time at creation. The instance's **clock mode** says how the
-clock moves from there:
+An instance's clock starts at a **start instant**: the `now=` it was given, or else the fixture's
+`now`, or else, for a blank instance, the wall time at creation. The instance's **clock mode** says
+how the clock moves from there:
 
 | Mode | What the clock reads | Replays |
 |---|---|---|
@@ -78,7 +78,25 @@ clock does not move it. `wall` reads the host's clock at every reading.
 The clock is made *before* the blank database is built, not after, so a schema file that seeds
 reference rows of its own, such as `INSERT INTO plans VALUES ('free', ...)`, stamps them from the
 instance's clock as well. Freezing records the clock's reading at that moment as the fixture's
-`now`, and every instance of the fixture starts from there.
+`now`, and every instance of the fixture starts from there unless it is given a later `now=`.
+
+### Starting a fixture later
+
+Pass `now=` with a fixture to start the instance after the fixture's `now`. One fixture can then
+serve an eval at several times, such as three days later, when a deadline in the data has passed.
+The `small_startup` fixture of the reference world was frozen at `2026-06-01T09:00:00.000Z`:
+
+```python
+import projecttracker
+
+world = projecttracker.world
+
+with world.instance("small_startup", now="2026-06-04T09:00:00.000Z", clock_mode="fixed") as inst:
+    assert inst.clock.iso() == "2026-06-04T09:00:00.000Z"
+```
+
+A `now=` earlier than the fixture's `now` is refused. The fixture's rows are dated by its clock, so
+an earlier start would give the instance rows created in its future.
 
 ## Timestamps are not a complete order
 

src/seahaven/docs/concepts.md

@@ -160,9 +160,9 @@ other instance, no process.
 
 Every instance has a clock of its own. World code reads it through `ctx.clock`, and SQL's date and
 time functions, such as `CURRENT_TIMESTAMP`, read the same clock. The clock starts at the fixture's
-`now`. The instance's clock mode says how the clock moves from there: `fixed`, `tick`, `running`
-(the default) or `wall`. [clock.md](clock.md) explains each mode, how to choose one, and what the
-mode means for the timestamps a world writes.
+`now`, or at a later `now=` given to `world.instance(...)`. The instance's clock mode says how the
+clock moves from there: `fixed`, `tick`, `running` (the default) or `wall`. [clock.md](clock.md)
+explains each mode, how to choose one, and what the mode means for the timestamps a world writes.
 
 ## Reproducibility
 

src/seahaven/docs/db_schema_and_fixtures.md

@@ -153,7 +153,7 @@ world_version: 1.0.0
 | `id` | the fixture's name, and the directory it sits in |
 | `world`, `world_version` | the world it was frozen from |
 | `schema_hash` | the schema it conforms to |
-| `now` | the instance's clock reading when it was frozen, and where the clock of every instance of this fixture starts |
+| `now` | the instance's clock reading when it was frozen, and where the clock of every instance of this fixture starts unless it is given a later `now=` |
 | `parent_id` | the fixture it was forked from, or `null` |
 | `file_sha256` | the checksum of `state.sqlite`, verified before the first copy |
 | `created_at` | real wall-clock time, and one of only two wall-clock reads a world makes outside the `wall` clock mode |

src/seahaven/docs/reference/api.md

@@ -130,7 +130,7 @@ a NUL, an accent, a non-Latin script. A **fixture id** follows the same rule, an
 | `world.add_world(other, *, name=None, store=None, tool_prefix=None, tool_allow_list=None, tool_block_list=None, startup=None)` | add another world: its tools join this world's surface, its store becomes a node of every instance. Call it; there is nothing to decorate |
 | `world.state_format(name)` | register a state format of this world's own, as a decorator. The name is `<family>/<major>` and may not begin with `seahaven.` |
 | `world.resolve_state_format(name)` | the formatter a name answers to: a built-in, or one this world registered. Asked of the root of an instance and of nothing else |
-| `world.instance(fixture=None, *, seed=None, now=None, clock_mode=None, state_format=None, control_tools=False, startup=None)` | make an instance; a context manager. `now` is where a blank instance's clock starts. `clock_mode` is how the clock moves, `None` for `world.default_clock_mode`. `state_format` answers in another of this world's formats, in place of the pin. `control_tools=True` makes the framework's own control tool callable on the instance. `startup` is the world's own keywords, passed to the startup hooks that name them |
+| `world.instance(fixture=None, *, seed=None, now=None, clock_mode=None, state_format=None, control_tools=False, startup=None)` | make an instance; a context manager. `now` is where the clock starts, no earlier than the fixture's `now`. `clock_mode` is how the clock moves, `None` for `world.default_clock_mode`. `state_format` answers in another of this world's formats, in place of the pin. `control_tools=True` makes the framework's own control tool callable on the instance. `startup` is the world's own keywords, passed to the startup hooks that name them |
 | `world.fixtures()` | every fixture in the fixtures directory, as a list sorted by id. A world with no fixtures directory has none, which is not an error |
 | `copy.copy(world)` | this world with the same registrations and its own instances: set `fixtures_dir` on the copy to freeze somewhere else without moving the imported world's |
 | `world.tools` | the registry, in registration order. Read-only, and this world's **own** tools: the composite surface an agent sees is `inst.tools()`, or `world.composition().tools` |

src/seahaven/docs/reference/cli.md

@@ -204,7 +204,7 @@ command says so and exits 1.
 |---|---|---|---|
 | `--fixture NAME` | `SEAHAVEN_FIXTURE` | a blank instance | the fixture the instance starts from |
 | `--seed N` | `SEAHAVEN_SEED` | a random seed, written to stderr | the caller seed, an integer; the framework refuses a negative one, and one that does not fit in 8 bytes |
-| `--now ISO` | `SEAHAVEN_NOW` | wall time at creation | the clock a blank instance starts at; the framework refuses it together with a fixture |
+| `--now ISO` | `SEAHAVEN_NOW` | the fixture's `now`, or wall time at creation for a blank instance | where the instance's clock starts; with a fixture, the framework refuses an instant earlier than the fixture's `now` |
 | `--clock-mode MODE` | `SEAHAVEN_CLOCK_MODE` | the world's default | how the instance's clock moves: `fixed`, `tick`, `running` or `wall` |
 | `--reset-options JSON` | `SEAHAVEN_RESET_OPTIONS` | none | a JSON object of the keyword arguments `world.instance()` is called with; not allowed with `--fixture`, `--seed`, `--now` or `--clock-mode` |
 | `--world module:attr` | -- | the convention | which world to serve |

src/seahaven/docs/serving_and_openenv.md

@@ -116,8 +116,8 @@ A WebSocket connection is one session, and one session holds one instance.
 
 - **`reset(fixture=..., seed=..., startup=...)`** creates the instance. `reset()` with no fixture
   creates a blank instance from the schema, whose clock starts at wall time unless `now=` says
-  otherwise. Passing `now=` together with a fixture is refused, because the fixture carries its own
-  start instant.
+  otherwise. An instance of a fixture starts at the fixture's `now`, and `now=` can move that start
+  later ([clock.md](clock.md#starting-a-fixture-later)).
   Everything is passed straight to `world.instance(...)`, so the rules are the ones you already know
   from running in process.
 - **A second `reset`** destroys the current instance before making the new one, so a session never
@@ -132,7 +132,7 @@ A WebSocket connection is one session, and one session holds one instance.
 |---|---|
 | `fixture=` | the frozen starting state to copy. Omit it for a blank instance, built from the world's schema |
 | `seed=` | the seed behind `ctx.ids`, and behind SQL's `random()` and `randomblob()` |
-| `now=` | where the clock starts, for a blank instance only. A fixture carries its own, and `now=` with one is refused |
+| `now=` | where the clock starts. Omit it for the fixture's `now`, or for wall time on a blank instance. With a fixture, it must not be earlier than the fixture's `now` |
 | `clock_mode=` | how the clock moves: `fixed`, `tick`, `running` or `wall`. Omit it for the world's default ([clock.md](clock.md)) |
 | `episode_id=` | your own id for the episode, echoed back on `state` so a trajectory ties to your run |
 | `state_format=` | the format the `state` message answers in, in place of the world's pin ([state.md](state.md)) |

src/seahaven/fixtures.py

@@ -191,7 +191,7 @@ def id(self) -> str:
 
     @property
     def now(self) -> str:
-        """The clock every instance of this fixture starts at."""
+        """Where every instance of this fixture starts its clock, unless `now=` is later."""
         return self.meta.now
 
     @property

src/seahaven/instances.py

@@ -1038,9 +1038,9 @@ def create(
         # exists: an unknown startup keyword, a startup value no state document
         # could carry, a clock mode that does not exist, a format nothing
         # registered, an id that is not an id, a fixture that is missing,
-        # modified or frozen from another schema, and `now=` where the fixture
-        # already carries the clock. A creation that cannot succeed copies
-        # nothing and leaves nothing behind.
+        # modified or frozen from another schema, and a `now=` earlier than the
+        # fixture's own. A creation that cannot succeed copies nothing and leaves
+        # nothing behind.
         _check_startup_keywords(composition, keywords)
         serialised_startup = _serialised_startup(keywords)
         # On the root, and only the root: an added world's registrations are
@@ -1067,10 +1067,10 @@ def create(
             base = instance_seed(fixture_id if fixture_id is not None else world.name, seed)
             # Made before anything is built or copied: a `running` clock counts
             # from here, and a blank instance's schema reads it.
-            if fixture is not None:
-                clock = Clock.from_iso(fixture.now, mode)
-            elif now is not None:
+            if now is not None:
                 clock = _clock_from(now, mode)
+            elif fixture is not None:
+                clock = Clock.from_iso(fixture.now, mode)
             else:
                 clock = Clock(Clock.wall().now(), mode)
             if fixture is None:
@@ -1241,7 +1241,7 @@ def _fixture(
         for difference in check_composition(fixture.meta, composition):
             _log.info("fixture %s of world %s: %s", fixture_id, self._world.name, difference)
         if now is not None:
-            raise WorldBug("now= applies to blank instances only: a fixture carries its own clock")
+            _check_not_before_fixture(fixture, now)
         return fixture
 
     def _make_instance_dir(self, instance_id: str) -> Path:
@@ -1327,6 +1327,22 @@ def _clock_from(now: str | datetime, mode: ClockMode) -> Clock:
     return Clock.from_iso(now, mode) if isinstance(now, str) else Clock(now, mode)
 
 
+def _check_not_before_fixture(fixture: Fixture, now: str | datetime) -> None:
+    """Refuse a start instant earlier than the fixture's own `now`.
+
+    The fixture's rows are dated by its clock, so an earlier start would give the
+    instance rows created in its future.
+    """
+    requested = _clock_from(now, "fixed")
+    frozen = Clock.from_iso(fixture.now)
+    if requested.now() < frozen.now():
+        raise WorldBug(
+            f"now={requested.iso()} is earlier than {frozen.iso()}, the now of fixture "
+            f"{fixture.id!r}: the fixture's rows are dated by its clock, so start the instance "
+            "at or after it"
+        )
+
+
 def node_seed(base: bytes, path: str) -> bytes:
     """The seed one node's id stream is drawn from.
 

src/seahaven/openenv/env.py

@@ -373,8 +373,7 @@ class SeahavenResetRequest(ResetRequest):
     now: str | None = Field(
         default=None,
         description=(
-            "Where a blank instance's clock starts, as an ISO-8601 instant, e.g. "
-            "2024-03-05T12:00:00Z."
+            "Where the instance's clock starts, as an ISO-8601 instant, e.g. 2024-03-05T12:00:00Z."
         ),
     )
     clock_mode: _ClockModeField | None = Field(
@@ -506,9 +505,9 @@ def reset(
         `done` is `False` and `reward` is `None`, as on every observation here.
 
         `fixture=None` is a blank instance built from the world's DDL, whose clock
-        starts at the wall time unless `now=` says otherwise; a fixture carries
-        its own start and `now=` with one is refused. `clock_mode=` is the mode
-        the clock runs in, the world's default when it is not given.
+        starts at the wall time unless `now=` says otherwise; a fixture's clock
+        starts at the fixture's own `now`, or at a later `now=`. `clock_mode=`
+        is the mode the clock runs in, the world's default when it is not given.
         `state_format=` answers this episode's `state` message in another of the
         root world's formats, in place of the world's pin. An unknown mode or an
         unregistered format is refused before anything is copied. Those are the
@@ -538,8 +537,8 @@ def reset(
         it runs before `_forget()` and the session keeps the episode it had,
         which is what the same call does in process: an unknown keyword fails at
         argument binding, before the body. Everything the world judges -- an
-        unknown startup keyword, `now=` with a fixture -- is judged while the
-        instance is being made, after the old one is gone.
+        unknown startup keyword, a `now=` before the fixture's -- is judged
+        while the instance is being made, after the old one is gone.
 
         The old instance is destroyed *before* the new one is made, so the
         session never holds two at once. A creation that then fails leaves the