tigrbl 0.4.3.dev4__tar.gz → 0.4.4.dev7__tar.gz

{tigrbl-0.4.3.dev4 → tigrbl-0.4.4.dev7}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tigrbl
-Version: 0.4.3.dev4
-Summary: Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins.
+Version: 0.4.4.dev7
+Summary: Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, runtime plans, hooks, diagnostics, and engine plugins.
 License: Apache License
                                     Version 2.0, January 2004
                                  http://www.apache.org/licenses/
@@ -205,7 +205,7 @@ License: Apache License
             limitations under the License.
 License-File: LICENSE
 License-File: NOTICE
-Keywords: tigrbl,asgi,api,api framework,asgi framework,dependency injection,fastapi alternative,json-rpc,framework,openapi,openrpc,pydantic,rest,schema-first,sqlalchemy,typed validation
+Keywords: tigrbl,asgi,api,api framework,asgi framework,dependency injection,fastapi alternative,json-rpc,framework,openapi,openrpc,pydantic,rest,runtime plans,schema-first,sqlalchemy,sse,streaming,typed validation,websocket,webtransport
 Author: Jacob Stewart
 Author-email: jacob@swarmauri.com
 Requires-Python: >=3.10,<3.15
@@ -265,7 +265,7 @@ Description-Content-Type: text/markdown
 <div align="center">
 <h1>tigrbl</h1>
 <img src="https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/tigrbl_full_logo.png" alt="Tigrbl logo" width="140"/>
-<p><strong>Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins.</strong></p>
+<p><strong>Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, OpenAPI, OpenRPC, typed validation, hooks, diagnostics, and engine plugins.</strong></p>
 <a href="https://pypi.org/project/tigrbl/"><img src="https://img.shields.io/pypi/v/tigrbl?label=PyPI" alt="PyPI version for tigrbl"/></a>
 <a href="https://pypi.org/project/tigrbl/"><img src="https://static.pepy.tech/badge/tigrbl" alt="Downloads for tigrbl"/></a>
 <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"/></a>
@@ -277,7 +277,7 @@ Description-Content-Type: text/markdown
 
 ## What is tigrbl?
 
-Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins.
+Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, OpenAPI, OpenRPC, typed validation, hooks, diagnostics, and engine plugins.
 
 ## Why use tigrbl?
 
@@ -285,7 +285,7 @@ Use it when you want the public Tigrbl authoring surface in one install target i
 
 ## When should I install tigrbl?
 
-Install it for application projects, examples, service skeletons, and teams that want REST, JSON-RPC, docs, schemas, engines, and CLI support from one facade.
+Install it for application projects, examples, service skeletons, and teams that want REST, JSON-RPC, streaming, SSE, WebSocket, docs, schemas, engines, and CLI support from one facade.
 
 ## Who is tigrbl for?
 
@@ -293,7 +293,7 @@ Application developers, platform teams, and service owners building schema-first
 
 ## Where does tigrbl fit?
 
-`tigrbl` lives at `pkgs/core/tigrbl` and serves schema-first service authoring, REST and JSON-RPC projection, docs, engines, and CLI workflows.
+`tigrbl` lives at `pkgs/core/tigrbl` and serves schema-first service authoring, REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, docs, engines, and CLI workflows.
 
 ## How does tigrbl work?
 
@@ -346,7 +346,7 @@ Implementation orientation:
 Facade orientation:
 - Authoring API: app/router factories, table helpers, column helpers, schema helpers, operation decorators, hook decorators, response decorators, and engine decorators.
 - Compatibility imports: facade modules such as `tigrbl.op`, `tigrbl.config`, `tigrbl.schema`, `tigrbl.ddl`, `tigrbl.security`, and `tigrbl.system` forward into the split packages that now own the implementation.
-- Runtime projection: model operations are compiled into REST bindings, JSON-RPC methods, OpenAPI, OpenRPC, diagnostics, schemas, and engine-backed handlers.
+- Runtime projection: model operations are compiled into REST bindings, JSON-RPC methods, HTTP streams, SSE responses, WebSocket channels, WebTransport-aware runtime units, OpenAPI, OpenRPC, diagnostics, schemas, and engine-backed handlers.
 - Operational boundary: this package is the application-facing install target; lower-level packages own specs, atoms, kernel planning, runtime execution, base abstractions, concrete adapters, ORM helpers, and engine plugins.
 
 ## Public API and Import Surface
@@ -412,7 +412,7 @@ Tigrbl is organized as a split framework behind this facade:
 | Atoms | `tigrbl-atoms` | Phase names, stage transitions, typed contexts, ingress/dispatch/wire/storage/handler/egress/error atoms, transaction atoms, batch atoms, and transport atoms. |
 | Kernel | `tigrbl-kernel` | Operation-view compilation, hook ordering, labels, packed plans, protocol chains, lifecycle rows, event keys, capability masks, and dispatch plans. |
 | Runtime | `tigrbl-runtime` | Runtime-owned routing, request execution, framing atoms, transport channels, and default kernel integration. |
