tigrbl-atoms 0.4.4

Runtime atom package for Tigrbl stages, phases, typed contexts, event anchors, protocol execution, and composable pipeline algebra.

tigrbl-atoms

Runtime atom package for Tigrbl stages, phases, typed contexts, event anchors, protocol execution, and composable pipeline algebra.

What is tigrbl-atoms?

Runtime atom package for Tigrbl stages, phases, typed contexts, event anchors, protocol execution, and composable pipeline algebra.

Why use tigrbl-atoms?

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

When should I install tigrbl-atoms?

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

Who is tigrbl-atoms for?

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

Where does tigrbl-atoms fit?

tigrbl-atoms lives at pkgs/core/tigrbl_atoms and serves a focused layer in the split Tigrbl framework.

How does tigrbl-atoms work?

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

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/core/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.

Install

uv add tigrbl-atoms

pip install tigrbl-atoms

Surface Coverage

Surface	Value
PyPI package	tigrbl-atoms
Repository path	pkgs/core/tigrbl_atoms
Python import root	tigrbl_atoms
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-atoms 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_atoms: _ctx, _opview_helpers, _request, algebra, atoms/, events, fallback, phases, protocol_runtime, runtime_callbacks, runtime_channel, runtime_transactions

Package catalog:

• phases.py and stages.py: lifecycle phase names, aliases, stage transitions, transaction flags, and error-phase metadata.
• _ctx.py, _request.py, types.py, and events.py: typed context, request, event, and callable contracts shared by kernel/runtime code.
• algebra.py: composable pipeline helpers for sequencing runtime work.
• atoms/ingress: context initialization, transport extraction, and input preparation.
• atoms/dispatch: binding matching, binding parsing, operation resolution, and input normalization.
• atoms/dep: security dependency, general dependency, and parameter resolution units.
• atoms/wire: input schema construction, input validation, output construction, and dump/serialization units.
• atoms/sys: default system handlers for CRUD, bulk, analytics, realtime, transport, transaction, and persistence operations.
• atoms/storage, atoms/out, atoms/response, atoms/egress, and atoms/err: storage conversion, masking, response negotiation/rendering, transport egress, error shaping, and rollback.
• atoms/batch, atoms/fanout, atoms/hot, atoms/intent, and atoms/transport: batch scheduling, fanout shaping, hot slots, intent grouping, and transport sink/capture units.
• protocol_runtime.py, runtime_channel.py, runtime_callbacks.py, and runtime_transactions.py: helpers used by runtime-owned protocol execution.

Public API and Import Surface

• Import roots: tigrbl_atoms.
• Public symbols: EGRESS_PHASES, EdgeTarget, ErrorCtx, HANDLER_PHASES, HookPhase, HookPhases, HookPredicate, INGRESS_PHASES, PHASE_SEQUENCE, PhaseTreeEdge, PhaseTreeNode, StepFn.
• Workspace dependencies: tigrbl-ops-oltp, tigrbl-ops-olap, tigrbl-ops-realtime, tigrbl-ops-webtransport, tigrbl-core, tigrbl-typing.
• External runtime dependencies: jinja2>=3.1, sqlalchemy>=2.0, typing-extensions>=4.0.

Lifecycle Phases

Atoms are organized around the runtime lifecycle:

Group	Phases	Meaning
Ingress	INGRESS_BEGIN, INGRESS_PARSE, INGRESS_DISPATCH	Receive a transport unit, initialize context, parse input, and resolve the target binding/operation.
Transaction and handler	PRE_TX_BEGIN, START_TX, PRE_HANDLER, HANDLER, POST_HANDLER, PRE_COMMIT, TX_COMMIT	Prepare policy, open or attach transaction state, validate input, run handlers, post-process, and commit when Tigrbl owns the transaction.
Egress	POST_COMMIT, EGRESS_SHAPE, EGRESS_FINALIZE, POST_RESPONSE	Shape output, apply response rules, finalize transport output, and run after-response work.
Error	ON_ERROR, phase-specific ON_*_ERROR, TX_ROLLBACK	Classify errors, shape error responses, and roll back transaction-owned work.

