Fensalir/docs/cult-runtime-surface.md

37 lines
1.3 KiB
Markdown
Raw Normal View History

2026-05-08 12:42:08 +01:00
# Cult Runtime Surface
2026-05-23 19:00:53 +01:00
Fensalir exposes the runtime cache path and schema catalog boundary; client
repos own their typed CultCache documents.
2026-05-08 12:42:08 +01:00
2026-05-23 19:00:53 +01:00
## Cache Path
2026-05-08 12:42:08 +01:00
2026-05-23 19:00:53 +01:00
`AquariumHost` parses `--cache <path>` and passes the result through
`AquariumRuntimeOptions.CultCachePath`. Direct runs can also use
`AQUARIUM_CULTCACHE_PATH`.
The dev scripts pass a repo-local cache path under:
2026-05-08 12:42:08 +01:00
```powershell
2026-05-23 19:00:53 +01:00
E:\Projects\Fensalir\artifacts\dev-reload\cultcache\aquarium-client.msgpack
2026-05-08 12:42:08 +01:00
```
2026-05-23 19:00:53 +01:00
Headless runs use a separate headless cache directory so smoke tests do not
overwrite the visible dev window's state.
2026-05-09 02:16:30 +01:00
2026-05-23 19:00:53 +01:00
## Ownership
2026-05-09 02:16:30 +01:00
2026-05-23 19:00:53 +01:00
Fensalir does not define every client document. A client runtime decides which
typed CultCache documents it persists: camera state, graphics settings, body
state, UI state, transport state, or anything else the client owns.
2026-05-09 02:16:30 +01:00
2026-05-23 19:00:53 +01:00
Shared settings that the host/renderer must understand belong in
`Aquarium.Engine.Contracts`. Client-specific schemas stay in the client repo.
2026-05-08 12:42:08 +01:00
2026-05-23 19:00:53 +01:00
## Failure Boundary
2026-05-08 12:42:08 +01:00
2026-05-23 19:00:53 +01:00
A truncated or unreadable single-file CultCache backing store is not a schema
migration failure. Client runtimes should quarantine corrupt snapshots and boot
fresh typed state instead of treating broken bytes as missing defaults.
2026-05-08 12:42:08 +01:00
2026-05-23 19:00:53 +01:00
Live reload should flush the current runtime before loading the next client
assembly so changed settings survive assembly reload.