-| Operation packs | `tigrbl-ops-oltp`, `tigrbl-ops-olap`, `tigrbl-ops-realtime` | Canonical operation definitions for CRUD, analytics, and realtime/streaming workloads. |
+| Operation packs | `tigrbl-ops-oltp`, `tigrbl-ops-olap`, `tigrbl-ops-realtime`, `tigrbl-ops-webtransport` | Canonical operation definitions for CRUD, analytics, realtime/streaming, and WebTransport control-plane workloads. |
 | ORM | `tigrbl-orm` | SQLAlchemy-facing table and mixin helpers used by application models. |
 | Engines | `tigrbl-engine-*` | Persistence, cache, queue, rate, bloom, dedupe, dataframe, warehouse, and database engine integrations. |
 
@@ -422,35 +422,42 @@ Use the facade for application code unless you are maintaining a framework layer
 
 The facade is the normal application authoring surface. Use `docs/developer/AUTHORING_BCP.md` for the full policy; this package README keeps the public-package guidance explicit because it is the README most application developers see first.
 
+If you are translating concepts from Starlette, FastAPI, Flask, ASGI 3,
+WebSocket, WebTransport, SQLAlchemy, or backend-specific SQL engines, start with
+[`docs/developer/EQUIVALENCE_INDEX.md`](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/EQUIVALENCE_INDEX.md).
+Those guides describe analogous lower-layer concepts while keeping Tigrbl-owned
+authoring surfaces as the application contract.
+
 Do:
 
-- Do import application-facing classes, decorators, helpers, and shortcuts from `tigrbl` unless you are intentionally maintaining a lower-level package.
-- Do create services with `TigrblApp`, `TigrblRouter`, facade route/operation decorators, table helpers, column helpers, hook decorators, response decorators, schema helpers, and engine decorators.
-- Do model domain actions as Tigrbl operations, including canonical CRUD operations, operation-pack verbs, or explicit custom operation specs.
-- Do use operation handlers through Tigrbl specs and kernel/runtime dispatch so REST, JSON-RPC, OpenAPI, OpenRPC, diagnostics, schemas, hooks, and tests stay aligned.
-- Do express field behavior through Tigrbl table, column, datatype, storage, IO, request, response, and operation specs.
-- Do use `get_schema(...)` or schema helpers for operation request/response payloads.
-- Do bind engines declaratively at app, router, table, or operation scope.
-- Do use lifecycle hooks for policy, validation, enrichment, audit, response shaping, and post-response work.
-- Do use `/system/methodz`, `/system/hookz`, `/system/kernelz`, OpenAPI, and OpenRPC to inspect the registered framework state.
+- Do import application-facing classes, decorators, helpers, and shortcuts from `tigrbl` unless you are intentionally maintaining a lower-level package. Why: the facade is the supported application contract and hides lower-layer package splits.
+- Do create services with `TigrblApp`, `TigrblRouter`, facade route/operation decorators, table helpers, column helpers, hook decorators, response decorators, schema helpers, and engine decorators. Why: these entry points are visible to runtime planning, docs, diagnostics, schemas, and tests.
+- Do model domain actions as Tigrbl operations, including canonical CRUD operations, operation-pack verbs, or explicit custom operation specs. Why: operations are the unit Tigrbl can project consistently across protocol surfaces.
+- Do use operation handlers through Tigrbl specs and kernel/runtime dispatch so REST, JSON-RPC, HTTP streams, SSE, WebSocket, WebTransport-aware runtime units, OpenAPI, OpenRPC, diagnostics, schemas, hooks, and tests stay aligned. Why: handler dispatch is where protocol projection and lifecycle guarantees meet.
+- Do express field behavior through Tigrbl table, column, datatype, storage, IO, request, response, and operation specs. Why: specs are the shared source for storage lowering, wire schemas, docs, runtime planning, hooks, and diagnostics.
+- Do use `get_schema(...)` or schema helpers for operation request/response payloads. Why: generated schemas keep payloads aligned with operation specs and docs.
+- Do bind engines declaratively at app, router, table, or operation scope. Why: declarative binding lets the runtime own session selection, transaction scope, diagnostics, and backend-specific behavior.
+- Do use lifecycle hooks for policy, validation, enrichment, audit, response shaping, and post-response work. Why: hooks make policy visible to lifecycle ordering, diagnostics, tests, and transport-independent execution.
+- Do use `/system/methodz`, `/system/hookz`, `/system/kernelz`, OpenAPI, and OpenRPC to inspect the registered framework state. Why: these surfaces show the compiled Tigrbl state instead of a lower-level framework's partial view.
 
 Do not:
 
