Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

tigrbl-kernel

Tigrbl logo

Kernel orchestration for composing Tigrbl runtime plans, bindings, operation dispatch, and optimized ASGI execution.

PyPI version for tigrbl-kernel Downloads for tigrbl-kernel Discord community for tigrbl-kernel Repository hits for tigrbl-kernel README Apache 2.0 license Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-kernel Workspace group for tigrbl-kernel

What is tigrbl-kernel?

Kernel orchestration for composing Tigrbl runtime plans, bindings, operation dispatch, and optimized ASGI execution.

Why use tigrbl-kernel?

Use it when you need this foundational Tigrbl layer directly as a small, focused dependency.

When should I install tigrbl-kernel?

Install it for extension packages, package-local tests, or internals that need this boundary without the whole facade.

Who is tigrbl-kernel for?

Framework maintainers, extension authors, and advanced users composing Tigrbl from split packages.

Where does tigrbl-kernel fit?

tigrbl-kernel lives at pkgs/45_kernel/tigrbl_kernel and serves a focused layer in the split Tigrbl framework.

How does tigrbl-kernel work?

It owns a narrow layer in the split workspace and is consumed by higher-level packages through explicit dependencies.

Install

uv add tigrbl-kernel
pip install tigrbl-kernel

Surface Coverage

Surface Value
PyPI package tigrbl-kernel
Repository path pkgs/45_kernel/tigrbl_kernel
Python import root tigrbl_kernel
Console scripts none declared
Entry points none declared
Optional extras none declared
Legal files LICENSE, NOTICE
Supported Python 3.10, 3.11, 3.12, 3.13, 3.14

What It Owns

tigrbl-kernel owns the foundational framework package boundary. It should be installed when you need this package's focused responsibility without assuming every other Tigrbl workspace package is present.

Implementation orientation:

  • tigrbl_kernel: _build, _compile, atoms, cache, callbacks, contract_classification, core, eventkey, eventkey_hooks, events, helpers, hook_types

Package catalog:

  • tigrbl_kernel/core.py, tigrbl_kernel/_build.py, tigrbl_kernel/_compile.py, tigrbl_kernel/models.py, tigrbl_kernel/types.py, and tigrbl_kernel/payload.py: kernel objects, operation views, packed plans, build/compile helpers, and payload contracts.
  • tigrbl_kernel/ordering.py, tigrbl_kernel/labels.py, tigrbl_kernel/hook_types.py, tigrbl_kernel/callbacks.py, and tigrbl_kernel/eventkey_hooks.py: hook ordering, diagnostic labels, callback shape, and event-key-aware hook plumbing.
  • tigrbl_kernel/cache.py, tigrbl_kernel/trace.py, and tigrbl_kernel/measure.py: cached plans, execution trace support, and measurement views.
  • tigrbl_kernel/atoms.py, tigrbl_kernel/transport_atoms.py, and tigrbl_kernel/transaction_units.py: atom references and transaction/transport plan units.
  • tigrbl_kernel/protocol_bindings.py, tigrbl_kernel/protocol_phase_tree.py, tigrbl_kernel/protocol_chains/, tigrbl_kernel/protocol_completion.py, tigrbl_kernel/protocol_fusion.py, and tigrbl_kernel/protocol_legality_matrix.py: transport-specific plan compilation, phase tree construction, chain definitions, completion semantics, fusion, and legality checks.
  • tigrbl_kernel/eventkey.py, tigrbl_kernel/events.py, tigrbl_kernel/transport_events.py, tigrbl_kernel/webtransport_events.py, tigrbl_kernel/subevent_taxonomy.py, and tigrbl_kernel/subevent_handlers.py: event-key construction, subevent taxonomy, and protocol subevent handler mapping.
  • tigrbl_kernel/opchannel_capabilities.py, tigrbl_kernel/loop_modes.py, tigrbl_kernel/loop_regions.py, tigrbl_kernel/segment_fusion.py, and tigrbl_kernel/contract_classification.py: channel capability checks, loop planning, segment grouping, and contract classification.

Public API and Import Surface

  • Import roots: tigrbl_kernel.
  • Public symbols: BatchOpPlan, Kernel, OpView, PackedKernel, SchemaIn, SchemaOut, build_kernel_plan, build_packed_kernel, build_packed_kernel_measurement_view.
  • Workspace dependencies: tigrbl-typing, tigrbl-atoms, tigrbl-core.
  • External runtime dependencies: none declared.

Kernel Semantics

The kernel turns specs, operation inventories, hooks, atoms, and protocol bindings into executable plans. It does not own app authoring syntax, persistence engines, or concrete ASGI classes. Its job is to compile the behavior that runtime-owned routing will execute.

The basic flow is:

specs + model metadata + bindings + hooks
-> operation views
-> ordered phase plan
-> packed kernel
-> runtime execution and diagnostics

Kernel and PackedKernel are the planning surfaces; OpView is the operation-level view of schemas, handlers, hooks, bindings, and labels. build_kernel_plan(...) and build_packed_kernel(...) are useful for tests and framework packages that need to verify the compiled plan without driving a full ASGI request.

Protocol Planning

Protocol planning keeps binding kind, family, framing, exchange, lane, subevent rows, and atom anchors separate. The current planner handles:

Binding kind Runtime family Default framing Plan shape
http.rest / https.rest request JSON request received, handler invoke, response emit.
http.jsonrpc / https.jsonrpc request JSON-RPC framing decode, dispatch, handler invoke, framing encode.
http.stream / https.stream stream stream handler invoke, transport emit, stream close.
http.sse / https.sse stream SSE encode event, emit event, close stream.
ws / wss / websocket message text or negotiated JSON-RPC accept, decode, dispatch, handler, emit/close.
webtransport session, stream, or datagram no top-level app framing lane-specific session, stream, or datagram rows with lane-local framing validation.

Unsupported or ambiguous bindings raise planning errors. For example, WebSocket bindings do not accept HTTP methods, HTTP JSON-RPC requires an RPC method, WebTransport request/response exchange is unsupported, and WebTransport app framing must be declared on the relevant control stream, stream, or datagram lane.

Hook Ordering and Labels

The kernel orders security dependencies, dependencies, system hooks, user hooks, atoms, and handlers into phase plans. Labels are part of the diagnostics contract:

PRE_HANDLER:secdep:myapp.auth.require_user
PRE_HANDLER:dep:myapp.context.load_tenant
HANDLER:hook:sys:handler:create@HANDLER
EGRESS_SHAPE:atom:wire:dump

Use labels to debug and test ordering. Do not use them as application APIs; use specs, decorators, dependencies, and hooks for configuration.

Diagnostics and Traceability

Kernel plans feed /system/kernelz in concrete applications. Trace and measurement helpers make it possible to assert plan shape, count phase work, and inspect compiled execution without relying on a live server. This is especially important for transport work, where a route can look correct while the protocol chain is missing required event rows or capability masks.

Best Practices

  • Compile plans from explicit specs and bindings; do not guess transport behavior from URL strings alone.
  • Keep protocol support checks fail-closed and close to planning.
  • Preserve separate event rows for request, stream, message, session, and datagram families.
  • Add tests at the kernel layer when changing hook order, labels, phase rows, protocol legality, or capability masks.
  • Use measurement views for plan review instead of parsing private object internals.
  • Keep runtime side effects out of kernel code; the kernel should plan, classify, and label, not perform IO.

Usage Examples

Verify the installed package

python -m pip show tigrbl-kernel
python - <<'PY'
from importlib.metadata import version
print(version("tigrbl-kernel"))
PY

Import the package boundary

import importlib

module = importlib.import_module("tigrbl_kernel")
print(module.__name__)

Import a public symbol

from tigrbl_kernel import BatchOpPlan

print(BatchOpPlan)

Use with the facade when building applications

uv add tigrbl tigrbl-kernel
python - <<'PY'
import tigrbl
print(tigrbl.__name__)
PY

How To Choose This Package

Choose tigrbl-kernel when the quick-answer table matches your use case. Choose tigrbl instead when you want the full public facade. Choose a lower-level package such as tigrbl-core, tigrbl-base, or tigrbl-runtime when you are building framework extensions or testing a specific internal boundary.

Support

Package-local Boundary

This file is a package-local distribution entry point. This README is the package-local distribution entry point for tigrbl-kernel. It answers install, usage, API, ownership, and certification-orientation questions for this package. Broader architectural decisions, release status, and cross-package proof chains remain in the repository-level docs and SSOT registry.

Certification Status

  • Package status: governed package in the tigrbl/tigrbl workspace.
  • Governance source: SSOT registry.
  • Release evidence: publish workflow validates package builds, tests, GitHub release assets, and PyPI publication for managed packages.
  • Local certification guard: pkgs/97_tests/tigrbl_tests/tests/unit/test_package_badges_and_notices.py verifies every package README keeps the Discord badge, Apache 2.0 badge, explicit Python-version badge, LICENSE, and NOTICE.
  • Scope note: this README documents the package boundary. Runtime feature support remains governed by .ssot/ entities and the conformance docs linked below.

License

Licensed under the Apache License, Version 2.0. See LICENSE, NOTICE, and the official Apache 2.0 license text.

Metadata

Release files for tigrbl-kernel 0.4.5.dev8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tigrbl-kernel 0.4.5.dev8
File Size Uploaded Provenance Actions
tigrbl_kernel-0.4.5.dev8.tar.gz 98.7 kB Without provenance Details for tigrbl_kernel-0.4.5.dev8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tigrbl-kernel 0.4.5.dev8
File Interpreter ABI Platform Actions
tigrbl_kernel-0.4.5.dev8-py3-none-any.whl Python 3 none any Details for tigrbl_kernel-0.4.5.dev8-py3-none-any.whl

Total release size: 216.1 kB

Release files / tigrbl_kernel-0.4.5.dev8.tar.gz

Download URL tigrbl_kernel-0.4.5.dev8.tar.gz
Size 98.7 kB
Tags Source
SHA-256 checksum
How to use checksums
803d525cc837c38bd9c00d66f5ed6e74ef2acd77ed7d4f017c76e5f917217ae1
BLAKE2b-256 checksum
How to use checksums
ea3896b90025873a5b25b5d657cb0ebaa8fd74da6ae12cf0953612b664c99acf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / tigrbl_kernel-0.4.5.dev8-py3-none-any.whl

Download URL tigrbl_kernel-0.4.5.dev8-py3-none-any.whl
Size 117.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a30b48f6fa736162cc36dfbc9c03aa0a03f9204ba5be832708c7841df12ebb12
BLAKE2b-256 checksum
How to use checksums
dba9d138cb567c89f7e82f2d6d1af7cf64b17b84918167888c889b6fd6c48f55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for tigrbl-kernel 0.4.5.dev8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page