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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-core
-Version: 0.4.2.dev4
+Version: 0.4.3.dev4
 Summary: Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs.
 License: Apache License
                                     Version 2.0, January 2004
@@ -228,6 +228,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: pydantic (>=2.10,<3)
 Requires-Dist: pyyaml
 Requires-Dist: tigrbl-typing
+Requires-Dist: tigrbl_spec
 Requires-Dist: tomli (>=2.0.1) ; python_version < "3.11"
 Requires-Dist: tomli-w
 Project-URL: Discord, https://discord.gg/K4YTAPapjR
@@ -246,7 +247,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-core"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_core/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_core/README.md.svg?label=hits" alt="Repository hits for tigrbl-core 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-core"/></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-core"/></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-core"/></a>
 </div>
 
@@ -303,7 +304,7 @@ pip install tigrbl-core
 | 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
 
@@ -312,6 +313,13 @@ pip install tigrbl-core
 Implementation orientation:
 - `tigrbl_core`: _spec/, canonical_json, config/, core/, op/, schema/
 
+Package catalog:
+- `tigrbl_core/_spec/`: typed, serializable specifications for aliases, apps, bindings, columns, data types, docs, engines, fields, hooks, IO, middleware, operations, paths, requests, responses, routers, schemas, sessions, storage, tables, and table registries.
+- `tigrbl_core/config/`: constants, defaults, resolver logic, and engine traversal helpers used when app, router, table, column, op, and request layers are merged.
+- `tigrbl_core/op/`: canonical operation names, operation collection, and operation typing helpers.
+- `tigrbl_core/schema/`: dynamic schema construction, schema cache helpers, extras handling, list-parameter support, schema JSON helpers, and `get_schema` access.
+- `tigrbl_core/canonical_json.py`: deterministic JSON output used by docs, registry-like payloads, tests, and conformance artifacts.
+
 ## Public API and Import Surface
 
 - Import roots: `tigrbl_core`.