-- Do not author application endpoints with FastAPI `FastAPI`, `APIRouter`, dependency wiring, route decorators, middleware registration, docs generation, or lifecycle hooks.
-- Do not author application endpoints with Starlette route, request, response, middleware, background-task, or lifecycle classes.
-- Do not use raw SQLAlchemy `mapped_column(...)` or `Column(...)` as the primary application authoring surface when Tigrbl column helpers or specs can represent the field behavior.
-- Do not build ad-hoc SQLAlchemy engines, sessions, or sessionmakers inside request handlers.
-- Do not call direct database/session methods such as `flush()` or `commit()` from application hooks or handlers unless you are implementing a framework-level atom with the correct lifecycle guard contract.
-- Do not wrap model behavior in one-off route handlers when an operation spec can represent the behavior.
-- Do not bypass kernel/runtime plans when wiring REST, JSON-RPC, stream, SSE, WebSocket, or WebTransport behavior.
+- Do not author application endpoints with FastAPI `FastAPI`, `APIRouter`, dependency wiring, route decorators, middleware registration, docs generation, or lifecycle hooks. Why: that makes FastAPI the application contract instead of Tigrbl's operation, binding, hook, schema, docs, and diagnostics contract.
+- Do not author application endpoints with Starlette route, request, response, middleware, background-task, or lifecycle classes. Why: Starlette is a lower-level runtime substrate here, not the application-facing authoring surface.
+- Do not author application endpoints with Flask `Flask`, `Blueprint`, route decorators, request/response globals, `MethodView`, extension registration, or lifecycle hooks. Why: Flask route objects cannot preserve Tigrbl's shared operation inventory, schema generation, lifecycle phases, or transport plan.
+- Do not use raw SQLAlchemy `mapped_column(...)` or `Column(...)` as the primary application authoring surface when Tigrbl column helpers or specs can represent the field behavior. Why: raw ORM declarations are only one lowering target and cannot carry the full storage, IO, validation, docs, hook, and runtime contract.
+- Do not build ad-hoc SQLAlchemy engines, sessions, or sessionmakers inside request handlers. Why: ad-hoc construction bypasses declarative engine binding, session policy, pooling, diagnostics, tests, and backend adapters.
+- Do not call direct database/session methods such as `flush()` or `commit()` from application hooks or handlers unless you are implementing a framework-level atom with the correct lifecycle guard contract. Why: direct calls bypass lifecycle guards and can commit partial state before hooks, errors, rollback handlers, or response shaping have run.
+- Do not wrap model behavior in one-off route handlers when an operation spec can represent the behavior. Why: route wrappers hide behavior from protocol projection, docs, hooks, diagnostics, and tests.
+- Do not bypass kernel/runtime plans when wiring REST, JSON-RPC, HTTP stream, SSE, WebSocket, or WebTransport behavior. Why: bypasses skip legality checks, lifecycle phases, transaction ownership, protocol framing policy, and fail-closed unsupported-combination handling.
 
 Avoid:
 
-- Avoid treating ASGI, FastAPI, Starlette, SQLAlchemy ORM materialization, or direct DB methods as the user-facing application contract. Tigrbl owns the authoring contract; lower-level libraries are implementation substrates behind Tigrbl-owned adapters, engines, tests, or benchmarks.
-- Avoid duplicating field behavior in SQLAlchemy, Pydantic, docs, and route handlers. Put reusable behavior in Tigrbl specs so storage, schema, docs, runtime, hooks, and diagnostics read the same source.
-- Avoid hand-written Pydantic envelopes for payloads that belong to a Tigrbl operation.
-- Avoid transport-specific wrappers for authentication, authorization, validation, or dispatch when security dependencies, hooks, operation specs, or lifecycle phases can express the rule once.
-- Avoid teaching lower-level internals in application README examples unless the example is clearly marked as a test, benchmark, migration, engine adapter, or framework-internal compatibility surface.
+- Avoid treating ASGI, FastAPI, Flask, Starlette, SQLAlchemy ORM materialization, or direct DB methods as the user-facing application contract. Tigrbl owns the authoring contract; lower-level libraries are implementation substrates behind Tigrbl-owned adapters, engines, tests, or benchmarks. Why: lower-level substrates are legal implementation tools, but not the supported application API.
+- Avoid duplicating field behavior in SQLAlchemy, Pydantic, docs, and route handlers. Put reusable behavior in Tigrbl specs so storage, schema, docs, runtime, hooks, and diagnostics read the same source. Why: duplicated rules create stale validation, stale docs, and protocol-specific behavior differences.
+- Avoid hand-written Pydantic envelopes for payloads that belong to a Tigrbl operation. Why: generated schemas keep request/response payloads aligned with operation specs and docs.
+- Avoid transport-specific wrappers for authentication, authorization, validation, or dispatch when security dependencies, hooks, operation specs, or lifecycle phases can express the rule once. Why: transport-layer policy can make REST, JSON-RPC, streams, SSE, WebSocket, and WebTransport disagree about the same domain operation.
+- Avoid teaching lower-level internals in application README examples unless the example is clearly marked as a test, benchmark, migration, engine adapter, or framework-internal compatibility surface. Why: examples without a boundary marker become accidental guidance.
 
 ## Default CRUD and Operation Semantics
 
@@ -526,7 +533,7 @@ Bulk operations are not part of the minimal canonical default set. They are enab
 
 ## REST, JSON-RPC, and Transport Projection
 
-Tigrbl projects the same operation inventory across multiple protocol surfaces:
+Tigrbl projects the same operation inventory across multiple protocol surfaces while keeping protocol, carrier, exchange, stream direction, and framing separate. The full public matrix is in [`docs/developer/TRANSPORTS_AND_FRAMING.md`](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORTS_AND_FRAMING.md).
 
 | Surface | Binding family | Framing | Primary use |
 |---|---|---|---|
@@ -535,9 +542,10 @@ Tigrbl projects the same operation inventory across multiple protocol surfaces:
 | HTTP stream | stream | stream or configured stream framing | Server-streaming outputs and progressive responses. |
 | SSE | stream | SSE | Browser-friendly event streams. |
 | WebSocket/WSS | message | text or JSON-RPC when negotiated | Bidirectional message workflows. |
