Implement M9.7 dev region sessions with durable no-effect intentions

Run a non-blocking TLS 1.3 session server inside evo-server's loop:
environment views come from the region's own field/terrain stores with an
explicitly empty organism presentation; admitted intentions ride the next
synthetic input (content unchanged) and return a durable no-effect outcome
from the host's final acknowledgement, or not_committed when dropped.
Sessions are bound to their connection, epochs close stale sessions, and
connections have bounded output, input rate and deadlines.

SessionClient and evo-client --connect consume one single-use grant per
Hello (refusals before admission keep it), reset to a fresh baseline on
every session, keep stale views visible and report in-flight intentions as
unknown after loss. evo-dev-session generates dev credentials, grant
bundles and runs a restart probe. The dev deployment gains a drill-time,
loopback-only listener with an optional Secret, enforced by the policy
check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and
the capacity close reason before any deployment. ADR-0083 records the
maintainer-confirmed decisions; M8-dev/stage remains not passed and no
cluster change was made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-01 20:12:18 -04:00
co-authored by Claude Opus 5.5
parent 8fbe093cc8
commit 8e319322f4
49 changed files with 3467 additions and 130 deletions
+29
View File
@@ -0,0 +1,29 @@
#pragma once
#include "evo/network/dev_grant.hpp"
#include <array>
#include <chrono>
#include <cstdint>
#include <expected>
#include <string>
#include <string_view>
// Dev-only session credentials (ADR-0083): a self-signed dev CA, a server
// certificate/key for one name, and a 32-byte grant HMAC key. Generated on an
// operator machine for the dev namespace Secret; refused for stage and World0.
namespace evo::network {
struct DevCredentials {
std::string authority_pem; // Public: given to dev clients.
std::string server_certificate_pem; // Public.
std::string server_key_pem; // Secret.
std::array<std::uint8_t, dev_key_bytes> grant_key{}; // Secret.
};
[[nodiscard]] std::expected<DevCredentials, GrantError>
generate_dev_credentials(DeploymentEnvironment environment, std::string_view server_name,
std::uint32_t days, std::chrono::system_clock::time_point now);
// Lowercase hex, 64 digits; surrounding whitespace is ignored when parsing.
[[nodiscard]] std::string format_grant_key(std::span<const std::uint8_t> key);
[[nodiscard]] std::expected<std::array<std::uint8_t, dev_key_bytes>, GrantError>
parse_grant_key(std::string_view text);
// Random 64-bit nonzero grant ids from the PSA RNG.
[[nodiscard]] std::expected<std::uint64_t, GrantError> random_grant_id();
} // namespace evo::network
+14 -2
View File
@@ -27,7 +27,8 @@ enum class MessageType : std::uint8_t {
intent_result,
environment_view,
organism_view,
close
close,
intent_outcome
};
enum class ProtocolError : std::uint8_t {
truncated,
@@ -119,7 +120,16 @@ enum class CloseReason : std::uint8_t {
duplicate_session,
stale_epoch,
rate_limited,
server_shutdown
server_shutdown,
capacity
};
// Final, after the host's durable commit (or loss): the M9.7 dev region has no
// movable organism, so a committed intention has no biological effect.
enum class IntentFinality : std::uint8_t { committed_no_effect, not_committed };
struct IntentOutcome {
std::uint64_t sequence{};
IntentFinality finality{};
std::uint64_t tick{}, commit_sequence{}; // Zero when not committed.
};
[[nodiscard]] std::expected<std::vector<std::uint8_t>, ProtocolError> encode(const Hello& m);
@@ -127,6 +137,7 @@ enum class CloseReason : std::uint8_t {
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentMessage& m);
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentResult& m);
[[nodiscard]] std::vector<std::uint8_t> encode(CloseReason reason);
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentOutcome& m);
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
const client::EnvironmentPresentation& view);
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
@@ -139,6 +150,7 @@ enum class CloseReason : std::uint8_t {
[[nodiscard]] std::expected<IntentMessage, ProtocolError> decode_intent(FrameView frame);
[[nodiscard]] std::expected<IntentResult, ProtocolError> decode_intent_result(FrameView frame);
[[nodiscard]] std::expected<CloseReason, ProtocolError> decode_close(FrameView frame);
[[nodiscard]] std::expected<IntentOutcome, ProtocolError> decode_intent_outcome(FrameView frame);
[[nodiscard]] std::expected<std::pair<ViewHeader, client::EnvironmentPresentation>, ProtocolError>
decode_environment_view(FrameView frame);
[[nodiscard]] std::expected<std::pair<ViewHeader, client::OrganismPresentation>, ProtocolError>
+74
View File
@@ -0,0 +1,74 @@
#pragma once
#include "evo/client/environment_view.hpp"
#include "evo/client/input.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/network/dev_grant.hpp"
#include "evo/network/protocol.hpp"
#include "evo/network/tls_channel.hpp"
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <string>
#include <vector>
// M9.7 dev session client (ADR-0083). Non-blocking; the desktop host calls poll()
// once per frame. Holds presentation copies only: it never predicts, simulates or
// treats a local value as authority. Each Hello consumes one single-use grant (except
// after a `server_shutdown`/`capacity` refusal, when the server never recorded it);
// every new session starts from a fresh server baseline.
namespace evo::network {
struct SessionClientConfig {
std::string host;
std::uint16_t port{};
ClientTrust trust;
std::vector<DevGrant> grants; // Consumed in order, one per Hello.
std::uint32_t lead_ticks{4}; // Intended tick = newest view tick + lead.
std::chrono::milliseconds attempt_deadline{5000}; // Connect to Welcome.
std::chrono::milliseconds first_retry{500}, max_retry{8000};
};
enum class SessionPhase : std::uint8_t { backoff, connecting, established, exhausted };
struct ClientEvent {
enum class Kind : std::uint8_t {
welcome,
closed,
lost, // Transport/TLS failure or deadline: no Close received.
result, // IntentResult.
outcome, // IntentOutcome (durable or not committed).
unknown, // Admitted intention whose outcome died with its connection.
exhausted // No grants left; reconnection stops.
} kind{};
Welcome welcome{};
CloseReason reason{};
IntentResult result{};
IntentOutcome outcome{};
std::uint64_t sequence{};
};
enum class SessionClientError : std::uint8_t { configuration };
class SessionClient {
public:
static constexpr std::size_t max_outstanding = 256;
[[nodiscard]] static std::expected<std::unique_ptr<SessionClient>, SessionClientError>
create(SessionClientConfig config);
SessionClient(const SessionClient&) = delete;
SessionClient& operator=(const SessionClient&) = delete;
~SessionClient();
void poll(std::chrono::steady_clock::time_point now);
// Sends when established and a view has arrived; never queued across connections.
[[nodiscard]] bool send(const client::Intention& intention);
[[nodiscard]] SessionPhase phase() const noexcept;
[[nodiscard]] const client::EnvironmentLayer& environment() const noexcept;
[[nodiscard]] const client::OrganismLayer& organisms() const noexcept;
[[nodiscard]] std::optional<Welcome> welcome() const noexcept;
[[nodiscard]] std::optional<ViewHeader> latest_view() const noexcept;
[[nodiscard]] std::size_t grants_left() const noexcept;
[[nodiscard]] std::vector<ClientEvent> take_events();
private:
struct Impl;
explicit SessionClient(std::unique_ptr<Impl> impl);
std::unique_ptr<Impl> impl_;
};
} // namespace evo::network
+76
View File
@@ -0,0 +1,76 @@
#pragma once
#include "evo/network/admission.hpp"
#include "evo/network/dev_grant.hpp"
#include "evo/network/tcp.hpp"
#include "evo/network/tls_channel.hpp"
#include <array>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <deque>
#include <expected>
#include <memory>
#include <optional>
#include <string>
#include <vector>
// M9.7 dev session server (ADR-0083). Host-agnostic and non-blocking: the region
// host calls poll() from its own loop, publishes views of its state, lets admitted
// intentions ride host inputs via carry(), and reports durable/lost outcomes. It
// never touches simulation state and never decides an outcome.
namespace evo::network {
using RequestId = std::array<std::uint8_t, 16>;
struct SessionServerConfig {
std::string listen; // Numeric address:port.
ServerCredentials credentials;
AdmissionConfig admission; // `epoch` is ignored: it follows RegionFacts.
std::size_t max_connections{4};
std::chrono::milliseconds hello_deadline{5000}; // Accept to Welcome.
std::size_t max_output_bytes{std::size_t{1} << 20};
std::size_t max_input_bytes_per_second{65536};
std::size_t max_pending_intents{64}; // Admitted, not yet carried.
std::size_t max_carried_intents{1024}; // Carried, awaiting durable/lost.
};
// The host's current authority facts, read once per loop iteration.
struct RegionFacts {
bool ready{};
std::uint64_t epoch{}, simulated_tick{}, committed_tick{}, commit_sequence{};
};
enum class SessionServerError : std::uint8_t { configuration, listen, credentials };
struct SessionEvent {
enum class Kind : std::uint8_t { opened, closed, refused } kind{};
std::uint64_t session{}, subject{};
CloseReason reason{};
};
class SessionServer {
public:
[[nodiscard]] static std::expected<std::unique_ptr<SessionServer>, SessionServerError>
create(SessionServerConfig config, DevGrantKey key);
SessionServer(const SessionServer&) = delete;
SessionServer& operator=(const SessionServer&) = delete;
~SessionServer();
[[nodiscard]] std::uint16_t port() const noexcept;
// Accepts, handshakes, admits and writes; never blocks. `now_seconds` is wall
// time for grant validity; `now` is monotonic time for connection deadlines.
void poll(const RegionFacts& facts, std::uint64_t now_seconds,
std::chrono::steady_clock::time_point now);
// The latest views; each session receives only the newest (older unsent views are
// replaced, never queued). New sessions receive the latest as their baseline.
void publish(const client::EnvironmentPresentation& environment,
const client::OrganismPresentation& organisms, const RegionFacts& facts);
// The oldest admitted intention whose intended tick is <= `tick`, to ride the host
// input for `tick`. The host input's content stays host-chosen.
[[nodiscard]] std::optional<RequestId> carry(std::uint64_t tick);
// Host final acknowledgement / drop for a request id; ids not carried here are ignored.
void committed(const RequestId& request, std::uint64_t tick, std::uint64_t commit_sequence);
void not_committed(const RequestId& request);
[[nodiscard]] std::vector<SessionEvent> take_events();
[[nodiscard]] std::size_t connections() const noexcept;
[[nodiscard]] std::size_t sessions() const noexcept;
private:
struct Impl;
explicit SessionServer(std::unique_ptr<Impl> impl);
std::unique_ptr<Impl> impl_;
};
} // namespace evo::network
+54
View File
@@ -0,0 +1,54 @@
#pragma once
#include "evo/network/tls_channel.hpp"
#include <cstdint>
#include <expected>
#include <memory>
#include <string>
#include <string_view>
// Minimal non-blocking TCP for the M9.7 dev session (ADR-0083), Windows and Linux.
// Plaintext bytes only: every session byte travels inside TlsChannel. No socket
// handle crosses this header. One owner thread per object.
namespace evo::network {
class TcpStream final : public ByteTransport {
public:
// Resolves `host` (blocking, bounded by the system resolver) and starts a
// non-blocking connect. Reads/writes return 0 until the connection completes.
[[nodiscard]] static std::expected<std::unique_ptr<TcpStream>, TransportError>
connect(const std::string& host, std::uint16_t port);
TcpStream(const TcpStream&) = delete;
TcpStream& operator=(const TcpStream&) = delete;
~TcpStream() override;
[[nodiscard]] std::expected<std::size_t, TransportError>
write(std::span<const std::uint8_t> bytes) override;
[[nodiscard]] std::expected<std::size_t, TransportError>
read(std::span<std::uint8_t> bytes) override;
private:
friend class TcpListener;
TcpStream(std::intptr_t socket, bool connecting) : socket_{socket}, connecting_{connecting} {}
[[nodiscard]] std::expected<bool, TransportError> ready();
std::intptr_t socket_;
bool connecting_;
};
class TcpListener {
public:
// Numeric address only ("127.0.0.1:7400", "[::1]:7400", "0.0.0.0:7400"); port 0
// picks a free port.
[[nodiscard]] static std::expected<std::unique_ptr<TcpListener>, TransportError>
listen(std::string_view address);
TcpListener(const TcpListener&) = delete;
TcpListener& operator=(const TcpListener&) = delete;
~TcpListener();
// A pending connection, or nullptr when none is waiting.
[[nodiscard]] std::expected<std::unique_ptr<TcpStream>, TransportError> accept();
[[nodiscard]] std::uint16_t port() const noexcept {
return port_;
}
private:
TcpListener(std::intptr_t socket, std::uint16_t port) : socket_{socket}, port_{port} {}
std::intptr_t socket_;
std::uint16_t port_;
};
} // namespace evo::network