kith-fw 1.0.0__tar.gz

kith_fw-1.0.0/.gitignore

@@ -0,0 +1,38 @@
+# Build directories (CMake + CLion presets)
+build/
+cmake-build-*/
+*/build/
+
+# Generated compile database (regenerated by CMake)
+compile_commands.json
+
+# Python bytecode and virtualenvs
+*.pyc
+__pycache__/
+.venv/
+# Dedicated venv for the free-threaded interpreter stage of verify.sh.
+.venv-ft/
+.cache/
+
+# Build artifacts (tracked in releases, not in the source tree)
+*.so
+*.a
+*.dylib
+
+# Editor/tag files
+.tags
+.idea/
+.vscode/
+
+# Secrets (never commit real env files; examples are tracked)
+*.env
+!*.env.example
+
+# Local profiling artifacts (coverage + LLVM profile data)
+.coverage
+default.profraw
+kith.profdata
+profraw/
+
+# ctest artifact directory (written when ctest runs from the source root)
+Testing/

kith_fw-1.0.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to kith are documented in this file. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-21
+
+The first stable release of kith: a scalable server framework for real-time,
+stateful multiplayer worlds. A C23 core owns the performance-critical systems
+— transport, the io_uring reactor, spatial indexing, the world stream fabric,
+and the simulation — and a Python layer hosts game logic, with C simulation
+models as shared libraries plugging into the same ABI. The framework ships
+one opinionated default runtime topology, the five-plane world stream fabric
+(Sim, Fabric, Gateway, Coord, Control), built around interest management:
+the world is divided into cells that publish state once, and gateways
+subscribe to cells and compose a per-player view. Embedded and distributed
+topologies run the same game code, the simulation is deterministic with
+replay and hash-regression coverage, and guides for Python extension, C
+simulation models, the wire protocol, operations, scaling, replay, and
+agentic testing document the whole surface.
+
+### Scaling gates
+
+Claims about scale are certified by two gate classes, with the certified
+configuration part of the claim. The procedure lives in
+`docs/guides/scaling_checklist.md`; the numbers here are the release
+thresholds.
+
+**dense-1000** (embedded, stress gate) — 1000 actors on one embedded server:
+`session_ok >= 99%`, `selected_clients >= 95%`, `bootstrap_ms_p95 < 3000 ms`,
+no crash or corruption. Delivery-fidelity metrics are reported, not
+thresholded: the embedded single-cell pileup is the adversarial case, not
+the topology the fidelity claim is made for.
+
+**distributed-2000** (fidelity gate) — 2000 actors across two server
+instances, per instance: `session_ok >= 99%`, `selected_clients >= 95%`,
+`move_missing_ratio_certified < 10%`, `bootstrap_ms_p95 < 3000 ms`, no
+continuity flicker. The certified move-missing reading is the
+publisher-minted `update_seq` delta between self echoes; the event-count
+metric is reported alongside it and floors under saturation.
+
+The certified configuration: free-threaded CPython 3.14t (GIL disabled),
+the native C movement-apply path, two delivery-executor workers, one load
+driver per instance cohort, pinned cores per the recorded reference
+envelope. The per-operation budgets and the per-instance capacity model
+that records both apply-path regimes live in
+`docs/architecture/performance_budgets.md`.
+
+The release certification ran on the release tree under this configuration
+on the recorded reference host, 2026-09-21: distributed-2000 twice
+back-to-back, both passing every threshold per instance — session_ok
+100.00%, selected_clients 100.00% of 2000 eligible,
+move_missing_ratio_certified 0.00%, no continuity flicker, bootstrap_ms_p95
+304 ms and 331 ms — and dense-1000 once, passing its stress gate
+(session_ok 100.00%, selected_clients 100.00% of 996 eligible,
+bootstrap_ms_p95 470 ms; its delivery-fidelity readings are the
+reported-not-thresholded dense semantics described above).
+
+### Out-of-box visual example
+
+The released wheel ships a runnable example alongside the library:
+`kith.examples.visual` boots an embedded-topology world — a seamless plain,
+ambient actors under the same momentum model the players use, cell-scoped
+chat, a metrics route — with one command and no written code, and the
+console entry point `kith-visual` lists and launches its scenarios (crowd,
+density, churn, membership, reconnect, tick ladder, soak). The graphical
+client renders the world through the certified harness client engine and
+carries the measurement HUD — per-actor staleness, arrival jitter, input
+echo, the snap-event log, and the live delivery counters; its window
+renderer rides an opt-in extra, so the base install stays dependency-free.
+The agentic client engine itself moved into the package under a private
+home, re-exported at its existing tooling path, so the shipped example and
+the certified harness drive one implementation.
+
+### Known residuals
+
+Measured, sub-threshold, and named — statements of scope, not open defects:
+
+- The single-driver load-driver configuration still shows occasional
+  sub-threshold delivery pauses at roughly half their measured amplitude
+  (one asyncio loop driving the full cohort delays the movement cadence).
+  The certified recipe runs one driver process per instance cohort, and
+  the certified runs read zero continuity flicker.
+- The gateway delivery executor's batch-release pause is measured in gate
+  traces; the pause has no attributed trigger.
+- Gate-run fidelity ledgers exist in two formats; numbers from the earlier
+  format are not directly comparable with later runs. The scaling guide's
+  measurement caveats carry the boundary.
+- The distributed gate certifies horizontal scaling: one server process
+  per instance with per-instance loopback coordination buses. Cross-machine
+  coordination transport is not part of the certified claim; the
+  `KITH_COORD_BUS_TRANSPORT` enum's additive extension point is the seam
+  for it.
+- On the Python movement-apply path, per-instance fidelity holds to roughly
+  300 clients per instance before compose-budget deferrals breach the
+  missing-move bar; the native C apply path — the certified configuration —
+  reads 0.00% at 1000 per instance. The capacity model records both regimes
+  and what raises each.
+
+### Platform
+
+kith is Linux-only. The reactor runs on io_uring; the build links
+`liburing`, `libpq`, and `libhiredis`; release wheels bundle the framework's
+own shared libraries and keep those three dynamically linked. Production
+builds are expected to compile with the hardening flags the project ships
+(full RELRO, stack protector, `-D_FORTIFY_SOURCE=3`, PIE, CFI where the
+toolchain supports it).