-| WebTransport | session, stream, or datagram | WebTransport outer framing plus lane-specific inner framing | Session, stream, and datagram transports with fail-closed lane validation. |
+| WebTransport | session, stream, or datagram | no top-level app framing; lane-local framing only | Session, stream, and datagram transports with fail-closed lane validation. |
+| h11 / h2 / h3 / QUIC carrier metadata | delegated server/runtime boundary | binding-dependent | Serving-stack protocol mechanics, runtime capability metadata, and deployment controls. |
 
-The framework keeps protocol, exchange, and framing separate. For example, strict JSON-RPC document framing is `jsonrpc`; newline-delimited JSON-RPC should be modeled distinctly rather than collapsed into plain `ndjson`. Unsupported combinations fail closed during binding or runtime planning instead of being guessed.
+The framework keeps protocol, exchange, and framing separate. For example, strict JSON-RPC document framing is `jsonrpc`; newline-delimited JSON-RPC should be modeled distinctly rather than collapsed into plain `ndjson`. Unsupported combinations fail closed during binding or runtime planning instead of being guessed. Tigrbl owns binding declarations, runtime planning, channel metadata, and frame codecs; the serving/runtime stack owns wire-level HTTP/1.1, HTTP/2, HTTP/3, QUIC, TLS termination, HPACK, QPACK, ALPN, and flow control.
 
 ## Request Lifecycle and Hook Phases
 
@@ -665,7 +673,7 @@ Common table-level declarations include:
 
 ## How To Choose This Package
 