@@ -319,6 +327,77 @@ Implementation orientation:
 - Workspace dependencies: [`tigrbl-typing`](https://pypi.org/project/tigrbl-typing/).
 - External runtime dependencies: `pydantic>=2.10,<3`, `pyyaml`, `tomli-w`, `tomli>=2.0.1; python_version < '3.11'`.
 
+## Specification Model
+
+The core package is the contract layer. It defines the vocabulary consumed by base abstractions, concrete adapters, atoms, kernel planning, runtime routing, docs generation, and the public facade. Most application code should not construct these specs manually; application code should normally use facade decorators and shortcuts. Extension packages use the specs when they need deterministic, testable configuration objects.
+
+| Spec family | What it describes |
+|---|---|
+| `AppSpec`, `RouterSpec`, `TableSpec` | Container-level framework configuration and inheritance points. |
+| `ColumnSpec`, `FieldSpec`, data type specs | Field semantics, validation, storage, schema projection, and data-type lowering. |
+| `OpSpec` and op utilities | Operation name, alias, arity, binding, handler, schema, hook, response, and runtime intent. |
+| `HookSpec` and hook types | Hook targets, phases, predicates, ordering, and callable registration shape. |
+| `SchemaSpec`, `RequestSpec`, `ResponseSpec`, `IoSpec` | Input/output envelope behavior, request extraction, response shaping, and Pydantic model generation. |
+| `BindingSpec` | REST, JSON-RPC, stream, SSE, WebSocket, WSS, and WebTransport binding metadata. |
+| `EngineSpec`, `SessionSpec`, `StorageSpec` | Engine/provider/session/storage configuration without importing concrete engine implementations. |
+| `DocsSpec`, `PathSpec`, `MiddlewareSpec` | Documentation projection, route paths, and middleware configuration. |
+
+## Operation Semantics
+
+`tigrbl_core.op.canonical.DEFAULT_CANON_VERBS` is the default CRUD set:
+
+```text
+create, read, update, replace, delete, list, clear
+```
+
+Tables can change canonical wiring through mode/include/exclude attributes or a `should_wire_canonical(op)` helper. Core only decides whether an operation is part of the desired specification. Concrete packages and operation packs supply the actual handlers and routing behavior.
+
+Use this package when you need to inspect or build operation specs before runtime compilation. Use `tigrbl` when you simply want a working app surface.
+
+## Binding and Transport Semantics
+
+`BindingSpec` keeps four concerns distinct:
+
+- protocol or binding kind, such as HTTP REST, HTTP JSON-RPC, HTTP stream, SSE, WebSocket, WSS, or WebTransport;
+- exchange shape, such as request/response, server stream, bidirectional stream, client stream, server stream, session, or datagram;
+- framing, such as JSON, JSON-RPC, SSE, WebSocket text, stream framing, or WebTransport outer framing;
+- runtime lane metadata, especially for WebTransport session, stream, and datagram behavior.
+
+This separation is deliberate. Extension authors should not collapse protocol support into a single string or infer framing from the transport name. Invalid combinations should remain explicit validation failures so runtime behavior is fail-closed.
+
+## Configuration Precedence
+
+Core resolvers use this precedence pattern:
+
+```text
+request override > operation spec > column spec > table spec > router spec > app spec > defaults
+```
+
+The most specific layer wins. Keep default policy broad, then narrow behavior by table, column, and operation. Avoid hidden mutation of spec objects after a runtime plan has been compiled; build a fresh spec or invalidate the relevant cache when behavior truly changes.
+
+## Schema Construction
+
+Schema helpers build operation-specific request and response models from table metadata, column specs, request/response extras, list-parameter rules, and op-level configuration. `get_schema(...)` is the stable way to retrieve the generated model for a table operation and direction. Prefer it over hand-writing duplicate Pydantic envelopes when data belongs to a Tigrbl operation.
+
+Best practices for schema work:
+- Keep storage fields, wire fields, and virtual extras separate.
+- Put reusable schema behavior in table or column specs; reserve op specs for operation-specific differences.
+- Use canonical JSON helpers when writing deterministic docs or evidence artifacts.
+- Treat generated schemas as projections of the specs, not as the source of truth.
+
+## Extension Guidance
+
+- Depend on `tigrbl-core` when you need spec classes, op collection, schema generation, or config resolution without concrete app/router/runtime imports.
+- Keep specs serializable and deterministic. Do not attach live database sessions, request objects, or transport handles to core specs.
+- Validate protocol and binding assumptions in core or kernel-facing tests before adding runtime behavior.
+- Keep application-facing convenience APIs in `tigrbl` or `tigrbl-concrete`; keep cross-package contracts here.
+
+Authoring BCP for this boundary:
+- Do treat `ColumnSpec`, `FieldSpec`, `OpSpec`, `HookSpec`, `SchemaSpec`, `BindingSpec`, `EngineSpec`, `SessionSpec`, and related specs as the contract vocabulary that other Tigrbl packages consume.
+- Do keep specs independent of FastAPI, Starlette, SQLAlchemy sessions, live request objects, and transport handles.
+- Do not move application route authoring, direct database calls, concrete engine creation, or runtime dispatch side effects into `tigrbl-core`.
+- Avoid duplicating spec fields in helper classes or generated schemas. Specs should remain the source that schema, docs, kernel, runtime, base, concrete, and facade layers project from.
+
 ## Usage Examples
 
 ### Verify the installed package
@@ -379,6 +458,8 @@ Choose `tigrbl-core` 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)
 