kith_fw-1.0.0/CMakeLists.txt

@@ -0,0 +1,154 @@
+cmake_minimum_required(VERSION 4.4)
+
+# The project version is the single source of truth that flows to every
+# consumer channel: the library SONAMEs (kith_apply_abi reads
+# PROJECT_VERSION), the pkg-config .pc file (Version:), the CMake package
+# version file (write_basic_package_version), and the find_package(kith
+# VERSION ...) check a downstream project issues. It tracks the release
+# target the release infrastructure in this cluster produces.
+project(kith VERSION 1.0.0 LANGUAGES C)
+
+set(CMAKE_C_STANDARD 23)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_C_VISIBILITY_PRESET hidden)
+
+# GNUInstallDirs provides CMAKE_INSTALL_LIBDIR / INCLUDEDIR / etc. Used by
+# the per-library install(TARGETS EXPORT kithTargets) calls in
+# cmake/lib_*.cmake and by the find_package / pkg-config consumer block at
+# the bottom of this file; included here so the lib_*.cmake fragments pick
+# up the variables without each re-including it (the local re-includes are
+# idempotent and document each fragment's dependency).
+include(GNUInstallDirs)
+
+# Framework-wide conventions: warnings, hardening, visibility, sanitizers,
+# abi helpers, linker/LTO/reproducible-build settings.
+# framework.cmake is the single source of truth and includes the rest.
+include(cmake/framework.cmake)
+
+# Per-module shared-library targets. Each lib_<module>.cmake fragment
+# defines one layer-2 SHARED library and its install rules; framework.cmake
+# supplies the kith_apply_abi helper they all use.
+include(cmake/lib_util.cmake)
+include(cmake/lib_config.cmake)
+include(cmake/lib_logger.cmake)
+include(cmake/lib_metrics.cmake)
+include(cmake/lib_proto.cmake)
+include(cmake/lib_net.cmake)
+include(cmake/lib_reactor.cmake)
+include(cmake/lib_worker.cmake)
+include(cmake/lib_state.cmake)
+include(cmake/lib_db.cmake)
+include(cmake/lib_client.cmake)
+include(cmake/lib_sim.cmake)
+include(cmake/lib_fabric.cmake)
+include(cmake/lib_aoi.cmake)
+include(cmake/lib_gateway.cmake)
+include(cmake/lib_coord.cmake)
+# The control plane is an optional layer-2 library. When
+# CONTROL_PLANE_ENABLED is OFF the library is not built and contributes
+# zero code to the build (no source-level #ifdef guards; the library is
+# simply absent from the build).
+option(CONTROL_PLANE_ENABLED "Build the control plane library (HTTP/WS introspection)" ON)
+if(CONTROL_PLANE_ENABLED)
+    include(cmake/lib_control.cmake)
+endif()
+# Composition root. The server is the single layer-3 library a game links
+# against; it wires every plane library above and must be included after
+# them (and after the optional control block) so their targets exist.
+include(cmake/lib_server.cmake)
+
+
+# Per-checker build targets (check-layout-consistency, check-clang-tidy, ...,
+# check-all). Each runs the corresponding tools/*.py checker (or clang-tidy /
+# clang-format) and fails the build on a violation. The format/verify split
+# targets (`format`, the single fix entry point, plus the verify-only
+# check-ruff-format / check-ruff / check-trivial-fixers targets that check-all
+# depends on) come from the same dev toolchain: both fragments drive the
+# tools/*.py checkers, the scripts/ helpers, and git ls-files, and both
+# fail at use when one of their tools is missing. The full checkout ships
+# tools/ and scripts/ together; a source distribution carries only the
+# build inputs, so the fragments are included only when tools/ is present.
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tools")
+    include(cmake/checks.cmake)
+    include(cmake/format.cmake)
+endif()
+
+# C unit tests. enable_testing() must appear at the top level so ctest
+# discovers tests registered by the tests/c subdirectory. The optional
+# subtrees below exist only in a full checkout; a source distribution ships
+# the build inputs alone, so each is composed only when its CMakeLists is
+# present.
+enable_testing()
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tests/c/CMakeLists.txt")
+    add_subdirectory(tests/c)
+endif()
+
+# libFuzzer targets. Built only when KITH_ENABLE_FUZZ is set (the fuzz
+# preset); the subdirectory hard-fails on non-Clang compilers because
+# libFuzzer ships with Clang alone.
+if(KITH_ENABLE_FUZZ)
+    add_subdirectory(tests/fuzz)
+endif()
+
+# Examples. The C boots link against the composition root (kith_server) so
+# the example executables exercise the public server surface end-to-end; the
+# Python examples are plain modules run by pytest or `python -m`.
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/examples/CMakeLists.txt")
+    add_subdirectory(examples)
+endif()
+
+# Perf tooling: the C-native bench driver links the layer-2 sim + fabric
+# libraries directly (no composition root; the bench measures the raw
+# publish path, not the server wiring).
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tools/CMakeLists.txt")
+    add_subdirectory(tools)
+endif()
+
+
+# --- Downstream consumer story: find_package(kith) + pkg-config -----------
+# Every layer-2 (and the layer-3 composition root) library above installed
+# with `EXPORT kithTargets`; this block assembles that export set into a
+# CMake package a downstream finds with `find_package(kith 1.0.0 REQUIRED)`,
+# and a pkg-config .pc file a hand-written Makefile or autotools consumer
+# queries with `pkg-config --cflags --libs kith`. The version flowing into
+# both channels is PROJECT_VERSION (set above), so the SONAME, the pkg-config
+# Version, the find_package version check, and the kith_apply_abi SOVERSION
+# all read from one source.
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+install(EXPORT kithTargets
+    FILE kithTargets.cmake
+    NAMESPACE kith::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/kith)
+
+configure_package_config_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/kithConfig.cmake.in
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kithConfig.cmake
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/kith)
+
+write_basic_package_version_file(
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kithConfigVersion.cmake
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion)
+
+install(FILES
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kithConfig.cmake
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kithConfigVersion.cmake
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/kith)
+
+# pkg-config .pc file. The template is processed with @-only substitution
+# (the .pc format treats ${} as its own variable expansion), then installed
+# to <prefix>/lib/pkgconfig/kith.pc where `pkg-config --modversion kith`
+# finds it.
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/kith.pc.in
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kith.pc
+    @ONLY)
+install(FILES
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/kith.pc
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)

