foliot 0.1.0__tar.gz

foliot-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to foliot will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and releases use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-05
+
+### Added
+
+- Mandatory `BaseAction` lifecycle with stable admission identity.
+- Scheduled and recurring actions.
+- Suspension, exact deadline shifting, and the `on_resume` hook.
+- Counter-based deterministic random streams and secure world-seed creation.
+- Structural `Store` and `Txn` protocols.
+- Dependency-free `MemoryStore` reference implementation.
+- Atomic deterministic `Simulation` tick processing.
+- Inclusive `ManualDriver` and drift-resistant `RealtimeDriver`.
+- Optional post-effect `TickFinalizer` and owner-wide action deletion.
+- Optional `foliot.events` layer for simultaneous participant Intents.
+- `EventMemoryStore`, stable Event/entity id templates, and explicit Event
+  continuation and ending.
+- Runnable Layer-1 Tinyworld and Layer-2 Eventworld examples.
+
+[Unreleased]: https://github.com/wordedword75049/foliot/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wordedword75049/foliot/releases/tag/v0.1.0

foliot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to foliot
+
+Thank you for helping improve foliot. The project favors small, explicit
+changes that preserve deterministic behavior and keep game concepts outside
+the engine.
+
+## Setup
+
+Install [uv](https://docs.astral.sh/uv/), then run:
+
+```console
+uv sync
+```
+
+The project supports Python 3.12 and newer. Runtime dependencies must remain
+empty unless a new dependency has been discussed and justified first.
+
+## Required checks
+
+```console
+uv run ruff format --check src tests examples
+uv run ruff check src tests examples
+uv run basedpyright
+uv run pytest
+```
+
+Use `uv run ruff format` to apply formatting.
+
+## Design rules
+
+- Every queued game action inherits `BaseAction`.
+- External ports such as stores, effects, contexts, RNGs, and drivers use
+  structural `Protocol` typing.
+- Keep public contexts narrow. Pass `ctx.rng` to a helper instead of passing
+  the whole context.
+- Game nouns do not belong in foliot. The engine has no built-in HP, character,
+  target, location, or combat model.
+- Use PEP 695 generic syntax; the supported floor is Python 3.12.
+- Do not use `Any` in public signatures.
+- Use exhaustive `match` statements for closed state unions; do not add a
+  catch-all branch that disables type-checker exhaustiveness.
+- Use `logging.getLogger(__name__)`; library code must never call
+  `logging.basicConfig()` or print.
+- Do not use Python's `random` module outside `rng.py`, `hash()` for persistent
+  string identity, or wall-clock time outside a driver.
+- Keep the root and `foliot.events` export lists curated. A public import path
+  is a compatibility promise.
+
+## Tests
+
+Tests use handwritten fakes rather than `unittest.mock`, `pytest-mock`,
+monkeypatching production objects, or time-freezing libraries.
+
+Important changes should prove the architectural property they affect:
+
+- replay produces the same output from the same seed;
+- reversing due-action order does not change results;
+- suspension shifts deadlines by the exact pause duration;
+- exceptional transaction exit publishes no foliot-owned state;
+- an incomplete Event round retains exactly one copy of every current child;
+- Layer 1 behaves identically when the optional Event layer is unused.
+
+Test game actions directly with a tiny recording context whenever possible.
+Use a full `Simulation` only when testing engine coordination.
+
+## Documentation
+
+Public docstrings explain behavior, parameters, return values, and meaningful
+exceptions. Examples should show normal usage. Internal comments should explain
+why a non-obvious mechanism exists rather than narrating the next line of code.
+
+Update the relevant guide whenever a public contract changes.
+
+Maintainers should follow [RELEASING.md](RELEASING.md) for versioning, artifact
+checks, and trusted publication.

foliot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Ivanin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foliot-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: foliot
+Version: 0.1.0
+Summary: A deterministic tick-driven simulation core: durable queue, absolute deadlines, per-entity randomness.
+Keywords: simulation,scheduler,tick,deterministic,event-queue
+Author: Nikita Ivanin
+Author-email: Nikita Ivanin <naik.iva@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment :: Simulation
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/wordedword75049/foliot
+Project-URL: Documentation, https://github.com/wordedword75049/foliot/blob/main/docs/index.md
+Project-URL: Repository, https://github.com/wordedword75049/foliot.git
+Project-URL: Issues, https://github.com/wordedword75049/foliot/issues
+Project-URL: Changelog, https://github.com/wordedword75049/foliot/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# foliot
+
+`foliot` is a small, deterministic simulation engine for worlds that advance
+in logical ticks.
+
+It gives you a durable action queue, scheduled and recurring work, reproducible
+randomness, suspension and resumption, atomic ticks, real-time pacing, and an
+optional layer for simultaneous multi-entity events. It deliberately does not
+define characters, maps, combat, health, inventories, or quests. Those belong
+to your simulation.
+
+> **Status:** pre-alpha. The core is tested and usable, but the public API may
+> still change before 1.0.
+
+## Why foliot?
+
+- **Reproducible:** the same world seed and inputs produce the same history.
+- **Order-independent:** unrelated actions have independent random streams.
+- **Transactional:** queue changes, effects, journal lines, and the tick commit
+  through one store transaction.
+- **Fast-forwardable:** use logical time to run millions of ticks without
+  sleeping.
+- **Domain-agnostic:** your game owns its world model and rules.
+- **Storage-agnostic:** implement two small protocols for PostgreSQL, MySQL,
+  MariaDB, a file, or another backend.
+- **Dependency-free:** the installed library uses only the Python standard
+  library.
+
+## Installation
+
+```console
+pip install foliot
+```
+
+Python 3.12 or newer is required.
+
+## Five-minute example
+
+```python
+from dataclasses import dataclass
+from typing import override
+
+from foliot import BaseAction, EntityId, ManualDriver, MemoryStore, Simulation, TickContext
+
+
+@dataclass(slots=True)
+class World:
+    energy: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class LoseEnergy:
+    amount: int
+
+    def apply(self, world: World, /) -> None:
+        world.energy -= self.amount
+
+
+class Hunger(BaseAction[World]):
+    def __init__(self, entity_id: EntityId) -> None:
+        super().__init__(entity_id, suspendable=False)
+
+    @override
+    def process(self, ctx: TickContext[World], /) -> None:
+        ctx.emit(LoseEnergy(1))
+        ctx.log("Lira grows hungry.")
+
+
+world = World()
+store = MemoryStore(
+    world,
+    world_seed=1,
+    initial_actions=((Hunger(EntityId("lira")), None),),
+)
+
+Simulation(store).run(ManualDriver(until_tick=9))
+
+assert world.energy == 90
+assert len(store.logs) == 10
+```
+
+`due_tick=None` makes `Hunger` recurring, so it runs once per logical tick.
+Effects and journal lines are collected first and applied only after every due
+action has made its decision.
+
+## The model
+
+An action begins **unbound**. Its first successful store admission assigns one
+permanent sequence number and an active state. Scheduling the same object again
+changes its deadline without changing that identity.
+
+| Request | Meaning |
+|---|---|
+| `ctx.schedule(action, 100)` | Run at tick 100. |
+| `ctx.schedule(action, None)` | Run every tick until `ctx.finish()`. |
+| `ctx.emit(effect)` | Apply a game-defined world change after decisions. |
+| `ctx.log(line)` | Append deterministic narrative output. |
+| `ctx.suspend(entity_id, by=handle)` | Pause that entity's suspendable actions. |
+| `ctx.finish()` | Remove the current action. |
+
+Concrete deadlines must always be later than the current tick. An action due
+at tick 90 can reschedule itself for tick 100; it keeps the same sequence
+number.
+
+## Optional simultaneous Events
+
+Ordinary actions are enough for walking, hunger, poison, construction, growth,
+and most other simulation work. Import `foliot.events` only when several
+entities must decide from the same tick-start state before any result applies.
+
+```python
+from foliot import Simulation
+from foliot.events import EventMemoryStore, Events
+
+store = EventMemoryStore(world, world_seed=1)
+simulation = Simulation(store, events=Events(store))
+```
+
+Each `EventAction` returns one game-defined Intent. Once every expected
+participant has answered in the same tick, the concrete `BaseEvent` resolves
+the complete set into either `Outcome.continue_with(...)` or `Outcome.end(...)`.
+Combat formulas and lifecycle rules remain game code.
+
+Run the complete example:
+
+```console
+uv run python -m examples.eventworld
+```
+
+## Storage
+
+`MemoryStore` and `EventMemoryStore` are ready-made implementations for tests,
+examples, and temporary simulations. They disappear with the process.
+
+A durable application implements `Store` and `Txn` (plus `EventStore` and
+`EventTxn` when Events are enabled). Foliot decides *when* the transaction
+begins and commits; your adapter decides *how* actions and world state are
+encoded in its database.
+
+See [Writing a store](https://github.com/wordedword75049/foliot/blob/main/docs/stores.md)
+for the complete contract and a
+PostgreSQL-shaped example.
+
+## Documentation
+
+- [Documentation index](https://github.com/wordedword75049/foliot/blob/main/docs/index.md)
+- [Quickstart](https://github.com/wordedword75049/foliot/blob/main/docs/quickstart.md)
+- [Actions and effects](https://github.com/wordedword75049/foliot/blob/main/docs/actions.md)
+- [Simultaneous Events](https://github.com/wordedword75049/foliot/blob/main/docs/events.md)
+- [Writing a durable store](https://github.com/wordedword75049/foliot/blob/main/docs/stores.md)
+- [Determinism and randomness](https://github.com/wordedword75049/foliot/blob/main/docs/determinism.md)
+- [Manual and real-time drivers](https://github.com/wordedword75049/foliot/blob/main/docs/drivers.md)
+- [Architecture](https://github.com/wordedword75049/foliot/blob/main/docs/architecture.md)
+- [Public API map](https://github.com/wordedword75049/foliot/blob/main/docs/api.md)
+- [Contributing](https://github.com/wordedword75049/foliot/blob/main/CONTRIBUTING.md)
+
+## Development
+
+```console
+uv sync
+uv run ruff format --check src tests examples
+uv run ruff check src tests examples
+uv run basedpyright
+uv run pytest
+```
+
+## License
+
+MIT

foliot-0.1.0/README.md

@@ -0,0 +1,169 @@
+# foliot
+
+`foliot` is a small, deterministic simulation engine for worlds that advance
+in logical ticks.
+
+It gives you a durable action queue, scheduled and recurring work, reproducible
+randomness, suspension and resumption, atomic ticks, real-time pacing, and an
+optional layer for simultaneous multi-entity events. It deliberately does not
+define characters, maps, combat, health, inventories, or quests. Those belong
+to your simulation.
+
+> **Status:** pre-alpha. The core is tested and usable, but the public API may
+> still change before 1.0.
+
+## Why foliot?
+
+- **Reproducible:** the same world seed and inputs produce the same history.
+- **Order-independent:** unrelated actions have independent random streams.
+- **Transactional:** queue changes, effects, journal lines, and the tick commit
+  through one store transaction.
+- **Fast-forwardable:** use logical time to run millions of ticks without
+  sleeping.
+- **Domain-agnostic:** your game owns its world model and rules.
+- **Storage-agnostic:** implement two small protocols for PostgreSQL, MySQL,
+  MariaDB, a file, or another backend.
+- **Dependency-free:** the installed library uses only the Python standard
+  library.
+
+## Installation
+
+```console
+pip install foliot
+```
+
+Python 3.12 or newer is required.
+
+## Five-minute example
+
+```python
+from dataclasses import dataclass
+from typing import override
+
+from foliot import BaseAction, EntityId, ManualDriver, MemoryStore, Simulation, TickContext
+
+
+@dataclass(slots=True)
+class World:
+    energy: int = 100
+
+
+@dataclass(frozen=True, slots=True)
+class LoseEnergy:
+    amount: int
+
+    def apply(self, world: World, /) -> None:
+        world.energy -= self.amount
+
+
+class Hunger(BaseAction[World]):
+    def __init__(self, entity_id: EntityId) -> None:
+        super().__init__(entity_id, suspendable=False)
+
+    @override
+    def process(self, ctx: TickContext[World], /) -> None:
+        ctx.emit(LoseEnergy(1))
+        ctx.log("Lira grows hungry.")
+
+
+world = World()
+store = MemoryStore(
+    world,
+    world_seed=1,
+    initial_actions=((Hunger(EntityId("lira")), None),),
+)
+
+Simulation(store).run(ManualDriver(until_tick=9))
+
+assert world.energy == 90
+assert len(store.logs) == 10
+```
+
+`due_tick=None` makes `Hunger` recurring, so it runs once per logical tick.
+Effects and journal lines are collected first and applied only after every due
+action has made its decision.
+
+## The model
+
+An action begins **unbound**. Its first successful store admission assigns one
+permanent sequence number and an active state. Scheduling the same object again
+changes its deadline without changing that identity.
+
+| Request | Meaning |
+|---|---|
+| `ctx.schedule(action, 100)` | Run at tick 100. |
+| `ctx.schedule(action, None)` | Run every tick until `ctx.finish()`. |
+| `ctx.emit(effect)` | Apply a game-defined world change after decisions. |
+| `ctx.log(line)` | Append deterministic narrative output. |
+| `ctx.suspend(entity_id, by=handle)` | Pause that entity's suspendable actions. |
+| `ctx.finish()` | Remove the current action. |
+
+Concrete deadlines must always be later than the current tick. An action due
+at tick 90 can reschedule itself for tick 100; it keeps the same sequence
+number.
+
+## Optional simultaneous Events
+
+Ordinary actions are enough for walking, hunger, poison, construction, growth,
+and most other simulation work. Import `foliot.events` only when several
+entities must decide from the same tick-start state before any result applies.
+
+```python
+from foliot import Simulation
+from foliot.events import EventMemoryStore, Events
+
+store = EventMemoryStore(world, world_seed=1)
+simulation = Simulation(store, events=Events(store))
+```
+
+Each `EventAction` returns one game-defined Intent. Once every expected
+participant has answered in the same tick, the concrete `BaseEvent` resolves
+the complete set into either `Outcome.continue_with(...)` or `Outcome.end(...)`.
+Combat formulas and lifecycle rules remain game code.
+
+Run the complete example:
+
+```console
+uv run python -m examples.eventworld
+```
+
+## Storage
+
+`MemoryStore` and `EventMemoryStore` are ready-made implementations for tests,
+examples, and temporary simulations. They disappear with the process.
+
+A durable application implements `Store` and `Txn` (plus `EventStore` and
+`EventTxn` when Events are enabled). Foliot decides *when* the transaction
+begins and commits; your adapter decides *how* actions and world state are
+encoded in its database.
+
+See [Writing a store](https://github.com/wordedword75049/foliot/blob/main/docs/stores.md)
+for the complete contract and a
+PostgreSQL-shaped example.
+
+## Documentation
+
+- [Documentation index](https://github.com/wordedword75049/foliot/blob/main/docs/index.md)
+- [Quickstart](https://github.com/wordedword75049/foliot/blob/main/docs/quickstart.md)
+- [Actions and effects](https://github.com/wordedword75049/foliot/blob/main/docs/actions.md)
+- [Simultaneous Events](https://github.com/wordedword75049/foliot/blob/main/docs/events.md)
+- [Writing a durable store](https://github.com/wordedword75049/foliot/blob/main/docs/stores.md)
+- [Determinism and randomness](https://github.com/wordedword75049/foliot/blob/main/docs/determinism.md)
+- [Manual and real-time drivers](https://github.com/wordedword75049/foliot/blob/main/docs/drivers.md)
+- [Architecture](https://github.com/wordedword75049/foliot/blob/main/docs/architecture.md)
+- [Public API map](https://github.com/wordedword75049/foliot/blob/main/docs/api.md)
+- [Contributing](https://github.com/wordedword75049/foliot/blob/main/CONTRIBUTING.md)
+
+## Development
+
+```console
+uv sync
+uv run ruff format --check src tests examples
+uv run ruff check src tests examples
+uv run basedpyright
+uv run pytest
+```
+
+## License
+
+MIT

foliot-0.1.0/RELEASING.md

@@ -0,0 +1,49 @@
+# Releasing foliot
+
+Publishing is intentionally automated through GitHub Actions and PyPI Trusted
+Publishing. No long-lived PyPI token belongs in the repository.
+
+## One-time PyPI setup
+
+Before the first release, create a pending trusted publisher for the future
+`foliot` project with these values:
+
+- PyPI project name: `foliot`
+- GitHub owner: `wordedword75049`
+- GitHub repository: `foliot`
+- Workflow filename: `release.yml`
+- Environment name: `pypi`
+
+Also create the `pypi` environment in the GitHub repository settings. See
+[PyPI's Trusted Publishers guide](https://docs.pypi.org/trusted-publishers/).
+
+## Prepare a release
+
+1. Choose the version and update `project.version` in `pyproject.toml`.
+2. Move the release notes out of `Unreleased` in `CHANGELOG.md` and add the
+   release date.
+3. Run the complete checks:
+
+   ```console
+   uv sync --locked
+   uv run ruff format --check src tests examples
+   uv run ruff check src tests examples
+   uv run basedpyright
+   uv run pytest
+   uv build --no-sources
+   ```
+
+4. Inspect both files under `dist/` and install the wheel in a fresh virtual
+   environment as a smoke test.
+5. Commit the release preparation and push it to `main`.
+
+## Publish
+
+Create and publish a GitHub release whose tag exactly matches the package
+version with a `v` prefix, such as `v0.1.0`. Publishing the GitHub release
+triggers `.github/workflows/release.yml`, which repeats all checks, builds the
+artifacts, and sends them to PyPI through the trusted publisher.
+
+PyPI versions are immutable. If publishing fails after a file was accepted,
+fix the problem under a new version rather than trying to replace the file.
+

foliot-0.1.0/docs/actions.md

@@ -0,0 +1,98 @@
+# Actions and effects
+
+## Action ownership
+
+Every `BaseAction` has an `entity_id`: the entity that owns the work. Foliot
+uses it for random-stream isolation, suspension, and owner-wide deletion. It
+does not mean “target.” Directed simulations can add a mandatory `target_id`
+in their own shared action base.
+
+## Admission and identity
+
+A newly constructed action has `Unbound()` as its complete binding. The first
+successful `Txn.schedule(...)` changes it to `Bound(seq, Active(due_tick))`.
+
+`seq` is permanent. Rescheduling, suspending, and resuming replace the state
+without changing the sequence number. A durable adapter must persist and
+restore both the binding and every game-defined subclass field.
+
+## Scheduled and recurring actions
+
+- `due_tick=50` means the action becomes due at logical tick 50.
+- `due_tick=None` means the action is due on every tick.
+- A deadline must be strictly later than the tick that schedules it.
+
+A scheduled action disappears after it runs unless it reschedules itself. A
+recurring action remains until it calls `ctx.finish()`.
+
+```python
+@override
+def process(self, ctx: TickContext[World], /) -> None:
+    ctx.emit(Damage(self.entity_id, 2))
+    next_strike = ctx.tick + self.interval
+    if next_strike < self.expires_at:
+        ctx.schedule(self, next_strike)
+```
+
+The same poison object—and therefore the same `seq` and game payload—moves to
+the new deadline.
+
+## Collect first, apply later
+
+Each action receives its own `TickContext`. The context collects effects,
+schedules, suspension requests, completion, and log lines. If the handler
+raises, that context is discarded and the error is written to ordinary Python
+operational logging. Other valid actions may still commit.
+
+After all due actions have decided, valid contexts apply in stable sequence
+order. An effect that raises is different: effects execute inside the tick
+transaction, so the exception aborts the entire tick.
+
+## Suspension
+
+```python
+ctx.suspend(lira_id, by=fight_id)
+```
+
+This pauses every suspendable action owned by Lira. Non-suspendable work such
+as hunger or poison continues.
+
+A suspended action remembers when it paused, who owes the wake-up, and its
+old deadline. Resuming by the same handle shifts the stored deadline forward
+by the exact pause duration. Override `on_resume(paused_for)` when the action
+also has a game-owned deadline:
+
+```python
+@override
+def on_resume(self, paused_for: int, /) -> None:
+    self.arrives_at += paused_for
+```
+
+## Effects
+
+An effect needs only this structural shape:
+
+```python
+class Effect[W](Protocol):
+    def apply(self, world: W, /) -> None: ...
+```
+
+Foliot does not know whether the effect represents damage, healing, ownership,
+weather, construction, or economics. Effects should normally carry all data
+needed to apply their mutation.
+
+## Post-effect finalization
+
+An optional `TickFinalizer` sees the world after ordinary and Event effects.
+It is the place for game rules such as death:
+
+```python
+class DeathFinalizer:
+    def finalize(self, world: World, ctx: FinalizationContext[World], /) -> None:
+        for character in world.characters.values():
+            if character.hp == 0:
+                ctx.delete_owned_by(character.entity_id)
+```
+
+Foliot provides the timing and cleanup tools; it never defines what death
+means.

foliot-0.1.0/docs/api.md

@@ -0,0 +1,42 @@
+# Public API
+
+This page is a map of foliot's supported import surface. The docstrings on
+each object contain the detailed parameter and error contracts.
+
+## Core
+
+Import these names directly from `foliot`:
+
+- **Actions:** `BaseAction`, `ActionBinding`, `Unbound`, `Bound`, `ActionState`,
+  `Active`, and `Suspended`.
+- **Processing:** `TickContext`, `Effect`, `Simulation`, `TickFinalizer`, and
+  `FinalizationContext`.
+- **Time:** `Driver`, `ManualDriver`, and `RealtimeDriver`.
+- **Storage:** `Store`, `Txn`, and `MemoryStore`.
+- **Randomness:** `Rng`, `counter_rng`, and `new_world_seed`.
+- **Identifiers:** `Tick`, `EntityId`, and `SuspensionId`.
+
+`BaseAction` is the one mandatory base class. The remaining action-state
+classes are useful when a store adapter serializes or inspects queue state.
+
+## Optional Events
+
+Import these names from `foliot.events` only when simultaneous decisions are
+needed:
+
+- **Actions and intents:** `EventAction` and `IntentRecord`.
+- **Events and outcomes:** `BaseEvent`, `Outcome`, `DecisionContext`, and
+  `ResolutionContext`.
+- **Integration:** `Events`, `EventStore`, `EventTxn`, and `EventMemoryStore`.
+- **Commands:** `open_event` and `end_event`.
+- **Stable identifiers:** `EventId`, `EventIdTemplate`, and `EntityIdTemplate`.
+- **Configuration errors:** `EventConfigurationError`.
+
+See [Simultaneous Events](events.md) before implementing this layer. Ordinary
+actions, effects, stores, and drivers do not depend on it.
+
+## Import stability
+
+Names listed in `foliot.__all__` and `foliot.events.__all__` are the intended
+public API. Modules and names beginning with an underscore are internal and may
+change without notice while the project is pre-alpha.