History

acamilo 77c8ee4558 session: resolve uncertain calls, and measure each mode in its own process Review fixes for SESSION-02. An expired caller deadline was becoming a failed epoch without the ipc-v1 section 6 resolution. That procedure existed and was correct and had exactly one caller, a test injection, so the deadline this slice introduced bypassed it and a merely slow participant lost its epoch. Deadlines is now the two-stage shape section 6 describes -- a probe, then a bounded resolve budget and attempt count -- call_owned returns a typed CallOutcome so an expiry is distinguishable from a refusal, and Prepare, Commit, Advance and the lifecycle calls all query the same request id against the same incarnation before the epoch can fail. This is also step-v1 section 7's Advance row, which was imperative about it. The coordinator peak-RSS column was measuring the measuring process. VmHWM never falls and every row shared one process, so the column was cumulative and the mode ranking reversed when the rows were reordered. Each row now runs in a measure-row child of its own. The corrected numbers say the opposite of what the first report claimed: the coordinator's own peak is roughly flat across the modes and lowest in process mode, and the cost of the split is the children. workers-v1 section 2 bounded Agent.Initialize's workerThreads by "within launcher allocation" and named no wire for it. Dated amendment: HelloResult.limits gains workerThreads, the worker reports what its launcher gave it, and the launcher refuses one that disagrees. The schema set, the shared fixtures and the TypeScript package move together; contractDigest changes, which ipc-v1 section 4 provides for. Also: the stale-epoch row now reaches the stale-epoch path against a live agent process and asserts exact codes on both halves; the router-restart row asserts the handle drop it claimed; frames are counted from the behaviour trace instead of calculated; the README says which suites run over which transports; bootstrap is fence-guarded; the shutdown reason is an Id rather than a silent fallback; and agent_mutations returns None rather than zero where the counter lives in another process.		2026-09-22 15:41:42 +00:00
..
bus-conformance.md	test(flybus): prove the two section 9 rows a review found cited but unproven	2026-09-22 12:39:07 +00:00
bus-v1.md	test(flybus): prove the two section 9 rows a review found cited but unproven	2026-09-22 12:39:07 +00:00
checkpoint-envelope-v1.md	docs(session-framework): seed derivation v1 and the FLYSESS1 checkpoint envelope	2026-09-22 12:47:48 +00:00
implementation.md	docs(design): session-framework specs (bus-v1, ipc-v1, step-v1, workers-v1, publishing-v1, state-media-v1) and the MaleCNS modular-session plans	2026-09-22 11:01:55 +00:00
ipc-v1.md	session: resolve uncertain calls, and measure each mode in its own process	2026-09-22 15:41:42 +00:00
publishing-v1.md	docs(design): session-framework specs (bus-v1, ipc-v1, step-v1, workers-v1, publishing-v1, state-media-v1) and the MaleCNS modular-session plans	2026-09-22 11:01:55 +00:00
README.md	Merge main: the bus slice, whose write-gate fix removes the flybus teardown flake under parallel load	2026-09-22 13:17:30 +00:00
seed-derivation-v1.md	docs(session-framework): seed derivation v1 and the FLYSESS1 checkpoint envelope	2026-09-22 12:47:48 +00:00
state-media-v1.md	docs(design): session-framework specs (bus-v1, ipc-v1, step-v1, workers-v1, publishing-v1, state-media-v1) and the MaleCNS modular-session plans	2026-09-22 11:01:55 +00:00
step-v1.md	session: both transports for every integration test, and the mid-step pause written into step-v1	2026-09-22 13:00:14 +00:00
workers-v1.md	session: resolve uncertain calls, and measure each mode in its own process	2026-09-22 15:41:42 +00:00

README.md

Application and session framework: architecture and contracts

Status: implementation specification, draft 2, 2026-09-18. This is a guide for future agents; none of the new runtime is implemented yet. Baseline code is 83090a9 on docs/improvement-suggestions. MUST/SHOULD requirements apply to the proposed new path, not retroactively to existing public feed, control API, or legacy numerical/checkpoint behavior.

Decisions from the architecture discussion

Applications orchestrate components and develop their presentation alongside them. “Director” is application code, not a mandatory framework service. A tournament is an example application, not the system's organizing data model.
One lightweight Rust bus supports RPC and pub/sub everywhere internally. Flybus replaces separate direct worker transports and an application broker. No NATS dependency.
Messages stay small; large artifacts live in managed storage. Delivery guards and explicit cache/retention owners keep data alive until its last actual use, then GC reclaims it.
The router moves messages and tracks generic ownership. It never schedules game frames, understands macro actions, composites video or operates a stream.
Sessions synchronize worlds; agent workers compute in parallel. One logical clock is not one execution thread. The coordinator alone commits complete world-control batches.
Game-aware executors receive current game state and task progress. Rich inspection data does not become undeclared neural input.
Native observations are framework outputs. Resizing, overlays, browser delivery, audio mixing, encoding, narration and streaming belong to the application/presentation layer.

Read in this order