kith_fw-1.0.0/CMakePresets.json

@@ -0,0 +1,187 @@
+{
+  "version": 6,
+  "cmakeMinimumRequired": {
+    "major": 4,
+    "minor": 4,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "_base",
+      "hidden": true,
+      "description": "Shared defaults: Ninja generator, Clang as the development compiler. Concrete presets inherit and add their own binaryDir and cacheVariables.",
+      "generator": "Ninja",
+      "environment": {
+        "CC": "clang"
+      }
+    },
+    {
+      "name": "debug",
+      "displayName": "Debug (default development)",
+      "description": "Unoptimized build with full debug info. No LTO. _FORTIFY_SOURCE is disabled for this preset: fortification requires optimization and is inert here. All other hardening flags remain active. The preset used for day-to-day development and the default for ctest.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_FORTIFY": "OFF"
+      }
+    },
+    {
+      "name": "release",
+      "displayName": "Release (optimized + LTO)",
+      "description": "Optimized build with link-time optimization enabled. Used for CI, benchmarks, and release artifacts.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "ON"
+      }
+    },
+    {
+      "name": "asan",
+      "displayName": "AddressSanitizer",
+      "description": "Debug build with AddressSanitizer. _FORTIFY_SOURCE is disabled for this preset by cmake/sanitizers.cmake; all other hardening flags remain active.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/asan",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_ASAN": "ON"
+      }
+    },
+    {
+      "name": "asan-ubsan",
+      "displayName": "AddressSanitizer + UndefinedBehaviorSanitizer",
+      "description": "Debug build with AddressSanitizer and UndefinedBehaviorSanitizer. UBSan findings abort instead of printing and continuing (cmake/sanitizers.cmake), so ctest fails on the first report; leak detection runs as part of ASan on Linux. _FORTIFY_SOURCE is disabled for this preset; all other hardening flags remain active. The preset behind the weekly sanitizer workflow.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/asan-ubsan",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_ASAN": "ON",
+        "KITH_ENABLE_UBSAN": "ON"
+      }
+    },
+    {
+      "name": "tsan",
+      "displayName": "ThreadSanitizer",
+      "description": "Debug build with ThreadSanitizer for data-race detection. _FORTIFY_SOURCE is disabled for this preset by cmake/sanitizers.cmake. The weekly sanitizer lane's tsan job drives the preset over the C test suite: reports collect a full census without halting, and the run exits nonzero through ThreadSanitizer's default exit code.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/tsan",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_TSAN": "ON"
+      }
+    },
+    {
+      "name": "coverage",
+      "displayName": "Coverage",
+      "description": "Debug build with coverage instrumentation (lcov / llvm-cov). _FORTIFY_SOURCE is disabled for this preset: fortification requires optimization and is inert here. All other hardening flags remain active. Coverage is reported in CI but not gated.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/coverage",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_COVERAGE": "ON",
+        "KITH_ENABLE_FORTIFY": "OFF"
+      }
+    },
+    {
+      "name": "fuzz",
+      "displayName": "libFuzzer (Clang)",
+      "description": "Debug build with libFuzzer instrumentation for protocol-decoder fuzzing. libFuzzer requires Clang, so the _base CC=clang is essential here. Runs AddressSanitizer alongside the fuzzer by default.",
+      "inherits": "_base",
+      "binaryDir": "${sourceDir}/build/fuzz",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "KITH_ENABLE_FUZZ": "ON",
+        "KITH_ENABLE_ASAN": "ON"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "debug",
+      "configurePreset": "debug"
+    },
+    {
+      "name": "release",
+      "configurePreset": "release"
+    },
+    {
+      "name": "asan",
+      "configurePreset": "asan"
+    },
+    {
+      "name": "asan-ubsan",
+      "configurePreset": "asan-ubsan"
+    },
+    {
+      "name": "tsan",
+      "configurePreset": "tsan"
+    },
+    {
+      "name": "coverage",
+      "configurePreset": "coverage"
+    },
+    {
+      "name": "fuzz",
+      "configurePreset": "fuzz"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "debug",
+      "configurePreset": "debug",
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "release",
+      "configurePreset": "release",
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "asan",
+      "configurePreset": "asan",
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "asan-ubsan",
+      "configurePreset": "asan-ubsan",
+      "environment": {
+        "ASAN_OPTIONS": "detect_leaks=1",
+        "UBSAN_OPTIONS": "print_stacktrace=1:halt_on_error=1"
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "tsan",
+      "configurePreset": "tsan",
+      "environment": {
+        "TSAN_OPTIONS": "second_deadlock_stack=1"
+      },
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "coverage",
+      "configurePreset": "coverage",
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "fuzz",
+      "configurePreset": "fuzz",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}