a11-kit 0.1.1__tar.gz

a11_kit-0.1.1/.clang-format

@@ -0,0 +1,103 @@
+# Google C/C++ Code Style settings
+# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+# Author: Kehan Xue, kehan.xue (at) gmail.com
+
+Language: Cpp
+BasedOnStyle: Google
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: None
+AlignOperands: Align
+AllowAllArgumentsOnNextLine: true
+AllowAllConstructorInitializersOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never  # To avoid conflict, set this "Never" and each "if statement" should include brace when coding
+AllowShortLambdasOnASingleLine: Inline
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterCaseLabel: false
+  AfterClass: false
+  AfterStruct: false
+  AfterControlStatement: Never
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  BeforeLambdaBody: false
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeColon
+BreakInheritanceList: BeforeColon
+ColumnLimit: 80
+CompactNamespaces: false
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false  # Make sure the * or & align on the left
+EmptyLineBeforeAccessModifier: LogicalBlock
+FixNamespaceComments: true
+#IncludeBlocks: Regroup
+IncludeCategories:
+- Regex: '^"'
+  Priority: 3
+  SortPriority: 0
+  CaseSensitive: false
+
+- Regex: '^<[^/]+[^(\.h)]>$'
+  Priority: 1
+  SortPriority: 0
+  CaseSensitive: false
+
+- Regex: '^<[^/]+>$'
+  Priority: 2
+  SortPriority: 0
+  CaseSensitive: false
+
+- Regex: '^<.+/.+>$'
+  Priority: 2
+  SortPriority: 0
+  CaseSensitive: false
+IndentCaseLabels: true
+IndentPPDirectives: None
+IndentWidth: 2
+KeepEmptyLinesAtTheStartOfBlocks: true
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PointerAlignment: Left
+ReflowComments: false
+SeparateDefinitionBlocks: Always   # Only support since clang-format 14
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceBeforeSquareBrackets: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: c++11
+TabWidth: 4
+UseTab: Never

a11_kit-0.1.1/.clang-tidy