-Choose `tigrbl` when you want the full public facade: app composition, schema-first routing, REST and JSON-RPC projection, docs generation, engine integration, and CLI workflow. Choose a lower-level package such as [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), or [`tigrbl-runtime`](https://pypi.org/project/tigrbl-runtime/) only when you are building framework extensions or testing a specific internal boundary.
+Choose `tigrbl` when you want the full public facade: app composition, schema-first routing, REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, docs generation, engine integration, and CLI workflow. Choose a lower-level package such as [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), or [`tigrbl-runtime`](https://pypi.org/project/tigrbl-runtime/) only when you are building framework extensions or testing a specific internal boundary.
 
 ## Related Packages
 
@@ -682,6 +690,12 @@ Choose `tigrbl` when you want the full public facade: app composition, schema-fi
 ## Documentation Links
 
 - [Workspace docs](https://github.com/tigrbl/tigrbl/blob/master/docs/README.md)
+- [Equivalence guide index](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/EQUIVALENCE_INDEX.md)
+- [Application authoring equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/AUTHORING_EQUIVALENCE.md)
+- [Router and table equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/ROUTER_TABLE_EQUIVALENCE.md)
+- [Transport equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORT_EQUIVALENCE.md)
+- [Engine and SQL equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/ENGINE_SQL_EQUIVALENCE.md)
+- [Transports and framing](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORTS_AND_FRAMING.md)
 - [Package catalog](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_CATALOG.md)
 - [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)

{tigrbl-0.4.3.dev4 → tigrbl-0.4.4.dev7}/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <h1>tigrbl</h1>
 <img src="https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/tigrbl_full_logo.png" alt="Tigrbl logo" width="140"/>
-<p><strong>Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins.</strong></p>
+<p><strong>Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, OpenAPI, OpenRPC, typed validation, hooks, diagnostics, and engine plugins.</strong></p>
 <a href="https://pypi.org/project/tigrbl/"><img src="https://img.shields.io/pypi/v/tigrbl?label=PyPI" alt="PyPI version for tigrbl"/></a>
 <a href="https://pypi.org/project/tigrbl/"><img src="https://static.pepy.tech/badge/tigrbl" alt="Downloads for tigrbl"/></a>
 <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"/></a>
@@ -13,7 +13,7 @@
 
 ## What is tigrbl?
 
-Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins.
+Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, OpenAPI, OpenRPC, typed validation, hooks, diagnostics, and engine plugins.
 
 ## Why use tigrbl?
 
@@ -21,7 +21,7 @@ Use it when you want the public Tigrbl authoring surface in one install target i
 
 ## When should I install tigrbl?
 
-Install it for application projects, examples, service skeletons, and teams that want REST, JSON-RPC, docs, schemas, engines, and CLI support from one facade.
+Install it for application projects, examples, service skeletons, and teams that want REST, JSON-RPC, streaming, SSE, WebSocket, docs, schemas, engines, and CLI support from one facade.
 
 ## Who is tigrbl for?
 
@@ -29,7 +29,7 @@ Application developers, platform teams, and service owners building schema-first
 
 ## Where does tigrbl fit?
 
-`tigrbl` lives at `pkgs/core/tigrbl` and serves schema-first service authoring, REST and JSON-RPC projection, docs, engines, and CLI workflows.
+`tigrbl` lives at `pkgs/core/tigrbl` and serves schema-first service authoring, REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, docs, engines, and CLI workflows.
 
 ## How does tigrbl work?
 
@@ -82,7 +82,7 @@ Implementation orientation:
 Facade orientation:
 - Authoring API: app/router factories, table helpers, column helpers, schema helpers, operation decorators, hook decorators, response decorators, and engine decorators.
 - Compatibility imports: facade modules such as `tigrbl.op`, `tigrbl.config`, `tigrbl.schema`, `tigrbl.ddl`, `tigrbl.security`, and `tigrbl.system` forward into the split packages that now own the implementation.
-- Runtime projection: model operations are compiled into REST bindings, JSON-RPC methods, OpenAPI, OpenRPC, diagnostics, schemas, and engine-backed handlers.
+- Runtime projection: model operations are compiled into REST bindings, JSON-RPC methods, HTTP streams, SSE responses, WebSocket channels, WebTransport-aware runtime units, OpenAPI, OpenRPC, diagnostics, schemas, and engine-backed handlers.
 - Operational boundary: this package is the application-facing install target; lower-level packages own specs, atoms, kernel planning, runtime execution, base abstractions, concrete adapters, ORM helpers, and engine plugins.
 
 ## Public API and Import Surface
@@ -148,7 +148,7 @@ Tigrbl is organized as a split framework behind this facade:
 | Atoms | `tigrbl-atoms` | Phase names, stage transitions, typed contexts, ingress/dispatch/wire/storage/handler/egress/error atoms, transaction atoms, batch atoms, and transport atoms. |
 | Kernel | `tigrbl-kernel` | Operation-view compilation, hook ordering, labels, packed plans, protocol chains, lifecycle rows, event keys, capability masks, and dispatch plans. |
 | Runtime | `tigrbl-runtime` | Runtime-owned routing, request execution, framing atoms, transport channels, and default kernel integration. |
-| Operation packs | `tigrbl-ops-oltp`, `tigrbl-ops-olap`, `tigrbl-ops-realtime` | Canonical operation definitions for CRUD, analytics, and realtime/streaming workloads. |
+| Operation packs | `tigrbl-ops-oltp`, `tigrbl-ops-olap`, `tigrbl-ops-realtime`, `tigrbl-ops-webtransport` | Canonical operation definitions for CRUD, analytics, realtime/streaming, and WebTransport control-plane workloads. |
 | ORM | `tigrbl-orm` | SQLAlchemy-facing table and mixin helpers used by application models. |
 | Engines | `tigrbl-engine-*` | Persistence, cache, queue, rate, bloom, dedupe, dataframe, warehouse, and database engine integrations. |
 
@@ -158,35 +158,42 @@ Use the facade for application code unless you are maintaining a framework layer
 
 The facade is the normal application authoring surface. Use `docs/developer/AUTHORING_BCP.md` for the full policy; this package README keeps the public-package guidance explicit because it is the README most application developers see first.
 
+If you are translating concepts from Starlette, FastAPI, Flask, ASGI 3,
+WebSocket, WebTransport, SQLAlchemy, or backend-specific SQL engines, start with
+[`docs/developer/EQUIVALENCE_INDEX.md`](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/EQUIVALENCE_INDEX.md).
+Those guides describe analogous lower-layer concepts while keeping Tigrbl-owned
+authoring surfaces as the application contract.
+
 Do:
 
-- Do import application-facing classes, decorators, helpers, and shortcuts from `tigrbl` unless you are intentionally maintaining a lower-level package.
-- Do create services with `TigrblApp`, `TigrblRouter`, facade route/operation decorators, table helpers, column helpers, hook decorators, response decorators, schema helpers, and engine decorators.
-- Do model domain actions as Tigrbl operations, including canonical CRUD operations, operation-pack verbs, or explicit custom operation specs.
-- Do use operation handlers through Tigrbl specs and kernel/runtime dispatch so REST, JSON-RPC, OpenAPI, OpenRPC, diagnostics, schemas, hooks, and tests stay aligned.
-- Do express field behavior through Tigrbl table, column, datatype, storage, IO, request, response, and operation specs.
-- Do use `get_schema(...)` or schema helpers for operation request/response payloads.
-- Do bind engines declaratively at app, router, table, or operation scope.
-- Do use lifecycle hooks for policy, validation, enrichment, audit, response shaping, and post-response work.
-- Do use `/system/methodz`, `/system/hookz`, `/system/kernelz`, OpenAPI, and OpenRPC to inspect the registered framework state.
+- Do import application-facing classes, decorators, helpers, and shortcuts from `tigrbl` unless you are intentionally maintaining a lower-level package. Why: the facade is the supported application contract and hides lower-layer package splits.
+- Do create services with `TigrblApp`, `TigrblRouter`, facade route/operation decorators, table helpers, column helpers, hook decorators, response decorators, schema helpers, and engine decorators. Why: these entry points are visible to runtime planning, docs, diagnostics, schemas, and tests.
+- Do model domain actions as Tigrbl operations, including canonical CRUD operations, operation-pack verbs, or explicit custom operation specs. Why: operations are the unit Tigrbl can project consistently across protocol surfaces.
+- Do use operation handlers through Tigrbl specs and kernel/runtime dispatch so REST, JSON-RPC, HTTP streams, SSE, WebSocket, WebTransport-aware runtime units, OpenAPI, OpenRPC, diagnostics, schemas, hooks, and tests stay aligned. Why: handler dispatch is where protocol projection and lifecycle guarantees meet.
+- Do express field behavior through Tigrbl table, column, datatype, storage, IO, request, response, and operation specs. Why: specs are the shared source for storage lowering, wire schemas, docs, runtime planning, hooks, and diagnostics.
+- Do use `get_schema(...)` or schema helpers for operation request/response payloads. Why: generated schemas keep payloads aligned with operation specs and docs.
+- Do bind engines declaratively at app, router, table, or operation scope. Why: declarative binding lets the runtime own session selection, transaction scope, diagnostics, and backend-specific behavior.
+- Do use lifecycle hooks for policy, validation, enrichment, audit, response shaping, and post-response work. Why: hooks make policy visible to lifecycle ordering, diagnostics, tests, and transport-independent execution.
+- Do use `/system/methodz`, `/system/hookz`, `/system/kernelz`, OpenAPI, and OpenRPC to inspect the registered framework state. Why: these surfaces show the compiled Tigrbl state instead of a lower-level framework's partial view.
 
 Do not:
 
-- Do not author application endpoints with FastAPI `FastAPI`, `APIRouter`, dependency wiring, route decorators, middleware registration, docs generation, or lifecycle hooks.
-- Do not author application endpoints with Starlette route, request, response, middleware, background-task, or lifecycle classes.
-- Do not use raw SQLAlchemy `mapped_column(...)` or `Column(...)` as the primary application authoring surface when Tigrbl column helpers or specs can represent the field behavior.
-- Do not build ad-hoc SQLAlchemy engines, sessions, or sessionmakers inside request handlers.
-- Do not call direct database/session methods such as `flush()` or `commit()` from application hooks or handlers unless you are implementing a framework-level atom with the correct lifecycle guard contract.
-- Do not wrap model behavior in one-off route handlers when an operation spec can represent the behavior.
-- Do not bypass kernel/runtime plans when wiring REST, JSON-RPC, stream, SSE, WebSocket, or WebTransport behavior.
+- Do not author application endpoints with FastAPI `FastAPI`, `APIRouter`, dependency wiring, route decorators, middleware registration, docs generation, or lifecycle hooks. Why: that makes FastAPI the application contract instead of Tigrbl's operation, binding, hook, schema, docs, and diagnostics contract.
+- Do not author application endpoints with Starlette route, request, response, middleware, background-task, or lifecycle classes. Why: Starlette is a lower-level runtime substrate here, not the application-facing authoring surface.
+- Do not author application endpoints with Flask `Flask`, `Blueprint`, route decorators, request/response globals, `MethodView`, extension registration, or lifecycle hooks. Why: Flask route objects cannot preserve Tigrbl's shared operation inventory, schema generation, lifecycle phases, or transport plan.
+- Do not use raw SQLAlchemy `mapped_column(...)` or `Column(...)` as the primary application authoring surface when Tigrbl column helpers or specs can represent the field behavior. Why: raw ORM declarations are only one lowering target and cannot carry the full storage, IO, validation, docs, hook, and runtime contract.
+- Do not build ad-hoc SQLAlchemy engines, sessions, or sessionmakers inside request handlers. Why: ad-hoc construction bypasses declarative engine binding, session policy, pooling, diagnostics, tests, and backend adapters.
+- Do not call direct database/session methods such as `flush()` or `commit()` from application hooks or handlers unless you are implementing a framework-level atom with the correct lifecycle guard contract. Why: direct calls bypass lifecycle guards and can commit partial state before hooks, errors, rollback handlers, or response shaping have run.
+- Do not wrap model behavior in one-off route handlers when an operation spec can represent the behavior. Why: route wrappers hide behavior from protocol projection, docs, hooks, diagnostics, and tests.
+- Do not bypass kernel/runtime plans when wiring REST, JSON-RPC, HTTP stream, SSE, WebSocket, or WebTransport behavior. Why: bypasses skip legality checks, lifecycle phases, transaction ownership, protocol framing policy, and fail-closed unsupported-combination handling.
 
 Avoid:
 
-- Avoid treating ASGI, FastAPI, Starlette, SQLAlchemy ORM materialization, or direct DB methods as the user-facing application contract. Tigrbl owns the authoring contract; lower-level libraries are implementation substrates behind Tigrbl-owned adapters, engines, tests, or benchmarks.
-- Avoid duplicating field behavior in SQLAlchemy, Pydantic, docs, and route handlers. Put reusable behavior in Tigrbl specs so storage, schema, docs, runtime, hooks, and diagnostics read the same source.
-- Avoid hand-written Pydantic envelopes for payloads that belong to a Tigrbl operation.
-- Avoid transport-specific wrappers for authentication, authorization, validation, or dispatch when security dependencies, hooks, operation specs, or lifecycle phases can express the rule once.
-- Avoid teaching lower-level internals in application README examples unless the example is clearly marked as a test, benchmark, migration, engine adapter, or framework-internal compatibility surface.
+- Avoid treating ASGI, FastAPI, Flask, Starlette, SQLAlchemy ORM materialization, or direct DB methods as the user-facing application contract. Tigrbl owns the authoring contract; lower-level libraries are implementation substrates behind Tigrbl-owned adapters, engines, tests, or benchmarks. Why: lower-level substrates are legal implementation tools, but not the supported application API.
+- Avoid duplicating field behavior in SQLAlchemy, Pydantic, docs, and route handlers. Put reusable behavior in Tigrbl specs so storage, schema, docs, runtime, hooks, and diagnostics read the same source. Why: duplicated rules create stale validation, stale docs, and protocol-specific behavior differences.
+- Avoid hand-written Pydantic envelopes for payloads that belong to a Tigrbl operation. Why: generated schemas keep request/response payloads aligned with operation specs and docs.
+- Avoid transport-specific wrappers for authentication, authorization, validation, or dispatch when security dependencies, hooks, operation specs, or lifecycle phases can express the rule once. Why: transport-layer policy can make REST, JSON-RPC, streams, SSE, WebSocket, and WebTransport disagree about the same domain operation.
+- Avoid teaching lower-level internals in application README examples unless the example is clearly marked as a test, benchmark, migration, engine adapter, or framework-internal compatibility surface. Why: examples without a boundary marker become accidental guidance.
 
 ## Default CRUD and Operation Semantics
 
@@ -262,7 +269,7 @@ Bulk operations are not part of the minimal canonical default set. They are enab
 
 ## REST, JSON-RPC, and Transport Projection
 
-Tigrbl projects the same operation inventory across multiple protocol surfaces:
+Tigrbl projects the same operation inventory across multiple protocol surfaces while keeping protocol, carrier, exchange, stream direction, and framing separate. The full public matrix is in [`docs/developer/TRANSPORTS_AND_FRAMING.md`](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORTS_AND_FRAMING.md).
 
 | Surface | Binding family | Framing | Primary use |
 |---|---|---|---|
@@ -271,9 +278,10 @@ Tigrbl projects the same operation inventory across multiple protocol surfaces:
 | HTTP stream | stream | stream or configured stream framing | Server-streaming outputs and progressive responses. |
 | SSE | stream | SSE | Browser-friendly event streams. |
 | WebSocket/WSS | message | text or JSON-RPC when negotiated | Bidirectional message workflows. |
-| WebTransport | session, stream, or datagram | WebTransport outer framing plus lane-specific inner framing | Session, stream, and datagram transports with fail-closed lane validation. |
+| WebTransport | session, stream, or datagram | no top-level app framing; lane-local framing only | Session, stream, and datagram transports with fail-closed lane validation. |
+| h11 / h2 / h3 / QUIC carrier metadata | delegated server/runtime boundary | binding-dependent | Serving-stack protocol mechanics, runtime capability metadata, and deployment controls. |
 
-The framework keeps protocol, exchange, and framing separate. For example, strict JSON-RPC document framing is `jsonrpc`; newline-delimited JSON-RPC should be modeled distinctly rather than collapsed into plain `ndjson`. Unsupported combinations fail closed during binding or runtime planning instead of being guessed.
+The framework keeps protocol, exchange, and framing separate. For example, strict JSON-RPC document framing is `jsonrpc`; newline-delimited JSON-RPC should be modeled distinctly rather than collapsed into plain `ndjson`. Unsupported combinations fail closed during binding or runtime planning instead of being guessed. Tigrbl owns binding declarations, runtime planning, channel metadata, and frame codecs; the serving/runtime stack owns wire-level HTTP/1.1, HTTP/2, HTTP/3, QUIC, TLS termination, HPACK, QPACK, ALPN, and flow control.
 
 ## Request Lifecycle and Hook Phases
 
@@ -401,7 +409,7 @@ Common table-level declarations include:
 
 ## How To Choose This Package
 
-Choose `tigrbl` when you want the full public facade: app composition, schema-first routing, REST and JSON-RPC projection, docs generation, engine integration, and CLI workflow. Choose a lower-level package such as [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), or [`tigrbl-runtime`](https://pypi.org/project/tigrbl-runtime/) only when you are building framework extensions or testing a specific internal boundary.
+Choose `tigrbl` when you want the full public facade: app composition, schema-first routing, REST, JSON-RPC, streaming, SSE, WebSocket, WebTransport-aware runtime planning, docs generation, engine integration, and CLI workflow. Choose a lower-level package such as [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-base`](https://pypi.org/project/tigrbl-base/), or [`tigrbl-runtime`](https://pypi.org/project/tigrbl-runtime/) only when you are building framework extensions or testing a specific internal boundary.
 
 ## Related Packages
 
@@ -418,6 +426,12 @@ Choose `tigrbl` when you want the full public facade: app composition, schema-fi
 ## Documentation Links
 
 - [Workspace docs](https://github.com/tigrbl/tigrbl/blob/master/docs/README.md)
+- [Equivalence guide index](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/EQUIVALENCE_INDEX.md)
+- [Application authoring equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/AUTHORING_EQUIVALENCE.md)
+- [Router and table equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/ROUTER_TABLE_EQUIVALENCE.md)
+- [Transport equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORT_EQUIVALENCE.md)
+- [Engine and SQL equivalence](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/ENGINE_SQL_EQUIVALENCE.md)
+- [Transports and framing](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/TRANSPORTS_AND_FRAMING.md)
 - [Package catalog](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_CATALOG.md)
 - [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)

{tigrbl-0.4.3.dev4 → tigrbl-0.4.4.dev7}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tigrbl"
-version = "0.4.3.dev4"
-description = "Schema-first ASGI framework for REST and JSON-RPC APIs with OpenAPI, OpenRPC, SQLAlchemy, typed validation, hooks, and engine plugins."
+version = "0.4.4.dev7"
+description = "Schema-first ASGI framework for REST, JSON-RPC, streaming, SSE, WebSocket, runtime plans, hooks, diagnostics, and engine plugins."
 readme = "README.md"
 license = { file = "LICENSE" }
 keywords = [
@@ -18,9 +18,14 @@ keywords = [
     "openrpc",
     "pydantic",
     "rest",
+    "runtime plans",
     "schema-first",
     "sqlalchemy",
+    "sse",
+    "streaming",
     "typed validation",
+    "websocket",
+    "webtransport",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

{tigrbl-0.4.3.dev4 → tigrbl-0.4.4.dev7}/tigrbl/__init__.py

@@ -108,6 +108,7 @@ from tigrbl_concrete._concrete import (  # noqa: E402
     HTMLResponse,
     HTTPBasic,
     HTTPBearer,
+    JsonRpcBulkCrudTable,
     JsonRpcOlapTable,
     JsonRpcOltpTable,
     JsonRpcTable,
@@ -120,6 +121,7 @@ from tigrbl_concrete._concrete import (  # noqa: E402
     Op,
     PlainTextResponse,
     RealtimeTable,
+    RestBulkCrudTable,
     RestJsonRpcOlapTable,
     RestJsonRpcOltpTable,
     RestJsonRpcTable,
@@ -219,9 +221,12 @@ from tigrbl_core._spec import (  # noqa: E402
     FieldSpec,
     Framing,
     ForeignKeySpec,
+    HeadersSpec,
     HookPhase,
     HttpJsonRpcBindingSpec,
+    HttpJsonRpcProtocolBindingSpec,
     HttpRestBindingSpec,
+    HttpRestProtocolBindingSpec,
     HttpStreamBindingSpec,
     IOSpec,
     OpSpec,
@@ -249,6 +254,10 @@ from tigrbl_core._spec import (  # noqa: E402
     TxScope,
     WebSocketBindingSpec,
     WebTransportBindingSpec,
+    WebSocketProtocolBindingSpec,
+    WebTransportDatagramSpec,
+    WebTransportProtocolBindingSpec,
+    WebTransportStreamSpec,
     WellKnownResourceSpec,
     WsBindingSpec,
     canonical_binding_kind,
@@ -257,7 +266,7 @@ from tigrbl_core._spec import (  # noqa: E402
     validate_app_framing_for_binding,
     validate_binding_profile_exchange,
 )
-from tigrbl_runtime.executors.invoke import _invoke  # noqa: E402
+from tigrbl_runtime.executors.phase_runner import _invoke  # noqa: E402
 
 
 def bind(*args, **kwargs):
@@ -394,7 +403,9 @@ __all__ = [
     "Framing",
     "HTTPBindingSpec",
     "HttpJsonRpcBindingSpec",
+    "HttpJsonRpcProtocolBindingSpec",
     "HttpRestBindingSpec",
+    "HttpRestProtocolBindingSpec",
     "PathKind",
     "PathSpec",
     "path_for_binding",
@@ -431,6 +442,10 @@ __all__ = [
     "SseBindingSpec",
     "WebSocketBindingSpec",
     "WebTransportBindingSpec",
+    "WebSocketProtocolBindingSpec",
+    "WebTransportDatagramSpec",
+    "WebTransportProtocolBindingSpec",
+    "WebTransportStreamSpec",
     "WsBindingSpec",
     "canonical_binding_kind",
     "normalize_binding_spec",
@@ -481,6 +496,7 @@ __all__ = [
     "StorageTransformSpec",
     "StorageTypeRef",
     "ForeignKeySpec",
+    "HeadersSpec",
     "RequestSpec",
     "SchemaSpec",
     "SessionSpec",
@@ -506,6 +522,8 @@ __all__ = [
     "RestJsonRpcTable",
     "JsonRpcTable",
     "BulkCrudTable",
+    "RestBulkCrudTable",
+    "JsonRpcBulkCrudTable",
     "RestOltpTable",
     "JsonRpcOltpTable",
     "RestJsonRpcOltpTable",

{tigrbl-0.4.3.dev4 → tigrbl-0.4.4.dev7}/tigrbl/cli.py

@@ -21,6 +21,7 @@ from . import TigrblApp, TigrblRouter
 from .engine import known_engine_kinds, load_engine_plugins
 from .system import mount_lens, mount_openapi, mount_openrpc, mount_swagger
 from tigrbl_core._spec.engine_spec import EngineSpec
+from tigrbl_core._spec.serde import SerdeMixin
 
 SUPPORTED_SERVERS = ("tigrcorn", "uvicorn", "hypercorn", "gunicorn")
 DEFAULT_HOST = "127.0.0.1"
@@ -415,6 +416,8 @@ def _json_default(value: Any) -> Any:
             return [str(item) for item in value]
     if isinstance(value, Path):
         return str(value)
+    if isinstance(value, SerdeMixin):
+        return value.to_dict()
     raise TypeError(f"Object of type {value.__class__.__name__} is not JSON serializable")