Flybus v1 — authoritative wire/routing/RPC/pub-sub/artifact lifecycle contract.
Session RPCs — domain payloads, worker capability negotiation and safe retries.
Step protocol — session state machine, ordering and clocks.
Worker/task interfaces — exact method bodies and game-aware executor boundary.
Session media/state — observation timing and coherent recovery.
Application/presentation boundary — snapshots, flexible data and effects.
Implementation guide — sequenced build tasks and acceptance tests.
Flybus conformance report — the flybus crate audited sentence by sentence against bus-v1, with the test that proves each row, the measurements and the draft's own contradictions. A review artifact, not a contract.

Two derived specifications, written by CONTRACT-01 because the slices that need them cannot be built without them:

Seed derivation v1 — independent per-agent seeds from one recorded master seed and stable agent ids, with test vectors in both languages.
Checkpoint envelope v1 — the exact bytes of the new FLYSESS1 envelope and the durable commit sequence. FLYSIM01 is unchanged and stays separately readable.

For context: modular-session analysis and Melee audit. Each contract owns its named subject; step ordering wins over an informal diagram, and Flybus owns transport/resource rules. Resolve contradictions before implementation. The existing HTML report is an overview, not a contract.

1. Composition and processes

Application / supervisor                 Application presentation
  run policies, identity, history           UI, media composition, audience, stream
                \                           /
                   Flybus: RPC + pub/sub
                /          |              \
        Session        Agent workers      Environment worker
      coordinator      brain + encoder    emulator/world + native observations
      task/executors    + fixed readout
                           |
                  artifact store (same bus API)

This diagram is connectivity, not execution order. The step contract defines causal order. One router can host several independent sessions and application consumers; a deployment may choose one router per application for fault isolation. A router crash affects all its clients, so choose that boundary deliberately. In-process mode still exercises routing and ownership.

Defaults: coordinator per session, worker per fly, environment worker per world. Task and per-agent executors begin as coordinator-local libraries. An environment helper may own a separate emulator child process and adapt its native protocol. There is no second framework socket/lease API between those logical components.

Multiple players in one game share one environment/barrier. Independent games use independent sessions. Linked emulators require a composite backend with link-appropriate timing.

2. Ownership and authority

Owner	State and responsibility
Application	Composition, persistent personas/brain lineage, lifecycle policies, supported interventions, application schema/history
Session	Clock/epoch, port assignments, admission, task ledger, executor state, barriers and coherent recovery
Agent	Private membrane, RNG, rates, learning, sensory encoding, decoder and tick remainder
Environment	World, actual controller application, backend parser, native media and state capabilities
Flybus	Opaque endpoint/topic routing, delivery/call correlation, bounded queues, artifact-owner graph and GC
Storage client	Durable event/checkpoint writes and replay APIs; owns artifact handles during writes
Presentation	Application UI, display focus, clocks/buffers, media processing, audio/stream output and narrative cues

Immutable graph data can be shared; neural mutable state cannot. Do not concurrently dispatch the existing single-job WorkerPool through cloned handles from different brains.

Applications use declared session capabilities, not arbitrary emulator writes. Bus registration and method privileges preserve a single controller authority for a session. Browser/audience clients do not gain controller access by knowing a service name. Existing public rules remain.

3. Domain independence

The kernel knows no task or bus. The environment knows no neuron populations. A task interprets game state and requests outcomes/recovery; its executor translates a selected decision using read-only current game/progress context. The coordinator orders and applies these results. The bus handles no such semantics. Presentation combines framework observations with an application-owned schema and can change without changing simulation behavior.

Persistent AssetRefs identify installed release content. Transient Flybus ArtifactRefs identify live bytes with ownership. Domain epoch/step identity and bus route/store incarnation are different: the first protects simulation order, the second protects delivery/resource validity. Never substitute game-frame number, persona identity or array position for either.

4. Initial scope and compatibility

First build a generic bus example (RPC + pub/sub + artifact retained beyond message lifetime), then a synthetic two-agent session using it. One local machine, Unix sockets/in-memory parity, immutable file-backed artifacts, fixed cadence, 1-ms LIF, direct control and exact-checkpoint synthetic backend are sufficient. Dolphin, MaleCNS and richer effects are later integrations.

Deferred: cross-machine artifact access, durable broker queues, wildcard/queue-group routing, dynamic native plugins, hot-join, speculative netplay rollback and pooled GPU buffers.

Keep legacy-gameboy-v1 distinct from lockstep-v1. Preserve TypeScript as oracle, existing default versions, historical arithmetic/fingerprints and FLYSIM01 reader. New identities include sensor, readout/executor/task/scheduler semantics. New public feed v2 is an application/presentation gateway contract built on the same internal bus; it does not replace the bus or expose it raw.

5. Reuse criterion

Adding a third environment/application requires a backend, task/profile, composition and application presentation. It must not require game-specific edits to the coordinator, router, artifact manager, kernel, generic stores or transport. Schematized task extensions are valid; an unchecked data blob or universal tournament schema is not a substitute for interfaces.