@@ -0,0 +1,148 @@
+# Generated from CLion Inspection settings
+---
+Checks: '-*,
+abseil-*,
+bugprone-argument-comment,
+bugprone-assert-side-effect,
+bugprone-bad-signal-to-kill-thread,
+bugprone-branch-clone,
+bugprone-copy-constructor-init,
+bugprone-dangling-handle,
+bugprone-dynamic-static-initializers,
+bugprone-fold-init-type,
+bugprone-forward-declaration-namespace,
+bugprone-forwarding-reference-overload,
+bugprone-inaccurate-erase,
+bugprone-incorrect-roundings,
+bugprone-integer-division,
+bugprone-lambda-function-name,
+bugprone-macro-parentheses,
+bugprone-macro-repeated-side-effects,
+bugprone-misplaced-operator-in-strlen-in-alloc,
+bugprone-misplaced-pointer-arithmetic-in-alloc,
+bugprone-misplaced-widening-cast,
+bugprone-move-forwarding-reference,
+bugprone-multiple-statement-macro,
+bugprone-no-escape,
+bugprone-parent-virtual-call,
+bugprone-posix-return,
+bugprone-reserved-identifier,
+bugprone-sizeof-container,
+bugprone-sizeof-expression,
+bugprone-spuriously-wake-up-functions,
+bugprone-string-constructor,
+bugprone-string-integer-assignment,
+bugprone-string-literal-with-embedded-nul,
+bugprone-suspicious-enum-usage,
+bugprone-suspicious-include,
+bugprone-suspicious-memset-usage,
+bugprone-suspicious-missing-comma,
+bugprone-suspicious-semicolon,
+bugprone-suspicious-string-compare,
+bugprone-suspicious-memory-comparison,
+bugprone-suspicious-realloc-usage,
+bugprone-swapped-arguments,
+bugprone-terminating-continue,
+bugprone-throw-keyword-missing,
+bugprone-too-small-loop-variable,
+bugprone-undefined-memory-manipulation,
+bugprone-undelegated-constructor,
+bugprone-unhandled-self-assignment,
+bugprone-unused-raii,
+bugprone-unused-return-value,
+bugprone-use-after-move,
+bugprone-virtual-near-miss,
+cert-dcl21-cpp,
+cert-dcl58-cpp,
+cert-err34-c,
+cert-err52-cpp,
+cert-err60-cpp,
+cert-flp30-c,
+cert-msc50-cpp,
+cert-msc51-cpp,
+cert-str34-c,
+cppcoreguidelines-interfaces-global-init,
+cppcoreguidelines-narrowing-conversions,
+cppcoreguidelines-pro-type-member-init,
+cppcoreguidelines-pro-type-static-cast-downcast,
+cppcoreguidelines-slicing,
+google-default-arguments,
+google-explicit-constructor,
+google-runtime-operator,
+hicpp-exception-baseclass,
+hicpp-multiway-paths-covered,
+misc-misplaced-const,
+misc-new-delete-overloads,
+misc-no-recursion,
+misc-non-copyable-objects,
+misc-throw-by-value-catch-by-reference,
+misc-unconventional-assign-operator,
+misc-uniqueptr-reset-release,
+modernize-avoid-bind,
+modernize-concat-nested-namespaces,
+modernize-deprecated-headers,
+modernize-deprecated-ios-base-aliases,
+modernize-loop-convert,
+modernize-make-shared,
+modernize-make-unique,
+modernize-pass-by-value,
+modernize-raw-string-literal,
+modernize-redundant-void-arg,
+modernize-replace-auto-ptr,
+modernize-replace-disallow-copy-and-assign-macro,
+modernize-replace-random-shuffle,
+modernize-return-braced-init-list,
+modernize-shrink-to-fit,
+modernize-unary-static-assert,
+modernize-use-auto,
+modernize-use-bool-literals,
+modernize-use-emplace,
+modernize-use-equals-default,
+modernize-use-equals-delete,
+modernize-use-nodiscard,
+modernize-use-noexcept,
+modernize-use-nullptr,
+modernize-use-override,
+modernize-use-transparent-functors,
+modernize-use-uncaught-exceptions,
+mpi-buffer-deref,
+mpi-type-mismatch,
+openmp-use-default-none,
+performance-faster-string-find,
+performance-for-range-copy,
+performance-implicit-conversion-in-loop,
+performance-inefficient-algorithm,
+performance-inefficient-string-concatenation,
+performance-inefficient-vector-operation,
+performance-move-const-arg,
+performance-move-constructor-init,
+performance-no-automatic-move,
+performance-noexcept-move-constructor,
+performance-trivially-destructible,
+performance-type-promotion-in-math-fn,
+performance-unnecessary-copy-initialization,
+performance-unnecessary-value-param,
+portability-simd-intrinsics,
+readability-avoid-const-params-in-decls,
+readability-const-return-type,
+readability-container-size-empty,
+readability-convert-member-functions-to-static,
+readability-delete-null-pointer,
+readability-deleted-default,
+readability-inconsistent-declaration-parameter-name,
+readability-make-member-function-const,
+readability-misleading-indentation,
+readability-misplaced-array-index,
+readability-non-const-parameter,
+readability-redundant-control-flow,
+readability-redundant-declaration,
+readability-redundant-function-ptr-dereference,
+readability-redundant-smartptr-get,
+readability-redundant-string-cstr,
+readability-redundant-string-init,
+readability-simplify-subscript-expr,
+readability-static-accessed-through-instance,
+readability-static-definition-in-anonymous-namespace,
+readability-string-compare,
+readability-uniqueptr-delete-release,
+readability-use-anyofallof'

a11_kit-0.1.1/AGENTS.md

