tigrbl-atoms 0.4.2.dev4__tar.gz → 0.4.3.dev4__tar.gz

{tigrbl_atoms-0.4.2.dev4 → tigrbl_atoms-0.4.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-atoms
-Version: 0.4.2.dev4
+Version: 0.4.3.dev4
 Summary: Runtime atom package for Tigrbl stages, phases, typed contexts, event anchors, protocol execution, and composable pipeline algebra.
 License: Apache License
                                     Version 2.0, January 2004
@@ -254,7 +254,7 @@ Description-Content-Type: text/markdown
 <a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord community for tigrbl-atoms"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_atoms/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_atoms/README.md.svg?label=hits" alt="Repository hits for tigrbl-atoms README"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
-<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-atoms"/></a>
+<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2C%203.11%2C%203.12%2C%203.13%2C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-atoms"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/docs/README.md"><img src="https://img.shields.io/badge/workspace-core-1f6feb" alt="Workspace group for tigrbl-atoms"/></a>
 </div>
 
@@ -311,7 +311,7 @@ pip install tigrbl-atoms
 | Entry points | none declared |
 | Optional extras | none declared |
 | Legal files | `LICENSE`, `NOTICE` |
-| Supported Python | `3.10 | 3.11 | 3.12 | 3.13 | 3.14` |
+| Supported Python | `3.10, 3.11, 3.12, 3.13, 3.14` |
 
 ## What It Owns
 
@@ -320,6 +320,19 @@ pip install tigrbl-atoms
 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`.
@@ -327,6 +340,67 @@ Implementation orientation:
 - Workspace dependencies: [`tigrbl-ops-oltp`](https://pypi.org/project/tigrbl-ops-oltp/), [`tigrbl-ops-olap`](https://pypi.org/project/tigrbl-ops-olap/), [`tigrbl-ops-realtime`](https://pypi.org/project/tigrbl-ops-realtime/), [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-typing`](https://pypi.org/project/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
@@ -388,6 +462,8 @@ Choose `tigrbl-atoms` when the quick-answer table matches your use case. Choose
 - [Package layout](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_LAYOUT.md)
 - [Current target](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_TARGET.md)
 - [Current state](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_STATE.md)
+- [Next steps](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/NEXT_STEPS.md)
+- [Documentation pointers](https://github.com/tigrbl/tigrbl/blob/master/docs/governance/DOC_POINTERS.md)
 - [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json)
 - [Release workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml)
 
@@ -399,7 +475,7 @@ Choose `tigrbl-atoms` when the quick-answer table matches your use case. Choose
 
 ## Package-local Boundary
 
-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.
+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
 

{tigrbl_atoms-0.4.2.dev4 → tigrbl_atoms-0.4.3.dev4}/README.md

@@ -7,7 +7,7 @@
 <a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord community for tigrbl-atoms"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_atoms/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_atoms/README.md.svg?label=hits" alt="Repository hits for tigrbl-atoms README"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
-<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-atoms"/></a>
+<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2C%203.11%2C%203.12%2C%203.13%2C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-atoms"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/docs/README.md"><img src="https://img.shields.io/badge/workspace-core-1f6feb" alt="Workspace group for tigrbl-atoms"/></a>
 </div>
 
@@ -64,7 +64,7 @@ pip install tigrbl-atoms
 | Entry points | none declared |
 | Optional extras | none declared |
 | Legal files | `LICENSE`, `NOTICE` |
-| Supported Python | `3.10 | 3.11 | 3.12 | 3.13 | 3.14` |
+| Supported Python | `3.10, 3.11, 3.12, 3.13, 3.14` |
 
 ## What It Owns
 
@@ -73,6 +73,19 @@ pip install tigrbl-atoms
 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`.
@@ -80,6 +93,67 @@ Implementation orientation:
 - Workspace dependencies: [`tigrbl-ops-oltp`](https://pypi.org/project/tigrbl-ops-oltp/), [`tigrbl-ops-olap`](https://pypi.org/project/tigrbl-ops-olap/), [`tigrbl-ops-realtime`](https://pypi.org/project/tigrbl-ops-realtime/), [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-typing`](https://pypi.org/project/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
@@ -141,6 +215,8 @@ Choose `tigrbl-atoms` when the quick-answer table matches your use case. Choose
 - [Package layout](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_LAYOUT.md)
 - [Current target](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_TARGET.md)
 - [Current state](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_STATE.md)
+- [Next steps](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/NEXT_STEPS.md)
+- [Documentation pointers](https://github.com/tigrbl/tigrbl/blob/master/docs/governance/DOC_POINTERS.md)
 - [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json)
 - [Release workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml)
 
@@ -152,7 +228,7 @@ Choose `tigrbl-atoms` when the quick-answer table matches your use case. Choose
 
 ## Package-local Boundary
 
-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.
+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
 

{tigrbl_atoms-0.4.2.dev4 → tigrbl_atoms-0.4.3.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-atoms"
-version = "0.4.2.dev4"
+version = "0.4.3.dev4"
 description = "Runtime atom package for Tigrbl stages, phases, typed contexts, event anchors, protocol execution, and composable pipeline algebra."
 readme = "README.md"
 license = { file = "LICENSE" }

{tigrbl_atoms-0.4.2.dev4 → tigrbl_atoms-0.4.3.dev4}/tigrbl_atoms/__init__.py

@@ -3,9 +3,6 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
-from .fallback import rust_atoms_enabled
-from .rust import register_rust_atom, register_rust_callback, register_rust_hook
-
 _LAZY_EXPORTS = {
     "PHASE_SEQUENCE": "types",
     "INGRESS_PHASES": "types",
@@ -40,10 +37,6 @@ __all__ = [
     "TypedErr",
     "ErrorCtx",
     "build_error_ctx",
-    "rust_atoms_enabled",
-    "register_rust_atom",
-    "register_rust_callback",
-    "register_rust_hook",
 ]
 
 

tigrbl_atoms-0.4.3.dev4/tigrbl_atoms/atoms/framing/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from .app_frame import (
+    DEFAULT_MAX_PAYLOAD_SIZE,
+    HEADER_SIZE,
+    RESERVED_FLAG_MASK,
+    SUPPORTED_VERSION,
+    FrameStreamDecoder,
+    decode_app_frame,
+    decode_app_frames,
+    encode_app_frame,
+)
+from .codec import (
+    FRAME_CODECS,
+    FrameCodec,
+    decode_frame,
+    decode_webtransport_inner_frame,
+    encode_frame,
+    encode_webtransport_inner_frame,
+    get_frame_codec,
+    supported_frame_codecs,
+)
+
+__all__ = [
+    "DEFAULT_MAX_PAYLOAD_SIZE",
+    "FRAME_CODECS",
+    "HEADER_SIZE",
+    "RESERVED_FLAG_MASK",
+    "SUPPORTED_VERSION",
+    "FrameCodec",
+    "FrameStreamDecoder",
+    "decode_app_frame",
+    "decode_app_frames",
+    "decode_frame",
+    "decode_webtransport_inner_frame",
+    "encode_app_frame",
+    "encode_frame",
+    "encode_webtransport_inner_frame",
+    "get_frame_codec",
+    "supported_frame_codecs",
+]

tigrbl_atoms-0.4.3.dev4/tigrbl_atoms/atoms/framing/app_frame.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+
+HEADER_SIZE = 8
+SUPPORTED_VERSION = 1
+RESERVED_FLAG_MASK = 0x80
+DEFAULT_MAX_PAYLOAD_SIZE = 16 * 1024 * 1024
+
+
+def _as_bytes(payload: bytes | bytearray | memoryview) -> bytes:
+    if isinstance(payload, bytes):
+        return payload
+    if isinstance(payload, (bytearray, memoryview)):
+        return bytes(payload)
+    raise TypeError("payload must be bytes-like")
+
+
+def encode_app_frame(
+    *,
+    version: int = SUPPORTED_VERSION,
+    kind: int,
+    flags: int = 0,
+    payload: bytes | bytearray | memoryview = b"",
+) -> bytes:
+    if version != SUPPORTED_VERSION:
+        raise ValueError(f"unsupported app frame version: {version}")
+    if not 0 <= kind <= 0xFF:
+        raise ValueError("app frame kind must fit in one byte")
+    if not 0 <= flags <= 0x7F:
+        raise ValueError("app frame flags include reserved bits")
+    body = _as_bytes(payload)
+    if len(body) > 0xFFFFFFFF:
+        raise ValueError("app frame payload length exceeds wire limit")
+    return bytes((version, kind, flags, 0)) + len(body).to_bytes(4, "big") + body
+
+
+def decode_app_frame(
+    frame: bytes | bytearray | memoryview,
+    *,
+    max_payload_size: int = DEFAULT_MAX_PAYLOAD_SIZE,
+) -> dict[str, object]:
+    raw = _as_bytes(frame)
+    if len(raw) < HEADER_SIZE:
+        raise ValueError("truncated app frame header")
+    version, kind, flags, reserved = raw[:4]
+    if version != SUPPORTED_VERSION:
+        raise ValueError(f"unsupported app frame version: {version}")
+    if flags & RESERVED_FLAG_MASK or reserved:
+        raise ValueError("app frame reserved bits must be zero")
+    length = int.from_bytes(raw[4:8], "big")
+    if length > max_payload_size:
+        raise ValueError("app frame size exceeds configured limit before allocation")
+    end = HEADER_SIZE + length
+    if len(raw) < end:
+        raise ValueError("truncated app frame payload length")
+    if len(raw) > end:
+        raise ValueError("app frame contains trailing bytes")
+    return {
+        "version": version,
+        "kind": kind,
+        "flags": flags,
+        "length": length,
+        "payload": raw[HEADER_SIZE:end],
+    }
+
+
+def decode_app_frames(
+    stream: bytes | bytearray | memoryview,
+    *,
+    max_payload_size: int = DEFAULT_MAX_PAYLOAD_SIZE,
+) -> Iterator[dict[str, object]]:
+    raw = _as_bytes(stream)
+    offset = 0
+    while offset < len(raw):
+        if len(raw) - offset < HEADER_SIZE:
+            raise ValueError("truncated app frame header")
+        length = int.from_bytes(raw[offset + 4 : offset + 8], "big")
+        end = offset + HEADER_SIZE + length
+        if end > len(raw):
+            raise ValueError("truncated app frame payload length")
+        yield decode_app_frame(raw[offset:end], max_payload_size=max_payload_size)
+        offset = end
+
+
+class FrameStreamDecoder:
+    def __init__(self, *, max_payload_size: int = DEFAULT_MAX_PAYLOAD_SIZE) -> None:
+        self._buffer = bytearray()
+        self._max_payload_size = max_payload_size
+
+    def feed(
+        self, chunk: bytes | bytearray | memoryview
+    ) -> Iterator[dict[str, object]]:
+        self._buffer.extend(_as_bytes(chunk))
+        while len(self._buffer) >= HEADER_SIZE:
+            length = int.from_bytes(self._buffer[4:8], "big")
+            if length > self._max_payload_size:
+                raise ValueError(
+                    "app frame size exceeds configured limit before allocation"
+                )
+            end = HEADER_SIZE + length
+            if len(self._buffer) < end:
+                break
+            frame = bytes(self._buffer[:end])
+            del self._buffer[:end]
+            yield decode_app_frame(frame, max_payload_size=self._max_payload_size)
+
+
+__all__ = [
+    "DEFAULT_MAX_PAYLOAD_SIZE",
+    "HEADER_SIZE",
+    "RESERVED_FLAG_MASK",
+    "SUPPORTED_VERSION",
+    "FrameStreamDecoder",
+    "decode_app_frame",
+    "decode_app_frames",
+    "encode_app_frame",
+]