@@ -390,7 +471,7 @@ Choose `tigrbl-core` when the quick-answer table matches your use case. Choose [
 
 ## Package-local Boundary
 
-This README is the package-local distribution entry point for `tigrbl-core`. 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-core`. 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_core-0.4.3.dev4/README.md

@@ -0,0 +1,238 @@
+<div align="center">
+<h1>tigrbl-core</h1>
+<img src="https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/tigrbl_full_logo.png" alt="Tigrbl logo" width="140"/>
+<p><strong>Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs.</strong></p>
+<a href="https://pypi.org/project/tigrbl-core/"><img src="https://img.shields.io/pypi/v/tigrbl-core?label=PyPI" alt="PyPI version for tigrbl-core"/></a>
+<a href="https://pypi.org/project/tigrbl-core/"><img src="https://static.pepy.tech/badge/tigrbl-core" alt="Downloads for tigrbl-core"/></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-core"/></a>
+<a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_core/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_core/README.md.svg?label=hits" alt="Repository hits for tigrbl-core 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%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-core"/></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-core"/></a>
+</div>
+
+## What is tigrbl-core?
+
+Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs.
+
+## Why use tigrbl-core?
+
+Use it when you need this foundational Tigrbl layer directly as a small, focused dependency.
+
+## When should I install tigrbl-core?
+
+Install it for extension packages, package-local tests, or internals that need this boundary without the whole facade.
+
+## Who is tigrbl-core for?
+
+Framework maintainers, extension authors, and advanced users composing Tigrbl from split packages.
+
+## Where does tigrbl-core fit?
+
+`tigrbl-core` lives at `pkgs/core/tigrbl_core` and serves a focused layer in the split Tigrbl framework.
+
+## How does tigrbl-core 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](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json).
+- Release evidence: [publish workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml) 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
+
+```bash
+uv add tigrbl-core
+```
+
+```bash
+pip install tigrbl-core
+```
+
+## Surface Coverage
+
+| Surface | Value |
+|---|---|
+| PyPI package | [`tigrbl-core`](https://pypi.org/project/tigrbl-core/) |
+| Repository path | [`pkgs/core/tigrbl_core`](https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl_core) |
+| Python import root | `tigrbl_core` |
+| 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-core` 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_core`: _spec/, canonical_json, config/, core/, op/, schema/
+
+Package catalog:
+- `tigrbl_core/_spec/`: typed, serializable specifications for aliases, apps, bindings, columns, data types, docs, engines, fields, hooks, IO, middleware, operations, paths, requests, responses, routers, schemas, sessions, storage, tables, and table registries.
+- `tigrbl_core/config/`: constants, defaults, resolver logic, and engine traversal helpers used when app, router, table, column, op, and request layers are merged.
+- `tigrbl_core/op/`: canonical operation names, operation collection, and operation typing helpers.
+- `tigrbl_core/schema/`: dynamic schema construction, schema cache helpers, extras handling, list-parameter support, schema JSON helpers, and `get_schema` access.
+- `tigrbl_core/canonical_json.py`: deterministic JSON output used by docs, registry-like payloads, tests, and conformance artifacts.
+
+## Public API and Import Surface
+
+- Import roots: `tigrbl_core`.
+- Public symbols: public surface is module-oriented; import the package boundary and inspect submodules as needed.
+- Workspace dependencies: [`tigrbl-typing`](https://pypi.org/project/tigrbl-typing/).
+- External runtime dependencies: `pydantic>=2.10,<3`, `pyyaml`, `tomli-w`, `tomli>=2.0.1; python_version < '3.11'`.
+
+## Specification Model
+
+The core package is the contract layer. It defines the vocabulary consumed by base abstractions, concrete adapters, atoms, kernel planning, runtime routing, docs generation, and the public facade. Most application code should not construct these specs manually; application code should normally use facade decorators and shortcuts. Extension packages use the specs when they need deterministic, testable configuration objects.
+
+| Spec family | What it describes |
+|---|---|
+| `AppSpec`, `RouterSpec`, `TableSpec` | Container-level framework configuration and inheritance points. |
+| `ColumnSpec`, `FieldSpec`, data type specs | Field semantics, validation, storage, schema projection, and data-type lowering. |
+| `OpSpec` and op utilities | Operation name, alias, arity, binding, handler, schema, hook, response, and runtime intent. |
+| `HookSpec` and hook types | Hook targets, phases, predicates, ordering, and callable registration shape. |
+| `SchemaSpec`, `RequestSpec`, `ResponseSpec`, `IoSpec` | Input/output envelope behavior, request extraction, response shaping, and Pydantic model generation. |
+| `BindingSpec` | REST, JSON-RPC, stream, SSE, WebSocket, WSS, and WebTransport binding metadata. |
+| `EngineSpec`, `SessionSpec`, `StorageSpec` | Engine/provider/session/storage configuration without importing concrete engine implementations. |
+| `DocsSpec`, `PathSpec`, `MiddlewareSpec` | Documentation projection, route paths, and middleware configuration. |
+
+## Operation Semantics
+
+`tigrbl_core.op.canonical.DEFAULT_CANON_VERBS` is the default CRUD set:
+
+```text
+create, read, update, replace, delete, list, clear
+```
+
+Tables can change canonical wiring through mode/include/exclude attributes or a `should_wire_canonical(op)` helper. Core only decides whether an operation is part of the desired specification. Concrete packages and operation packs supply the actual handlers and routing behavior.
+
+Use this package when you need to inspect or build operation specs before runtime compilation. Use `tigrbl` when you simply want a working app surface.
+
+## Binding and Transport Semantics
+
+`BindingSpec` keeps four concerns distinct:
+
+- protocol or binding kind, such as HTTP REST, HTTP JSON-RPC, HTTP stream, SSE, WebSocket, WSS, or WebTransport;
+- exchange shape, such as request/response, server stream, bidirectional stream, client stream, server stream, session, or datagram;
+- framing, such as JSON, JSON-RPC, SSE, WebSocket text, stream framing, or WebTransport outer framing;
+- runtime lane metadata, especially for WebTransport session, stream, and datagram behavior.
+
+This separation is deliberate. Extension authors should not collapse protocol support into a single string or infer framing from the transport name. Invalid combinations should remain explicit validation failures so runtime behavior is fail-closed.
+
+## Configuration Precedence
+
+Core resolvers use this precedence pattern:
+
+```text
+request override > operation spec > column spec > table spec > router spec > app spec > defaults
+```
+
+The most specific layer wins. Keep default policy broad, then narrow behavior by table, column, and operation. Avoid hidden mutation of spec objects after a runtime plan has been compiled; build a fresh spec or invalidate the relevant cache when behavior truly changes.
+
+## Schema Construction
+
+Schema helpers build operation-specific request and response models from table metadata, column specs, request/response extras, list-parameter rules, and op-level configuration. `get_schema(...)` is the stable way to retrieve the generated model for a table operation and direction. Prefer it over hand-writing duplicate Pydantic envelopes when data belongs to a Tigrbl operation.
+
+Best practices for schema work:
+- Keep storage fields, wire fields, and virtual extras separate.
+- Put reusable schema behavior in table or column specs; reserve op specs for operation-specific differences.
+- Use canonical JSON helpers when writing deterministic docs or evidence artifacts.
+- Treat generated schemas as projections of the specs, not as the source of truth.
+
+## Extension Guidance
+
+- Depend on `tigrbl-core` when you need spec classes, op collection, schema generation, or config resolution without concrete app/router/runtime imports.
+- Keep specs serializable and deterministic. Do not attach live database sessions, request objects, or transport handles to core specs.
+- Validate protocol and binding assumptions in core or kernel-facing tests before adding runtime behavior.
+- Keep application-facing convenience APIs in `tigrbl` or `tigrbl-concrete`; keep cross-package contracts here.
+
+Authoring BCP for this boundary:
+- Do treat `ColumnSpec`, `FieldSpec`, `OpSpec`, `HookSpec`, `SchemaSpec`, `BindingSpec`, `EngineSpec`, `SessionSpec`, and related specs as the contract vocabulary that other Tigrbl packages consume.
+- Do keep specs independent of FastAPI, Starlette, SQLAlchemy sessions, live request objects, and transport handles.
+- Do not move application route authoring, direct database calls, concrete engine creation, or runtime dispatch side effects into `tigrbl-core`.
+- Avoid duplicating spec fields in helper classes or generated schemas. Specs should remain the source that schema, docs, kernel, runtime, base, concrete, and facade layers project from.
+
+## Usage Examples
+
+### Verify the installed package
+
+```bash
+python -m pip show tigrbl-core
+python - <<'PY'
+from importlib.metadata import version
+print(version("tigrbl-core"))
+PY
+```
+
+### Import the package boundary
+
+```python
+import importlib
+
+module = importlib.import_module("tigrbl_core._spec")
+print(module.__name__)
+```
+
+### Inspect available modules
+
+```python
+import importlib
+import pkgutil
+
+module = importlib.import_module("tigrbl_core._spec")
+for info in pkgutil.iter_modules(getattr(module, "__path__", [])):
+    print(info.name)
+```
+
+### Use with the facade when building applications
+
+```bash
+uv add tigrbl tigrbl-core
+python - <<'PY'
+import tigrbl
+print(tigrbl.__name__)
+PY
+```
+
+## How To Choose This Package
+
+Choose `tigrbl-core` when the quick-answer table matches your use case. Choose [`tigrbl`](https://pypi.org/project/tigrbl/) instead when you want the full public facade. 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/) when you are building framework extensions or testing a specific internal boundary.
+
+## Related Packages
+
+- [`tigrbl-typing`](https://pypi.org/project/tigrbl-typing/)
+- [`tigrbl`](https://pypi.org/project/tigrbl/)
+- [`tigrbl-base`](https://pypi.org/project/tigrbl-base/)
+- [`tigrbl-runtime`](https://pypi.org/project/tigrbl-runtime/)
+
+## Documentation Links
+
+- [Workspace docs](https://github.com/tigrbl/tigrbl/blob/master/docs/README.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)
+- [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)
+
+## Support
+
+- Community: [Discord](https://discord.gg/K4YTAPapjR).
+- Issues: [GitHub Issues](https://github.com/tigrbl/tigrbl/issues).
+- Repository: [pkgs/core/tigrbl_core](https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl_core).
+
+## Package-local Boundary
+
+This file is a package-local distribution entry point. This README is the package-local distribution entry point for `tigrbl-core`. 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](https://www.apache.org/licenses/LICENSE-2.0).

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

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-core"
-version = "0.4.2.dev4"
+version = "0.4.3.dev4"
 description = "Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -42,6 +42,7 @@ requires-python = ">=3.10,<3.15"
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 
 dependencies = [
+    "tigrbl_spec",
     "tigrbl-typing",
     "pydantic>=2.10,<3",
     "pyyaml",
@@ -59,6 +60,7 @@ Issues = "https://github.com/tigrbl/tigrbl/issues"
 
 [tool.uv.sources]
 "tigrbl-typing" = { workspace = true }
+"tigrbl_spec" = { workspace = true }
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

{tigrbl_core-0.4.2.dev4 → tigrbl_core-0.4.3.dev4}/tigrbl_core/_spec/__init__.py

@@ -29,6 +29,8 @@ _EXPORTS = {
     "HttpStreamBindingSpec": "binding_spec",
     "SseBindingSpec": "binding_spec",
     "WebTransportBindingSpec": "binding_spec",
+    "WELL_KNOWN_PREFIX": "well_known_spec",
+    "WellKnownResourceSpec": "well_known_spec",
     "WsBindingSpec": "binding_spec",
     "resolve_rest_nested_prefix": "binding_spec",
     "ColumnSpec": "column_spec",
@@ -80,6 +82,8 @@ _EXPORTS = {
     "validate_app_framing_for_binding": "binding_spec",
     "validate_binding_profile_exchange": "binding_spec",
     "validate_path_binding": "path_spec",
+    "normalize_well_known_name": "well_known_spec",
+    "well_known_path": "well_known_spec",
     "PHASE": "op_spec",
     "PHASES": "op_spec",
     "HookPhase": "hook_spec",
@@ -106,7 +110,39 @@ _EXPORTS = {
     "TypeAdapter": "datatypes",
     "TypeRegistry": "datatypes",
     "TableSpec": "table_spec",
+    "BindingToken": "table_profile_bindings",
+    "LoweredBinding": "table_profile_bindings",
+    "lower_binding_tokens_for_ops": "table_profile_bindings",
+    "lower_default_bindings_for_op": "table_profile_bindings",
+    "lower_table_profile_bindings": "table_profile_bindings",
+    "TableProfileSpec": "table_profile_spec",
+    "BuiltinTableProfile": "table_profile_spec",
+    "BUILTIN_TABLE_PROFILE_DEFINITIONS": "table_profile_spec",
+    "BUILTIN_TABLE_PROFILE_KINDS": "table_profile_spec",
+    "TableProfileError": "table_profile_spec",
+    "TableProfileBindingFamily": "table_profile_spec",
+    "TableProfileRole": "table_profile_spec",
+    "PLAIN_TABLE_PROFILE": "table_profile_spec",
+    "CRUD_TABLE_PROFILE": "table_profile_spec",
+    "REALTIME_TABLE_PROFILE": "table_profile_spec",
+    "coerce_table_profile": "table_profile_spec",
+    "get_builtin_table_profile_definition": "table_profile_spec",
+    "get_table_profile": "table_profile_spec",
+    "iter_builtin_table_profile_definitions": "table_profile_spec",
+    "make_builtin_table_profile": "table_profile_spec",
+    "register_table_profile": "table_profile_spec",
     "TableRegistrySpec": "table_registry_spec",
+    "BINDING_STACK_PROJECTIONS": "transport_stack",
+    "BindingStackError": "transport_stack",
+    "BindingStackProjection": "transport_stack",
+    "binding_stack_maturity": "transport_stack",
+    "classify_binding_stack": "transport_stack",
+    "compose_h3_binding_projections": "transport_stack",
+    "require_binding_stack": "transport_stack",
+    "ExposureDecision": "exposure_policy",
+    "ExposurePolicyError": "exposure_policy",
+    "exposed_surfaces": "exposure_policy",
+    "resolve_exposure_policy": "exposure_policy",
 }
 
 __all__ = list(_EXPORTS)

{tigrbl_core-0.4.2.dev4 → tigrbl_core-0.4.3.dev4}/tigrbl_core/_spec/app_spec.py

@@ -2,10 +2,12 @@
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Callable, Optional, Sequence
+import warnings
 
 from .._spec.engine_spec import EngineCfg, EngineSpec
 from .._spec.monotone import as_tuple, merge_mro_sequence_attr
 from .._spec.response_spec import ResponseSpec
+from .._spec.well_known_spec import WellKnownResourceSpec
 from .serde import SerdeMixin
 
 
@@ -45,12 +47,15 @@ def normalize_app_spec(spec: "AppSpec") -> "AppSpec":
         title=str(spec.title or "Tigrbl"),
         description=spec.description,
         version=str(spec.version or "0.1.0"),
-        execution_backend=str(getattr(spec, "execution_backend", None) or "auto"),
+        execution_backend=normalize_execution_backend(
+            getattr(spec, "execution_backend", None),
+        ),
         engine=spec.engine,
         engine_name=spec.engine_name,
         engines=_seqify(spec.engines),
         routers=routers,
         ops=ops,
+        well_known=_seqify(spec.well_known),
         tables=tables,
         schemas=_seqify(spec.schemas),
         hooks=_seqify(spec.hooks),
@@ -64,6 +69,23 @@ def normalize_app_spec(spec: "AppSpec") -> "AppSpec":
     )
 
 
+def normalize_execution_backend(value: Any) -> str:
+    lowered = str(value or "auto").strip().lower()
+    if not lowered:
+        return "auto"
+    if lowered == "rust":
+        warnings.warn(
+            "AppSpec.execution_backend='rust' is deprecated; "
+            "Tigrbl runtime execution is Python-only.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return "python"
+    if lowered in {"auto", "python"}:
+        return lowered
+    raise ValueError(f"unsupported execution backend: {value!r}")
+
+
 @dataclass(eq=False)
 class AppSpec(SerdeMixin):
     """
@@ -83,6 +105,7 @@ class AppSpec(SerdeMixin):
 
     # NEW: orchestration/topology knobs
     ops: Sequence[Any] = field(default_factory=tuple)  # op descriptors or specs
+    well_known: Sequence[WellKnownResourceSpec] = field(default_factory=tuple)
     tables: Sequence[Any] = field(default_factory=tuple)  # table refs owned by app
     schemas: Sequence[Any] = field(default_factory=tuple)  # schema classes/defs
     hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
@@ -103,9 +126,11 @@ class AppSpec(SerdeMixin):
     lifespan: Optional[Callable[..., Any]] = None
 
     def __post_init__(self) -> None:
+        self.execution_backend = normalize_execution_backend(self.execution_backend)
         self.engines = _seqify(self.engines)
         self.routers = _seqify(self.routers)
         self.ops = _seqify(self.ops)
+        self.well_known = _seqify(self.well_known)
         self.tables = _seqify(self.tables)
         self.schemas = _seqify(self.schemas)
         self.hooks = _seqify(self.hooks)
@@ -113,6 +138,14 @@ class AppSpec(SerdeMixin):
         self.deps = _seqify(self.deps)
         self.middlewares = _seqify(self.middlewares)
 
+        for resource in self.well_known:
+            if isinstance(resource, str):
+                raise TypeError("AppSpec.well_known entries must be nested specs, not strings.")
+            if not isinstance(resource, WellKnownResourceSpec):
+                raise TypeError(
+                    "AppSpec.well_known entries must be WellKnownResourceSpec; "
+                    f"got {type(resource).__name__}."
+                )
         validate_engine_inventory(self.engines)
         validate_engine_name_binding(
             self.engine_name,
@@ -172,6 +205,8 @@ class AppSpec(SerdeMixin):
 
     @classmethod
     def from_dict(cls, payload: dict[str, Any]) -> "AppSpec":
+        if "routes" in payload:
+            raise ValueError("AppSpec does not accept 'routes'; use path-owned specs.")
         return super().from_dict(payload)
 
     @classmethod
@@ -255,6 +290,7 @@ class AppSpec(SerdeMixin):
                 or ()
             ),
             ops=tuple(merge_seq_attr(app, "OPS") or ()),
+            well_known=tuple(merge_seq_attr(app, "WELL_KNOWN") or ()),
             tables=tuple(merge_seq_attr(app, "TABLES") or ()),
             schemas=tuple(merge_seq_attr(app, "SCHEMAS") or ()),
             hooks=tuple(merge_seq_attr(app, "HOOKS") or ()),
@@ -277,6 +313,7 @@ class AppSpec(SerdeMixin):
                 engines=tuple(spec.engines or ()),
                 routers=tuple(spec.routers or ()),
                 ops=tuple(spec.ops or ()),
+                well_known=tuple(spec.well_known or ()),
                 tables=tuple(spec.tables or ()),
                 schemas=tuple(spec.schemas or ()),
                 hooks=tuple(spec.hooks or ()),