@@ -0,0 +1,152 @@
+# A11 Engineering Guide
+
+## Source of truth and layout
+
+- `a11/` defines the current Python API and behavioural contract. `cpp/` is
+  its native implementation and should converge on the same semantics.
+  `actionengine/` is historical reference material, not the source of truth.
+- Keep independently linkable C++ components (`core`, `data`, `concurrency`,
+  `stores`, `net`, `nodes`, `actions`, and `service`). Each `cpp/a11/<part>/`
+  owns its source list in its local `CMakeLists.txt`; the target and dependency
+  graph remain visible in `cpp/CMakeLists.txt`.
+- Concurrency types live directly in `namespace a11`, even though their files
+  remain under `a11/concurrency/`. Do not recreate `a11::concurrency`.
+- Public stateful Python runtime types reuse the bound native class objects;
+  do not add shadow Python implementations or facade subclasses for concrete
+  native types. Attach thin, asynchronous, idiomatic protocols to the bound
+  classes, while retaining deliberate virtual adapters such as
+  `LocalChunkStore` where Python subclass overrides must cross into C++.
+- Pydantic-style validation, JSON, copy, and schema helpers augment native
+  binary and schema values; they must not introduce a second public data model.
+  Python serializers and deserializers continue to operate on those native
+  values.
+
+## Concurrency architecture
+
+- Thread is A11's scheduling substrate. In A11 code, explicitly spell
+  `thread::Mutex`, `thread::MutexLock`, `thread::CondVar`, and
+  `thread::SleepFor`. Mutex members are `mu`/`mu_`; condition variables are
+  `cv`/`cv_`.
+- Protect shared state with Abseil annotations (`ABSL_GUARDED_BY`,
+  `ABSL_EXCLUSIVE_LOCKS_REQUIRED`, and `ABSL_LOCKS_EXCLUDED`) and keep
+  `-Wthread-safety` clean.
+- Boost.Context/Fiber is an implementation detail of Thread. No header may
+  include or expose a Boost type. Fixed, stack-resident opaque storage is
+  preferred for small Boost-backed primitives; implementation size/alignment
+  assertions must guard it.
+- The native `std::mutex`/`std::condition_variable` pair in Thread's Boost
+  scheduler is deliberate: it parks an OS worker when no fiber is runnable.
+  Do not replace that scheduler-internal pair with fiber-aware primitives.
+  A11 state and ordinary Thread APIs must use the fiber-aware primitives.
+- Use fibers near user-facing synchronous-looking APIs where they improve
+  clarity. Use fair, bounded, stackless callback pumps for high-cardinality
+  internal state machines. `ChunkStoreReader` and `ChunkStoreWriter` share
+  stackless schedulers; never add a permanently allocated fiber per instance.
+- Root-fiber stack size is configurable through
+  `THREAD_DEFAULT_FIBER_STACK_SIZE` and `thread::TreeOptions::stack_size`.
+  Avoid extra context switches and do not introduce unbounded queues.
+- Thread changes require cooperative-concurrency tests: cancellation and tree
+  propagation, `Select`/`SelectUntil`, `SleepFor`, timed waits, FIFO behaviour,
+  deadlock resistance, waiter cleanup, and joined/detached fiber lifetime.
+
+## C++ API and implementation rules
+
+- Model ownership with `std::unique_ptr` and `std::shared_ptr`; use raw pointers
+  for temporary non-owning access. Prefer `make_unique`/`make_shared`, write
+  `ptr == nullptr` or `ptr != nullptr`, and apply `absl_nonnull`,
+  `absl_nullable`, or `absl_nullability_unknown` to raw-pointer contracts.
+- Avoid reference counting where ownership is singular or scope-bound. Prefer
+  inline storage, contiguous data, `absl::InlinedVector`, bounded arenas, or a
+  stack-optimised pImpl when lifetime and size justify them.
+- Thread is an accepted public A11 dependency. Keep direct members and inline
+  implementations when Thread was the only reason for a pImpl. Hide other
+  third-party implementation types with forward declarations or pImpl unless
+  they are intrinsically part of a public data contract.
+- Use `absl::flat_hash_map` and `absl::flat_hash_set`. Use
+  `absl::node_hash_map` only when mapped-value addresses truly must remain
+  stable; pointer-valued flat maps already have stable pointees. Test lookup
+  iterators instead of using `.contains()`.
+- Use unqualified `size_t`, not `std::size_t`.
+- Virtual functions have no default arguments. Provide non-virtual convenience
+  overloads when defaults are useful.
+- Initialise every aggregate field deliberately. Treat use-after-move,
+  implicit narrowing, and partially initialised state as correctness bugs.
+
+## Abseil conventions
+
+- Abseil `Status`, `StatusOr`, `Time`, and `Duration` are the native error and
+  timing types. Prefer `ABSL_RETURN_IF_ERROR` and `ABSL_ASSIGN_OR_RETURN`.
+- For `absl::StatusOr<absl::Status>`, use `AssignStatus` to represent an outer
+  error; do not add a wrapper type or conflate it with the inner status value.
+- Log through Abseil (`LOG(ERROR)`, `DLOG`, and checks), never `std::cerr`.
+  Add `AbslStringify` to custom value types used in diagnostics.
+- Preserve structured A11 status details across C++, MessagePack/JSON, and
+  Python. Python callers must receive `a11.status.StatusException`, not a
+  generic or pybind11-specific exception.
+
+## Networking
+
+- WebSocket transport and WebSocket signalling use A11's nghttp2/HTTP2 stack.
+  libdatachannel is reserved for WebRTC data channels and peer connections.
+- All channel transports use the Action Engine-compatible byte-chunking wire
+  format. Keep `ChannelFramingOptions` aligned with `ByteChunkingOptions`,
+  enforce message and pending-byte bounds, and retain out-of-order/interleaved
+  reassembly tests. WebRTC chunk sizes must remain below SCTP limits;
+  WebSocket chunking also prevents large messages from monopolising a stream.
+
+## Python boundary
+
+- Python-specific policy belongs only in `cpp/python/` and thin Python facade
+  modules. Core A11 and Thread must not know about the GIL, asyncio, pybind11,
+  or Python exception classes.
+- Binding callbacks may arrive from fibers, libuv, or libdatachannel threads.
+  Acquire the GIL before touching Python, release it around blocking native
+  waits, marshal coroutine work to its captured asyncio loop, and retain Python
+  objects until completion without leaking references.
+- Native `absl::Time`, `absl::Duration`, and `absl::Status` may back Python
+  convenience types, but arithmetic, exceptions, reprs, and async methods must
+  continue to feel native to Python.
+- Synchronous binding methods returning `absl::Status` or `StatusOr` must use
+  the shared status boundary so failures raise `a11.status.StatusException`;
+  never expose a raw Abseil or pybind11 status exception to callers.
+
+## Dependencies, installation, and wheels
+
+- Non-system C++ dependencies are statically linked. Shared objects are allowed
+  only where a runtime/module boundary requires them; any such dependency must
+  use loader-relative RPATH/RUNPATH and never an absolute build-machine path.
+- Abseil is pinned and fetched from upstream because A11 depends on current
+  status macros. Boost, OpenSSL, nghttp2, uvw/libuv, and libdatachannel targets
+  must pass the static-target checks. Installed CMake targets must pass the
+  out-of-tree smoke test.
+- `scripts/build_wheels.py` builds architecture-specific CPython 3.11-3.15
+  wheels for macOS x86_64/arm64 and Linux x86_64/aarch64. Python 3.15 remains
+  enabled through cibuildwheel's `cpython-prerelease` group until it is stable.
+  Do not emit `universal2` wheels: Boost.Context contains architecture-specific
+  assembly.
+- On macOS, build both macOS and Linux matrices; on Linux, Linux-only is valid.
+  The dependency bootstrap builds static archives per target architecture and
+  deployment target. scikit-build outputs stay in ABI-specific build trees;
+  generated extensions must never enter the sdist or leak into another ABI's
+  wheel.
+- Every wheel must contain exactly one `a11/_native` extension and pass
+  `scripts/audit_wheel.py`, which rejects non-system loader dependencies,
+  absolute RPATH/RUNPATH entries, and universal wheels.
+
+## Verification
+
+- Use `build` as the normal native build tree:
+
+  ```sh
+  cmake --build build-codex -j 8
+  ctest --test-dir build-codex --output-on-failure
+  .venv/bin/pytest -q
+  scripts/smoke_cmake_install.sh build-codex
+  ```
+
+- Format C++ with the root `.clang-format`; run the configured `.clang-tidy`
+  checks when the tool is available. Keep Python formatted with Black/Ruff and
+  regenerate `uv.lock` after dependency or Python-version changes.
+- Add regression tests at the lowest useful layer. Remove or update tests that
+  assert obsolete pure-Python internals, while retaining language-native public
+  behaviour and cross-language callback/error tests.

a11_kit-0.1.1/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.28)
+
+project(a11-superbuild LANGUAGES CXX)
+
+include(CTest)
+
+add_subdirectory(cpp)