END_TX, ON_END_TX_ERROR, and ON_ROLLBACK are compatibility aliases for TX_COMMIT, ON_TX_COMMIT_ERROR, and TX_ROLLBACK. New docs and new atoms should use the current names.

Atom Semantics

An atom is a small, named runtime unit. It should do one thing, take context from the compiled plan, and leave the context in the expected next stage. Atoms are intentionally smaller than handlers:

• ingress atoms do not perform persistence;
• dispatch atoms do not execute business logic;
• wire atoms do not choose transport routes;
• storage atoms do not commit transactions;
• egress atoms do not reopen handler work;
• error atoms should be deterministic and avoid masking the original failure unless policy requires it.

This separation lets the kernel produce readable labels, lets diagnostics explain execution order, and lets runtime transports share behavior across REST, JSON-RPC, stream, SSE, WebSocket, WSS, and WebTransport surfaces.

System Handler Catalog

The atoms/sys package contains default handlers and transaction units used by operation packs and runtime plans. The catalog includes scalar CRUD handlers (create, read, update, replace, merge, delete, list, clear), bulk handlers, analytical handlers (count, exists, aggregate, group_by), realtime handlers (publish, subscribe, tail), stream/file handlers (upload, download, append_chunk, checkpoint), custom/no-op handlers, persistence helpers, and transaction helpers such as start_tx, phase_db, and commit_tx.

Use system handlers when implementing framework behavior. Application code should normally reach these through operations on a Tigrbl app or model rather than importing a handler atom directly.

Transaction Discipline

Transaction atoms and database guards exist so user hooks and system handlers do not silently commit or flush at the wrong phase. The broad rule is:

• before START_TX, do not assume a database transaction exists;
• from START_TX through PRE_COMMIT, in-transaction validation and handler work may proceed under guards;
• TX_COMMIT owns final commit when Tigrbl owns the transaction;
• POST_COMMIT, EGRESS_*, and POST_RESPONSE should not mutate transaction-owned state;
• TX_ROLLBACK performs rollback and cleanup for failures.

If you add or modify an atom, make its transaction expectations explicit in tests. Do not hide direct session commits inside validation, response, transport, or error atoms.

Transport and Protocol Atoms

Transport atoms model runtime units instead of broad protocol names. A WebSocket message, an SSE event, an HTTP stream chunk, and a WebTransport datagram are different units even when they carry similar payloads. Keep family, exchange, framing, lane, subevent, and handler intent separate.

Practical guidance:

• Use ingress/dispatch atoms to parse and resolve transport units.
• Use protocol/runtime helpers to carry channel metadata.
• Use response and egress atoms to render or emit units.
• Preserve fail-closed behavior for unsupported protocol/framing/lane combinations.

Extension Guidance

• Add atoms when the behavior is reusable, phase-specific, and independently testable.
• Keep application policy in hooks or dependencies, not in generic atoms.
• Keep atom names stable and descriptive; they show up in kernel diagnostics.
• Avoid broad atoms that parse, validate, execute, persist, and render at once.

Usage Examples

Verify the installed package

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

Import the package boundary

import importlib

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

Import a public symbol

from tigrbl_atoms import EGRESS_PHASES

print(EGRESS_PHASES)

Use with the facade when building applications

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

How To Choose This Package

Choose tigrbl-atoms 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.

Related Packages

• tigrbl-ops-oltp
• tigrbl-ops-olap
• tigrbl-ops-realtime
• tigrbl-ops-webtransport
• tigrbl-core
• tigrbl-typing
• tigrbl
• tigrbl-base
• tigrbl-runtime

Documentation Links

• Workspace docs
• Package catalog
• Package layout
• Current target
• Current state
• Next steps
• Documentation pointers
• SSOT registry
• Release workflow

Support

• Community: Discord.
• Issues: GitHub Issues.
• Repository: pkgs/core/tigrbl_atoms.

Package-local Boundary

This file is a package-local distribution entry point. This README is the package-local distribution entry point for tigrbl-atoms. 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.

License

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