tigrbl-skills-engineer 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. tigrbl_skills_engineer-0.1.0a1/.gitignore +14 -0
  2. tigrbl_skills_engineer-0.1.0a1/PKG-INFO +15 -0
  3. tigrbl_skills_engineer-0.1.0a1/README.md +3 -0
  4. tigrbl_skills_engineer-0.1.0a1/pyproject.toml +37 -0
  5. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/__init__.py +17 -0
  6. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/.codex-plugin/plugin.json +48 -0
  7. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/SKILL.md +42 -0
  8. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/agents/openai.yaml +4 -0
  9. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/backend-and-ops.md +136 -0
  10. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/containers.md +32 -0
  11. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/custom-and-event-driven-ops.md +35 -0
  12. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/data-engines.md +53 -0
  13. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/frontend-client.md +45 -0
  14. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-realtime-app/references/source-map.md +33 -0
  15. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/SKILL.md +38 -0
  16. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/agents/openai.yaml +4 -0
  17. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/containers-and-tests.md +39 -0
  18. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/frontend-client.md +35 -0
  19. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/postgres-and-transactions.md +44 -0
  20. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/rest-and-openapi.md +39 -0
  21. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/source-map.md +31 -0
  22. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/build-tigrbl-rest-bulk-crud-app/references/table-and-app.md +115 -0
  23. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/SKILL.md +31 -0
  24. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/agents/openai.yaml +4 -0
  25. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/app-router-authoring.md +24 -0
  26. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/docs-and-doc-payloads.md +21 -0
  27. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/hooks-lifecycle.md +22 -0
  28. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/ops-handlers-schemas.md +32 -0
  29. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/protocols-framing.md +19 -0
  30. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/references/table-profiles.md +64 -0
  31. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author/scripts/new_tigrbl_app.py +7 -0
  32. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-app/SKILL.md +26 -0
  33. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-app/agents/openai.yaml +4 -0
  34. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-app/references/app-router-authoring.md +24 -0
  35. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-app/references/docs-and-doc-payloads.md +21 -0
  36. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-app/scripts/check_docs_mounts.py +4 -0
  37. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-hook/SKILL.md +26 -0
  38. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-hook/agents/openai.yaml +4 -0
  39. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-hook/references/ctx-binding-patterns.md +39 -0
  40. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-hook/references/hooks-lifecycle.md +22 -0
  41. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-hook/scripts/list_hook_phases.py +3 -0
  42. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/SKILL.md +27 -0
  43. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/agents/openai.yaml +4 -0
  44. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/references/builtin-ops.md +20 -0
  45. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/references/ops-handlers-schemas.md +32 -0
  46. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/references/protocols-framing.md +19 -0
  47. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-op/scripts/inspect_bindings.py +3 -0
  48. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/SKILL.md +27 -0
  49. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/agents/openai.yaml +4 -0
  50. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/references/mux-demux-dispatch.md +13 -0
  51. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/references/protocols-framing.md +19 -0
  52. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/references/webtransport-streams-dgrams.md +13 -0
  53. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-protocol/scripts/protocol_matrix.py +12 -0
  54. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/SKILL.md +28 -0
  55. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/agents/openai.yaml +4 -0
  56. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/references/builtin-ops.md +20 -0
  57. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/references/ops-handlers-schemas.md +32 -0
  58. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/references/table-profiles.md +64 -0
  59. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-author-table/scripts/inspect_table_profiles.py +3 -0
  60. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/SKILL.md +27 -0
  61. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/agents/openai.yaml +4 -0
  62. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/references/ctx-binding-patterns.md +39 -0
  63. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/references/hooks-lifecycle.md +22 -0
  64. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/references/ops-handlers-schemas.md +32 -0
  65. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-bind-ctx/scripts/check_ctx_bindings.py +11 -0
  66. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-engineer/SKILL.md +48 -0
  67. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-engineer/agents/openai.yaml +4 -0
  68. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/SKILL.md +28 -0
  69. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/agents/openai.yaml +4 -0
  70. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/references/builtin-ops.md +20 -0
  71. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/references/ops-handlers-schemas.md +32 -0
  72. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/references/table-profiles.md +64 -0
  73. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/_payload/skills/tigrbl-use-builtin-ops/scripts/list_builtin_ops.py +3 -0
  74. tigrbl_skills_engineer-0.1.0a1/src/tigrbl_engineer_plugin/cli.py +7 -0
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .pytest_tmp/
5
+ .ruff_cache/
6
+ .mypy_cache/
7
+ .venv/
8
+ dist/
9
+ tigrbl-skills-*.tgz
10
+ build/
11
+ *.egg-info/
12
+ packages/*/src/*/_payload/
13
+ .DS_Store
14
+ Thumbs.db
@@ -0,0 +1,15 @@
1
+ Metadata-Version: 2.5
2
+ Name: tigrbl-skills-engineer
3
+ Version: 0.1.0a1
4
+ Summary: Portable Tigrbl Engineer Codex plugin.
5
+ Project-URL: Homepage, https://tigrbl.com
6
+ Project-URL: Repository, https://github.com/tigrbl/tigrbl-skills
7
+ Author-email: Tigrbl <support@tigrbl.com>
8
+ License-Expression: Apache-2.0
9
+ Requires-Python: >=3.10
10
+ Requires-Dist: tigrbl-skills==0.1.0a1
11
+ Description-Content-Type: text/markdown
12
+
13
+ # tigrbl-skills-engineer
14
+
15
+ Portable Python distribution for the `tigrbl-engineer` Codex plugin.
@@ -0,0 +1,3 @@
1
+ # tigrbl-skills-engineer
2
+
3
+ Portable Python distribution for the `tigrbl-engineer` Codex plugin.
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "tigrbl-skills-engineer"
7
+ version = "0.1.0a1"
8
+ description = "Portable Tigrbl Engineer Codex plugin."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "Apache-2.0"
12
+ authors = [{ name = "Tigrbl", email = "support@tigrbl.com" }]
13
+ dependencies = ["tigrbl-skills==0.1.0a1"]
14
+
15
+ [project.urls]
16
+ Homepage = "https://tigrbl.com"
17
+ Repository = "https://github.com/tigrbl/tigrbl-skills"
18
+
19
+ [project.scripts]
20
+ tigrbl-skills-engineer = "tigrbl_engineer_plugin.cli:main"
21
+
22
+ [project.entry-points."tigrbl_skills.plugins"]
23
+ tigrbl-engineer = "tigrbl_engineer_plugin:plugin"
24
+
25
+ [dependency-groups]
26
+ dev = [
27
+ "pyyaml>=6.0,<7",
28
+ "pytest>=8.4,<9",
29
+ "ruff>=0.12,<1",
30
+ "ssot-registry>=0.2,<1",
31
+ ]
32
+
33
+ [tool.hatch.build.targets.wheel]
34
+ packages = ["src/tigrbl_engineer_plugin"]
35
+
36
+ [tool.hatch.build.targets.sdist]
37
+ include = ["src/tigrbl_engineer_plugin/**", "README.md", "pyproject.toml"]
@@ -0,0 +1,17 @@
1
+ """Payload provider for the tigrbl-engineer Codex plugin."""
2
+
3
+ from pathlib import Path
4
+
5
+ from tigrbl_skills import PluginDescriptor
6
+
7
+ __version__ = "0.1.0a1"
8
+
9
+
10
+ def plugin() -> PluginDescriptor:
11
+ return PluginDescriptor(
12
+ name="tigrbl-engineer",
13
+ distribution="tigrbl-skills-engineer",
14
+ version=__version__,
15
+ payload=Path(__file__).parent / "_payload",
16
+ conflicts=("tigrbl-app-authoring",),
17
+ )
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "tigrbl-engineer",
3
+ "version": "0.1.0a1",
4
+ "description": "Route and execute Tigrbl application, protocol, realtime, and REST bulk CRUD engineering workflows.",
5
+ "author": {
6
+ "name": "Tigrbl",
7
+ "url": "https://tigrbl.com"
8
+ },
9
+ "homepage": "https://tigrbl.com",
10
+ "repository": "https://github.com/tigrbl/tigrbl-skills",
11
+ "license": "Apache-2.0",
12
+ "keywords": [
13
+ "tigrbl",
14
+ "application-engineering",
15
+ "tables",
16
+ "operations",
17
+ "protocols",
18
+ "websocket",
19
+ "realtime",
20
+ "rest",
21
+ "bulk-crud",
22
+ "postgresql",
23
+ "configurable-skills"
24
+ ],
25
+ "skills": "./skills/",
26
+ "interface": {
27
+ "displayName": "Tigrbl Engineer Skills",
28
+ "shortDescription": "Build complete Tigrbl application systems.",
29
+ "longDescription": "An installable Tigrbl engineering toolkit with an umbrella routing skill and task-specific workflows for apps, routers, tables, operations, hooks, contexts, protocol bindings, durable realtime systems, and PostgreSQL-backed REST bulk CRUD services.",
30
+ "developerName": "Tigrbl",
31
+ "category": "Developer Tools",
32
+ "capabilities": [
33
+ "Design",
34
+ "Write",
35
+ "Integrate",
36
+ "Test"
37
+ ],
38
+ "websiteURL": "https://tigrbl.com",
39
+ "privacyPolicyURL": "https://tigrbl.com",
40
+ "termsOfServiceURL": "https://tigrbl.com",
41
+ "defaultPrompt": [
42
+ "Use $tigrbl-engineer to build a Tigrbl app.",
43
+ "Use $tigrbl-engineer to diagnose a protocol issue.",
44
+ "Use $tigrbl-engineer to select a Tigrbl workflow."
45
+ ],
46
+ "brandColor": "#0F766E"
47
+ }
48
+ }
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: build-tigrbl-realtime-app
3
+ description: Build, extend, debug, or containerize Tigrbl-based WebSocket realtime thread and messaging applications. Use when Codex needs to declare ws-jsonrpc apps, routers, tables, canonical or custom operations, subscription and publish fanout, browser JSON-RPC clients, PostgreSQL or DuckDB durability, DuckDB analytics over PostgreSQL, event-triggered client workflows, Dockerfiles, Compose stacks, or end-to-end realtime tests.
4
+ ---
5
+
6
+ # Build Tigrbl Realtime App
7
+
8
+ ## Workflow
9
+
10
+ 1. Inspect repository instructions, working-tree changes, dependency versions, and the nearest realtime demo before editing. Use `references/source-map.md` to locate the canonical examples and framework internals.
11
+ 2. Define the application contract: table resources, durable fields, shared WebSocket path, JSON-RPC methods, channel identity, notification envelope, authorization boundary, delivery guarantees, and frontend recovery behavior.
12
+ 3. Select a data topology with `references/data-engines.md`:
13
+ - Use PostgreSQL for concurrent, networked, production-oriented durability.
14
+ - Use DuckDB for local or single-process durable applications and analytical workloads.
15
+ - Use PostgreSQL for authoritative writes plus DuckDB read-only attachment for analytics when both OLTP concurrency and analytical SQL are required.
16
+ 4. Compose the backend with `references/backend-and-ops.md`. Declare app, router, path, table, binding, and operation specs; register engine plugins before constructing the app; let `app.initialize()` own DDL.
17
+ 5. Keep durable mutation and realtime fanout explicit. Treat `Message.create` and `Thread.publish` as separate operations unless the inspected Tigrbl version provides and tests a transactional publish-effect contract.
18
+ 6. Implement frontend transport using `references/frontend-client.md`. Correlate responses by JSON-RPC `id`, route id-less method frames as notifications, deduplicate events, rehydrate from durable history, and reconnect/resubscribe deliberately.
19
+ 7. Add custom request/response or event-reactive behavior with `references/custom-and-event-driven-ops.md`. Keep server custom handlers on Tigrbl operation surfaces; keep subscription notification reactions in the client unless a source-backed server hook exists.
20
+ 8. Containerize with `references/containers.md`. Preserve build contexts for sibling Tigrbl/Tigrcorn checkouts when developing unreleased framework code; use health checks and named volumes for durable services.
21
+ 9. Verify schema initialization, canonical CRUD, request correlation, multiple independent subscribers, id-less fanout notifications, disconnect cleanup, persistence across restart, and partial failure between save and publish.
22
+ 10. Report the selected topology, implemented methods and envelopes, verification evidence, and any production gaps such as authentication, authorization, multi-node broker support, ordering, replay, backpressure, or idempotency.
23
+
24
+ ## Guardrails
25
+
26
+ - Declare application table fields with Tigrbl `Column` and `Column.S`, `Column.F`, and `Column.IO`; do not import or directly author SQLAlchemy `Column`, `Mapped`, `mapped_column`, or SQLAlchemy types.
27
+ - Do not add an application-local WebSocket receive loop, JSON parser, method switch, send loop, broadcast loop, or cleanup loop when the declared `PathSpec(kind="ws-jsonrpc")` surface can be lowered by Tigrbl.
28
+ - Do not use a raw `duckdb.Connection` as a SQLAlchemy-style DDL bind; use the registered DuckDB engine provider.
29
+ - Do not imply that the current in-memory realtime broker provides cross-process or cross-node fanout.
30
+ - Do not couple a successful database write to an unverified broadcast. Expose retryable `saved_not_broadcast` state or implement an outbox when delivery guarantees require it.
31
+ - Do not accept client-supplied channel membership or actor identity without authorization checks in production.
32
+ - Preserve full importable `model_ref` identities in path-owned `TableSpec` values.
33
+ - Run repository-native formatters, type checks, tests, frontend builds, and multi-client proofs before completion.
34
+
35
+ ## Reference routing
36
+
37
+ - Read `references/source-map.md` whenever locating the demos or validating behavior against Tigrbl internals.
38
+ - Read `references/backend-and-ops.md` for declarations, engine registration, canonical realtime ops, and custom server handlers.
39
+ - Read `references/frontend-client.md` for browser integration, message state, notification routing, and recovery.
40
+ - Read `references/data-engines.md` for PostgreSQL, DuckDB durability, mixed-engine analytics, and consistency choices.
41
+ - Read `references/custom-and-event-driven-ops.md` for request-like custom ops and reactions to subscription events.
42
+ - Read `references/containers.md` for Dockerfiles, Compose services, volumes, health checks, and local source contexts.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Build Tigrbl Realtime App"
3
+ short_description: "Build durable Tigrbl realtime messaging"
4
+ default_prompt: "Use $build-tigrbl-realtime-app to build a durable Tigrbl WebSocket messaging application."
@@ -0,0 +1,136 @@
1
+ # Backend and operation composition
2
+
3
+ ## Declaration shape
4
+
5
+ 1. Define one `WsBindingSpec(proto="ws", path="/ws/realtime", framing=JsonRpcFramingSpec())`.
6
+ 2. Define `TableBase` models for durable resources such as `Thread` and `Message`.
7
+ 3. Attach canonical `OpSpec` entries to `__tigrbl_ops__`: `create`/`list` for durability and `subscribe`/`publish` for realtime behavior.
8
+ 4. Collect each model into a path-owned `TableSpec`; set `model=None` and an importable `model_ref="package.module:Class"` when composing across the spec boundary.
9
+ 5. Put tables on `PathSpec(kind="ws-jsonrpc")`, then collect a concrete `TigrblRouter` and `TigrblApp` defined through `defineRouterSpec` and `defineAppSpec`.
10
+ 6. Register the required engine plugin and pass its `EngineSpec` into `TigrblApp.from_spec(...)`.
11
+ 7. Run `app.initialize()` for provider-backed DDL. Run with Tigrcorn and enable both `http1` and `websocket` protocols.
12
+
13
+ Typical methods are `Thread.create`, `Thread.list`, `Thread.subscribe`, `Thread.publish`, `Message.create`, and `Message.list`. JSON-RPC requests use `{ "jsonrpc": "2.0", "method": "Message.create", "params": {...}, "id": "unique" }`.
14
+
15
+ ## Durable table declarations
16
+
17
+ Declare durable fields with Tigrbl `Column` and its storage, field, and I/O specs. Do not use SQLAlchemy `Column`, `Mapped`, `mapped_column`, or SQLAlchemy types in application models.
18
+
19
+ ```python
20
+ from tigrbl import Column, ForeignKeySpec, TableBase
21
+
22
+
23
+ class Thread(TableBase):
24
+ __tablename__ = "threads"
25
+
26
+ id = Column(
27
+ storage=Column.S(primary_key=True, nullable=False),
28
+ field=Column.F(
29
+ py_type=str,
30
+ constraints={"max_length": 64},
31
+ required_in=("create",),
32
+ ),
33
+ io=Column.IO(
34
+ in_verbs=("create",),
35
+ out_verbs=("read", "list", "create"),
36
+ filter_ops=("eq", "in"),
37
+ sortable=True,
38
+ ),
39
+ )
40
+ title = Column(
41
+ storage=Column.S(nullable=False, index=True),
42
+ field=Column.F(
43
+ py_type=str,
44
+ constraints={"min_length": 1, "max_length": 160},
45
+ required_in=("create",),
46
+ ),
47
+ io=Column.IO(
48
+ in_verbs=("create", "update"),
49
+ out_verbs=("read", "list", "create", "update"),
50
+ mutable_verbs=("update",),
51
+ filter_ops=("eq", "contains"),
52
+ sortable=True,
53
+ ),
54
+ )
55
+
56
+
57
+ class Message(TableBase):
58
+ __tablename__ = "messages"
59
+
60
+ id = Column(
61
+ storage=Column.S(primary_key=True, nullable=False),
62
+ field=Column.F(
63
+ py_type=str,
64
+ constraints={"max_length": 64},
65
+ required_in=("create",),
66
+ ),
67
+ io=Column.IO(
68
+ in_verbs=("create",),
69
+ out_verbs=("read", "list", "create"),
70
+ filter_ops=("eq", "in"),
71
+ sortable=True,
72
+ ),
73
+ )
74
+ thread_id = Column(
75
+ storage=Column.S(
76
+ nullable=False,
77
+ index=True,
78
+ fk=ForeignKeySpec("threads.id", on_delete="CASCADE"),
79
+ ),
80
+ field=Column.F(py_type=str, required_in=("create",)),
81
+ io=Column.IO(
82
+ in_verbs=("create",),
83
+ out_verbs=("read", "list", "create"),
84
+ filter_ops=("eq", "in"),
85
+ sortable=True,
86
+ ),
87
+ )
88
+ body = Column(
89
+ storage=Column.S(nullable=False),
90
+ field=Column.F(
91
+ py_type=str,
92
+ constraints={"min_length": 1, "max_length": 10_000},
93
+ required_in=("create",),
94
+ ),
95
+ io=Column.IO(
96
+ in_verbs=("create",),
97
+ out_verbs=("read", "list", "create"),
98
+ ),
99
+ )
100
+ ```
101
+
102
+ Let `Column.F.py_type` drive internal storage-type lowering. Keep channel authorization and publish/subscribe behavior in operation contracts rather than overloading column declarations.
103
+
104
+ ## Realtime semantics
105
+
106
+ - `subscribe` registers the current session sink under a channel and returns an acknowledgement.
107
+ - `publish` emits an id-less JSON-RPC notification to matching sinks and returns delivery counts to the caller.
108
+ - The current canonical broker is process-local memory. It cleans session subscriptions on disconnect but does not provide cross-worker delivery, replay, or durable subscription state.
109
+ - A durable thread row and a broker channel are related by application convention, not by automatic database coupling. Create/authorize the thread before subscribing to its channel.
110
+
111
+ ## Persistence and fanout boundary
112
+
113
+ Use an explicit two-step send path:
114
+
115
+ 1. Call `Message.create` with a stable client-generated id.
116
+ 2. After persistence succeeds, call `Thread.publish` with the same message id and display payload.
117
+ 3. Mark the item delivered only after its id-less notification returns through the socket.
118
+ 4. If publish fails, retain `saved_not_broadcast` state and retry publish without recreating the row.
119
+
120
+ For stronger guarantees, add a transactional outbox in PostgreSQL, an idempotent publisher, and a shared broker. Do not claim atomic save-plus-fanout from the basic demo.
121
+
122
+ ## Custom request/response operation
123
+
124
+ Prefer a model-co-located decorated handler:
125
+
126
+ ```python
127
+ from tigrbl import TableBase, op_ctx
128
+
129
+ class Message(TableBase):
130
+ @op_ctx(alias="request_like", target="custom", arity="collection", bindings=(WS_BINDING,))
131
+ async def request_like(cls, ctx):
132
+ payload = ctx.get("payload", {}) if isinstance(ctx, dict) else ctx.payload
133
+ return {"accepted": True, "request": payload}
134
+ ```
135
+
136
+ Inspect the installed version's examples for the exact handler context and binding arguments. Add `@engine_ctx(...)` when the custom operation must use a non-default engine. Ensure the collected `TableSpec.ops` retains decorated operations during path composition.
@@ -0,0 +1,32 @@
1
+ # Docker and Compose patterns
2
+
3
+ ## Backend image
4
+
5
+ The demos use Python 3.12 slim, copy `pyproject.toml`, source, README, and `tigrcorn.json`, install the app, expose port 8000, and run:
6
+
7
+ ```text
8
+ tigrcorn --config tigrcorn.json --host 0.0.0.0 --port 8000 --protocol http1 --protocol websocket
9
+ ```
10
+
11
+ During sibling-checkout development, Compose supplies `additional_contexts` for `../tigrbl/pkgs` and `../tigrcorn`; the Dockerfile copies them under `/opt` and installs the required package layers editable. Keep this only when testing unreleased local framework sources. For released deployments, install pinned packages from the package index and use a lockfile-driven build.
12
+
13
+ For DuckDB, install the DuckDB SQLAlchemy/provider dependencies, create `/data`, set the database path there, and mount a named volume. For PostgreSQL analytics attachment, install the DuckDB PostgreSQL extension at image build time.
14
+
15
+ ## Compose topology
16
+
17
+ - Backend: build with the required contexts, expose a configurable host port, and inject engine DSNs/paths.
18
+ - Frontend: build from `frontend/`, inject the browser-visible WebSocket URL, and expose the Vite or production-server port.
19
+ - PostgreSQL: use a health check with `pg_isready`, a named data volume, and `depends_on.condition: service_healthy` for the backend.
20
+ - DuckDB-only: mount a named volume at `/data`.
21
+ - PostgreSQL + DuckDB analytics: inject both the SQLAlchemy PostgreSQL DSN and the DuckDB attachment DSN; optionally provide separate inspection UIs for demos.
22
+
23
+ The browser endpoint must use a host-reachable address such as `ws://127.0.0.1:${PORT}/ws/realtime`, not the internal Compose service name. Server-to-server proxy targets may use service DNS.
24
+
25
+ ## Production adjustments
26
+
27
+ - Replace development servers and editable source installs with pinned, reproducible builds.
28
+ - Run as a non-root user, add container health checks, and bound resources.
29
+ - Inject secrets through the deployment platform, not committed environment values.
30
+ - Terminate TLS and use `wss://`; configure origin and proxy upgrade headers.
31
+ - Decide worker count only after replacing or externalizing the process-local realtime broker.
32
+ - Test volume persistence by recreating containers, not merely restarting processes.
@@ -0,0 +1,35 @@
1
+ # Custom and event-driven operations
2
+
3
+ ## Request-like custom operations
4
+
5
+ Use `@op_ctx(alias=..., target="custom", ...)` on the owning table class. Bind the operation to WebSocket JSON-RPC for socket requests or `HttpRestBindingSpec` for HTTP. Read inputs from the operation context payload and return a JSON-serializable result. Bind a named engine with `@engine_ctx` when the operation differs from the app default.
6
+
7
+ Use custom operations for domain commands or queries that canonical create/list/update/delete operations cannot express. Keep authorization, validation, idempotency, transaction scope, and error mapping explicit. Confirm the decorated handler survives `TableSpec.collect` and any `replace(...)` used to create path tables.
8
+
9
+ ## Upon receiving a subscription event
10
+
11
+ Separate the two meanings of “receiving an event”:
12
+
13
+ 1. A browser/client receives an id-less publish notification. Dispatch it through a method handler and optionally call a custom JSON-RPC op. This is the source-backed pattern in the demo frontend.
14
+ 2. The backend must react automatically to a published domain event. The inspected demo does not establish a durable server-side event-consumer hook. Do not invent one. Use a source-backed Tigrbl hook if the target version exposes one, or add an explicit consumer/outbox worker around a durable event record.
15
+
16
+ For a client reaction, send the triggering `event.id` as an idempotency key to the custom op. Record processed ids when duplicate side effects matter. Prevent cycles such as publish → custom op → publish of the same event kind.
17
+
18
+ For a server reaction with production guarantees:
19
+
20
+ 1. Persist the domain mutation and outbox event in one database transaction.
21
+ 2. Have a worker claim pending outbox rows with safe concurrency semantics.
22
+ 3. Invoke the custom domain handler and/or shared realtime broker.
23
+ 4. Mark completion with retry metadata and a stable idempotency key.
24
+ 5. Publish a notification envelope that identifies the source event and version.
25
+
26
+ The current `InMemoryRealtimeBroker` is suitable for single-process fanout demonstrations, not durable event processing or cross-node messaging.
27
+
28
+ ## Verification
29
+
30
+ - Test direct request/response success, validation errors, and engine selection.
31
+ - Test notifications interleaved with unrelated responses.
32
+ - Test duplicate notification delivery and loop prevention.
33
+ - Test save success followed by publish/handler failure and retry.
34
+ - Test authorization for both subscription and the event-triggered custom operation.
35
+ - Test worker restart and idempotent replay when using an outbox.
@@ -0,0 +1,53 @@
1
+ # Data engine topologies
2
+
3
+ ## DuckDB durability
4
+
5
+ Use a file-backed DuckDB `EngineSpec` for a local, embedded durable app:
6
+
7
+ ```python
8
+ EngineSpec(
9
+ kind="duckdb",
10
+ name="duckdb",
11
+ path=str(db_path),
12
+ mapping={"kind": "duckdb", "path": str(db_path), "async": False},
13
+ )
14
+ ```
15
+
16
+ Create the parent directory, register `tigrbl_engine_duckdb`, and let `app.initialize()` create tables. In containers, put the database at a mounted path such as `/data/realtime.duckdb`. DuckDB fits single-process or controlled-writer deployments; assess concurrency before using it for a multi-instance messaging service.
17
+
18
+ ## PostgreSQL durability
19
+
20
+ Use PostgreSQL for the authoritative threads/messages store when multiple processes or clients require concurrent transactional writes:
21
+
22
+ ```python
23
+ EngineSpec(
24
+ kind="postgres",
25
+ name="postgres",
26
+ dsn=dsn,
27
+ mapping={"kind": "postgres", "dsn": dsn, "async": False},
28
+ )
29
+ ```
30
+
31
+ Register `tigrbl_engine_postgres`, wait for database health before starting the app, run initialization through the provider, and persist `/var/lib/postgresql/data` in a named volume. Keep credentials outside committed Compose defaults for non-demo environments.
32
+
33
+ ## PostgreSQL plus DuckDB analytics
34
+
35
+ Use PostgreSQL as the global app engine. Add a named DuckDB engine to `AppSpec.engines`, then bind only analytical custom operations to it with `@engine_ctx` or an explicit per-op engine spec. Attach PostgreSQL into DuckDB with `TYPE postgres, READ_ONLY`; query the attached schema without maintaining a second writable copy.
36
+
37
+ The demo uses an in-memory DuckDB analytical engine and loads the PostgreSQL extension. Its Dockerfile installs the extension during image build so runtime startup does not depend on an extension download. Acquire the named engine through Tigrbl's resolver and always release it in `finally`.
38
+
39
+ Keep analytical operations read-only and bounded:
40
+
41
+ - Clamp query limits.
42
+ - Parameterize values rather than interpolating user input.
43
+ - Escape/configure DSNs safely; prefer secret injection in production.
44
+ - Decide whether analytics require a consistent snapshot or may observe concurrent PostgreSQL changes.
45
+ - Avoid DuckDB private connection attributes when a supported provider method is available in the installed engine version; the demo's `db._c` access is version-sensitive.
46
+
47
+ ## Selection rule
48
+
49
+ - DuckDB file: simplest durable local demo, desktop app, or single-writer service.
50
+ - PostgreSQL: concurrent durable messaging and production-oriented OLTP.
51
+ - PostgreSQL + DuckDB: PostgreSQL durability plus richer analytical SQL without a second writable fact store.
52
+
53
+ Database durability does not make realtime fanout durable. Add a shared broker/outbox/replay design independently when multi-node or offline delivery is required.
@@ -0,0 +1,45 @@
1
+ # Frontend WebSocket JSON-RPC client
2
+
3
+ ## Connection and correlation
4
+
5
+ - Open `new WebSocket(url, "jsonrpc")` and keep one socket per independent user/session.
6
+ - Generate a unique request id for every RPC call and store `{method, resolve, reject}` in a pending map keyed by id.
7
+ - On each frame, parse JSON once. If `id` matches a pending request, resolve `result` or reject `error`, remove the entry, and stop processing that frame.
8
+ - Treat an id-less frame with `method` as a notification. For Tigrbl fanout, read `params.channel` and `params.event`.
9
+ - Reject outstanding requests and clear transport state on close. Reconnect with bounded backoff, then reload history and resubscribe; subscriptions are session-scoped.
10
+
11
+ ## Durable and live state
12
+
13
+ 1. On open, call `Thread.list`; create the selected thread if absent.
14
+ 2. Call `Thread.subscribe` for its authorized channel.
15
+ 3. Call `Message.list` to rehydrate durable history.
16
+ 4. On send, create a stable message id, call `Message.create`, then `Thread.publish`.
17
+ 5. Merge list results and notifications by message id. Never append blindly.
18
+ 6. Track states such as `creating`, `persisted`, `publishing`, `delivered`, `saved_not_broadcast`, and `failed` so the UI represents the true boundary.
19
+
20
+ Notifications can interleave with responses. Never resolve a pending call merely because the next frame arrived. Do not assume notification ordering across reconnects; use durable history as the recovery source of truth.
21
+
22
+ ## Event-driven frontend operations
23
+
24
+ Route notification methods through an explicit handler registry. A handler may update local state and optionally issue a new custom RPC:
25
+
26
+ ```ts
27
+ const notificationHandlers: Record<string, (params: any) => Promise<void> | void> = {
28
+ "Thread.publish": async ({ channel, event }) => {
29
+ mergeMessage(event);
30
+ if (event.kind === "review.requested") {
31
+ await sendJsonRpc("Message.request_like", { channel, source_event_id: event.id });
32
+ }
33
+ },
34
+ };
35
+ ```
36
+
37
+ Guard event-triggered RPCs with stable event ids, a processed-id set or durable idempotency key, authorization checks, and loop prevention. Keep rendering code separate from transport correlation and event orchestration.
38
+
39
+ ## Security and resilience
40
+
41
+ - Derive actor identity and allowed channels from authenticated server context, not payload fields.
42
+ - Validate notification payloads before use.
43
+ - Bound pending requests with timeouts and maximum queue sizes.
44
+ - Define heartbeat, reconnect, replay/cursor, and stale-session behavior for production.
45
+ - Prefer `wss://` outside local development and apply origin policy intentionally.
@@ -0,0 +1,33 @@
1
+ # Source map
2
+
3
+ Use paths relative to the `D:/Code/GitHub/tigrbl` checkout when it is available. Re-inspect current source before copying a pattern because the demos may track unreleased framework behavior.
4
+
5
+ ## Standalone demos
6
+
7
+ - `websocket-realtime-ops-duckdb-demo/`: DuckDB-backed durable threads/messages, React multi-client lab, Docker volume, and three-user proof.
8
+ - `websocket-realtime-ops-postgres/`: PostgreSQL-backed durable threads/messages, React multi-client lab, pgAdmin, failure/retry UI, and three-user proof.
9
+ - `websocket-realtime-postgres-duckdb/`: PostgreSQL authoritative OLTP plus per-operation DuckDB analytics over a read-only PostgreSQL attachment.
10
+ - `tigrbl/examples/websocket_realtime_ops/`: minimal canonical declaration showing `AppSpec`, `RouterSpec`, `PathSpec`, `TableSpec`, `OpSpec`, and the absence of app-local transport loops.
11
+ - `tigrcorn/examples/websocket_uix_demo/`: lower-level Tigrcorn WebSocket UI example; use it for server transport context, not as the preferred Tigrbl app composition model.
12
+
13
+ ## Framework implementation
14
+
15
+ - `tigrbl/pkgs/60_ops/tigrbl_ops_realtime/tigrbl_ops_realtime/ops.py`: current subscribe, publish, session cleanup, and in-memory broker behavior.
16
+ - `tigrbl/pkgs/40_atoms/tigrbl_atoms/tigrbl_atoms/atoms/framing/websocket_jsonrpc.py`: JSON-RPC decode/encode atoms.
17
+ - `tigrbl/pkgs/50_runtime/tigrbl_runtime/tigrbl_runtime/channel/websocket.py`: runtime WebSocket adapter.
18
+ - `tigrbl/pkgs/45_kernel/tigrbl_kernel/tigrbl_kernel/protocol_chains/websocket.py`: protocol-chain composition.
19
+ - `tigrbl/pkgs/70_concrete/tigrbl_concrete/`: app lowering, runtime routing, and engine resolution.
20
+ - `tigrbl/pkgs/80_facade/tigrbl/tigrbl/engine/`: public engine collection, binding, builders, registry, and resolver surfaces.
21
+ - `tigrbl/pkgs/90_engines/tigrbl_engine_postgres/` and `tigrbl_engine_duckdb/`: provider registrations and sessions.
22
+ - `tigrbl/pkgs/96_examples/tigrbl_examples/tigrbl_examples/20_expert_hook_op_engine_bindings/`: decorated custom op and engine-binding examples.
23
+ - `tigrbl/docs/architecture/websocket-realtime-lifecycle-decisions.md`: lifecycle and ownership decisions.
24
+ - `tigrbl/docs/developer/operator/websockets-and-sse.md`: operator-facing transport guidance.
25
+
26
+ ## Verification surfaces
27
+
28
+ - Each standalone demo's `tests/test_demo.py` validates declaration and initialization behavior.
29
+ - Each standalone demo's `tests/test_three_user_realtime.py` validates independent subscriptions, persistence, and fanout.
30
+ - PostgreSQL frontend `src/__tests__/realtimeLab.test.ts` validates response correlation, interleaved notifications, deduplication, and save/publish partial failure.
31
+ - Tigrbl unit and integration tests matching `*websocket*`, `*engine*`, and `*jsonrpc*` validate framework contracts.
32
+
33
+ Prefer runnable source and tests over archived notes. Treat the demo architecture explainer's stated omissions—identity authorization, horizontal fanout, presence, unread counts, and offline queues—as real production gaps.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: build-tigrbl-rest-bulk-crud-app
3
+ description: Build, extend, debug, test, or containerize Tigrbl RestBulkCrudTable applications. Use when Codex needs to implement REST collection and member CRUD, bulk create/update/replace/delete operations, PostgreSQL persistence, OpenAPI contracts, React or other HTTP clients, Docker Compose stacks, engine-overridden tests, or migrations from handwritten CRUD routes to Tigrbl table profiles.
4
+ ---
5
+
6
+ # Build Tigrbl REST Bulk CRUD App
7
+
8
+ ## Workflow
9
+
10
+ 1. Inspect repository instructions, dependency versions, working-tree changes, and the nearest REST bulk CRUD demo before editing. Use `references/source-map.md` to locate canonical examples and framework internals.
11
+ 2. Define the resource contract: primary key, required and optional fields, collection path, member path, create/update/replace semantics, delete payload, response status codes, transaction expectations, authorization boundary, and maximum batch size.
12
+ 3. Compose the table and app with `references/table-and-app.md`. Prefer `RestBulkCrudTable`, a public engine factory, `TigrblApp.include_table(...)`, `app.initialize()`, and generated operations over handwritten route duplication.
13
+ 4. Verify the transport and schema contract with `references/rest-and-openapi.md`. Keep collection and member payloads distinct and confirm generated OpenAPI matches runtime behavior.
14
+ 5. Configure persistence with `references/postgres-and-transactions.md`. Accept a full DSN override, support structured local settings, keep credentials external, and make bulk transaction and partial-failure behavior explicit.
15
+ 6. Build an HTTP client or operator console with `references/frontend-client.md`. Use one request helper, encode member identifiers, validate JSON, trace request/response details, and drive documentation panels from live OpenAPI where practical.
16
+ 7. Containerize and test with `references/containers-and-tests.md`. Use health-gated Compose services, preserve sibling source contexts only for unreleased framework development, and test the complete collection/member route matrix.
17
+ 8. Report the route surface, payload contracts, engine topology, verification evidence, and remaining production gaps such as auth, batch limits, idempotency, concurrency, observability, and rollback policy.
18
+
19
+ ## Guardrails
20
+
21
+ - Declare application table fields with Tigrbl `Column` and `Column.S`, `Column.F`, and `Column.IO`; do not import or directly author SQLAlchemy `Column`, `Mapped`, `mapped_column`, or SQLAlchemy types.
22
+ - Do not hand-author collection or member CRUD routes already supplied by `RestBulkCrudTable` unless a tested framework defect or domain-specific contract requires an override.
23
+ - Do not copy the demo's `BulkDeleteCompatApp`, private `_resolver`, route-list mutation, or custom SQL delete shim without first reproducing the compatibility issue against the target Tigrbl version. Prefer the public generated `bulk_delete` operation when it works.
24
+ - Do not confuse PATCH with PUT: bulk update accepts partial rows with identifiers; bulk replace requires complete replacement rows.
25
+ - Do not expose JSON-RPC, OpenRPC, Lens, or another transport when the requested surface is REST-only.
26
+ - Do not interpolate identifiers or values into SQL. Use Tigrbl operations or parameterized SQLAlchemy expressions for justified custom operations.
27
+ - Do not claim all-or-nothing behavior, stable result ordering, or idempotency without tests against the selected engine and Tigrbl version.
28
+ - Do not use demo credentials or permissive CORS/auth defaults in production.
29
+ - Preserve user changes and run repository-native formatters, type checks, tests, frontend builds, and OpenAPI/runtime assertions before completion.
30
+
31
+ ## Reference routing
32
+
33
+ - Read `references/source-map.md` whenever locating demos, public profiles, operation implementations, schemas, or tests.
34
+ - Read `references/table-and-app.md` for table declarations, app composition, engine factories, initialization, and justified custom endpoints.
35
+ - Read `references/rest-and-openapi.md` for route matrices, payload shapes, status codes, OpenAPI, validation, and error contracts.
36
+ - Read `references/postgres-and-transactions.md` for DSNs, engine selection, transaction guarantees, batch safety, and production persistence.
37
+ - Read `references/frontend-client.md` for React or browser clients, request tracing, member workflows, and OpenAPI inspection.
38
+ - Read `references/containers-and-tests.md` for Docker, Compose, health checks, engine overrides, and end-to-end verification.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Build Tigrbl REST Bulk CRUD App"
3
+ short_description: "Build Tigrbl REST bulk CRUD applications"
4
+ default_prompt: "Use $build-tigrbl-rest-bulk-crud-app to build a PostgreSQL-backed Tigrbl REST bulk CRUD application."
@@ -0,0 +1,39 @@
1
+ # Containers and tests
2
+
3
+ ## Compose topology
4
+
5
+ - PostgreSQL: pin an image, use `pg_isready`, mount a named data volume, and inject database settings.
6
+ - Backend: build the app, depend on healthy PostgreSQL, expose a health route, and inject the database host as the Compose service name.
7
+ - Frontend: build static assets, proxy to the backend service, depend on backend health, and expose a browser port.
8
+
9
+ Use `additional_contexts` for sibling `tigrbl/pkgs` only while testing unreleased local framework code. For released deployments, install pinned packages from a lockfile. Run containers as non-root where practical and keep secrets out of the Compose file.
10
+
11
+ ## Backend tests
12
+
13
+ Use an in-memory synchronous engine override for fast contract tests while preserving PostgreSQL as the authored runtime default. Test:
14
+
15
+ 1. Structured PostgreSQL settings and full DSN override.
16
+ 2. Health and sanitized configuration endpoints.
17
+ 3. OpenAPI collection/member paths and exact method sets.
18
+ 4. Absence of unintended transports for a REST-only app.
19
+ 5. Bulk create with multiple rows.
20
+ 6. Bulk patch preserving omitted fields.
21
+ 7. Bulk replace requiring complete rows.
22
+ 8. List and member read after mutations.
23
+ 9. Member patch, replace, and delete.
24
+ 10. Bulk delete and remaining state.
25
+ 11. Empty, invalid, duplicate, missing, and oversized batches.
26
+
27
+ Add PostgreSQL integration tests for transaction, constraint, type, concurrency, and rollback behavior that an in-memory engine cannot prove.
28
+
29
+ ## Frontend and system tests
30
+
31
+ - Run the frontend type check/lint and production build.
32
+ - Test request construction for every method and payload shape.
33
+ - Test failure rendering, trace correlation, selection behavior, and duplicate-submit prevention.
34
+ - Start the Compose stack, wait for health, execute the full CRUD matrix, inspect OpenAPI, and recreate PostgreSQL to prove volume persistence.
35
+ - Test proxy body limits and timeouts with the largest supported batch.
36
+
37
+ ## Completion evidence
38
+
39
+ Report exact commands and results, the Tigrbl and engine versions tested, active route matrix, OpenAPI assertions, database topology, batch limits, and any compatibility shim. Identify what remains unproven rather than generalizing from the memory-engine suite.