[scosman]

Summary

This adds a framework-level setup_sql parameter beside fixture, startup and now on world.instance(...) and the OpenEnv reset. With it, a caller can change a new instance's rows using SQL, without writing a startup hook. The spec is in specs/projects/startup_sql/.

env.reset(
    fixture="agency",
    setup_sql="INSERT INTO users (...) VALUES (...); UPDATE issues SET priority = 0 WHERE key = 'ENG-3'",
    startup={"user_id": "..."},
)

Order of work at instance creation:

1. The fixture is copied, or the blank schema is built.
2. setup_sql runs in one transaction on one hardened connection to the root, with every added node attached by schema name (payments.charges, payments__tax.rates).
3. The transaction commits.
4. The startup hooks run and see those rows.

Change log and state: setup rows are not in the change log, and call_count stays 0. The state document echoes setup_sql beside startup.

Statements: ; separates statements, split using apsw.complete, so a ; inside a string literal is safe.

Determinism: random() draws from its own seeded stream (SETUP_STREAM), so the instance's own draws do not change. The clock functions read the instance's clock.

Guard: a default-deny authorizer, based on the sandbox Authorizer, limits it to reading and writing rows.

• It refuses schema changes, transaction control, ATTACH/DETACH, pragmas other than the reporting ones, and functions outside the run_sql allowlist.
• Every failure is a loud WorldBug that names the statement (setup_sql statement 2 of 3 was refused: … <fix>) and rolls everything back. No instance directory is left behind.
• Over OpenEnv, a failed reset leaves the session fresh. HTTP PUT answers 400.

Entry points: world.instance, OpenEnv reset (in process and over the WebSocket), HTTP PUT, seahaven mcp --reset-options, and the /ui console. The console shows a multi-line "Setup Sql" box with no console code change, because the field is one nullable string.

Commits

• Phase 1, core: seahaven/setup_sql.py, the parameter on World.instance, InstanceManager.create and Instance, the pytest marker, and about 95 tests in tests/test_setup_sql.py.
• Phase 2, entry points: the state envelope, SeahavenState, SeahavenResetRequest, RESET_ORDER, the console mock and smoke order, every pinned test, and entry-point tests including a projecttracker test.
• Phase 3, docs: updates to six existing pages, with one runnable example.

Deviations from the spec (decided during review)

• World trigger bodies are trusted for function calls and reads, matched by trigger name. Without this, a world trigger that uses changes() or json_each would make every INSERT into its table fail.
  • Views are not trusted, because SQLite names a view while it resolves the caller's own WHERE clause in DML on an INSTEAD OF view.
  • Accepted residual: a CTE named after a world trigger shares that trigger's trust for reads and functions. A test pins it, and the code says why it is accepted: setup_sql comes from the eval author, and the guard catches mistakes rather than attacks.
• Read-only pragmas are allowed (the inspection connection's list).
• A failure at COMMIT (a deferred constraint) is also reported as a WorldBug.

Test plan

• Every check in AGENTS.md (ruff, ty split, framework, projecttracker and xmlrpc suites, licence gates) in both the serve and mcp environments.
• Console e2e smoke test against both mocks.
• Tests run through world.instance(...) and through each real entry point.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D327Rt1yFbLSkhA7ocsWhz

---

Generated by Claude Code