sqlbenchdag 0.1.0__tar.gz

sqlbenchdag-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 Ramona C. Truta
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sqlbenchdag-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: sqlbenchdag
+Version: 0.1.0
+Summary: A reproducible, content-addressed SQL engine benchmarking laboratory.
+Author: Ramona C. Truta
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/rctruta/sql-benchmarks-dagster
+Project-URL: Repository, https://github.com/rctruta/sql-benchmarks-dagster
+Keywords: benchmarking,sql,duckdb,postgres,dagster,reproducibility,provenance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dagster
+Requires-Dist: dagster-cloud
+Requires-Dist: dagster-postgres
+Requires-Dist: dagster-duckdb
+Requires-Dist: docker
+Requires-Dist: pandas
+Requires-Dist: plotly
+Requires-Dist: polars
+Requires-Dist: pyarrow
+Requires-Dist: psycopg2-binary
+Requires-Dist: sqlalchemy
+Requires-Dist: psutil
+Requires-Dist: pyyaml
+Requires-Dist: numpy
+Requires-Dist: paramiko<4.0.0
+Requires-Dist: sshtunnel>=0.4.0
+Requires-Dist: scp>=0.14.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typedb-driver
+Provides-Extra: dev
+Requires-Dist: dagster-webserver; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# SQL Benchmarking Laboratory
+
+> **A deterministic, orchestrated harness for verifying database performance at scale.**
+> Developed by Ramona C. Truta
+
+---
+
+## The Mission: "Ground Truth" as Code
+
+This platform is a specialized laboratory for testing SQL performance hypotheses. It transforms query tuning from intuition into a reproducible science. 
+
+The core of the system is a **Deterministic Orchestration Harness** that guarantees that if the logic or the environment changes, the benchmark result changes. If they do not, the result is addressable and cached.
+
+**Scope:** the focus to date is **synthetic and canonical (TPC-H) data**, which
+is the right instrument for *mechanism* experiments — where controlled,
+reproducible data isolates the variable under test. Real-data support exists but
+is experimental; see the [FAQ](FAQ.md) for the synthetic-vs-real rationale, the
+container model, and the roadmap (AI-security testbed, real-data trust chain).
+
+---
+
+## Key Features & Innovations
+
+### 1. Context-Aware Semantic Hashing (The Experiment ID)
+The Heart of the system is the **Experiment ID**, an 8-character hash that governs the entire lifecycle. This hash is a SHA-256 fingerprint generated from:
+*   **The Config**: Every dimension in your YAML (rows, skew, parameters).
+*   **The SQL Logic**: The actual content of the benchmarked scripts.
+*   **The Code**: All measurement-relevant Python — orchestration (`assets/`), engine clients (`resources/`), and data generators (`plugins/`).
+
+**Semantic Normalization**: The hashing engine distinguishes between a logic change and a formatting change. 
+*   **SQL**: Comments, whitespace, and case are normalized before hashing.
+*   **Python**: Orchestration scripts are parsed into an **Abstract Syntax Tree (AST)** to strip docstrings and formatting variations, ensuring the Experiment ID only changes when execution logic changes.
+
+### 2. Multi-Layer Cold-Cache Isolation
+To ensure IO-bound performance is not masked by memory buffers, we implement a dual-layer cold start mechanism:
+*   **Out-of-Process (Postgres)**: Mandatory **Docker Container Restarts** before every query to clear engine-level shared buffers.
+*   **Global OS Flush (mmap)**: A specialized `thrash_os_cache` primitive that maps and dirties a file larger than physical RAM. This forces the OS to evict Page Cache entries, ensuring cold read performance for both containerized and in-process (DuckDB) engines.
+
+### 3. Agentic AI Integration
+The platform is built for the future of **Autonomous Engineering**. The Experiment ID allows AI agents to treat the laboratory as a **Deterministic Performance API**.
+*   See [AGENTS.md](AGENTS.md) for the full Agentic Benchmarking Protocol.
+
+### 4. Declarative Matrix Orchestration
+Benchmarks are defined as N-dimensional matrices in YAML. The platform expands these into a Cartesian product of **Independent Dagster Partitions**. This allows for parallel dispatch and granular retries.
+
+---
+
+## Usage & Technical Setup
+
+### Prerequisites
+*   **[uv](https://astral.sh/uv)**: the project's Python environment & dependency manager (fast, modern). `setup.sh` uses it, and it can install Python 3.11 for you.
+*   **Python 3.11+**: core runtime (uv provisions it if missing).
+*   **Docker**: for the containerized engines (Postgres, TypeDB), which the harness manages itself — *not* required for the DuckDB-only quickstart.
+
+### Installation & Setup
+The laboratory includes a comprehensive setup script that manages virtual environments, dependencies, and directory initialization.
+
+```bash
+# 1. Automate Setup
+chmod +x setup.sh && ./setup.sh
+
+# 2. Activate Laboratory
+source venv/bin/activate
+```
+
+### The Execution Workflow (CLI)
+While the system is powered by Dagster, the primary interface is the CLI for automated workflows.
+
+```bash
+# QUICKSTART: DuckDB only, no Docker required — runs in seconds
+./run.sh sql_benchmarks/experiments/queue/quickstart.yaml --auto
+
+# FULL BENCHMARK: Run all queued experiments (requires Docker for Postgres)
+./run.sh queue --auto
+
+# SINGLE EXPERIMENT: Pass a specific config path
+./run.sh sql_benchmarks/experiments/queue/quack_execution_modes.yaml --auto
+```
+
+To write your own experiment, start from the annotated template and see the
+catalog of published runs in **[docs/experiments.md](docs/experiments.md)**.
+
+---
+
+## Project Structure
+Managed with a strict separation between Harness and Scenario:
+
+```text
+/sql_benchmarks
+├── /assets                 # THE HARNESS: Dagster factories & pipeline logic
+├── /resources              # THE INFRASTRUCTURE: DB drivers & Docker management
+├── /scripts/sql            # THE SCENARIOS: Raw SQL partitioned by scenario
+├── /plugins                # THE DATA: Declarative generators & scenario providers
+├── /utils                  # THE BRAIN: AST-hashing, common logic, & system primitives
+└── /experiments            # THE LABORATORY
+    ├── active.yaml         # Current active partition matrix
+    ├── /queue              # Staging area for new experiment configs
+    ├── /archive            # Library of previously defined experiment templates
+    ├── /configs            # Registry of immutable, hash-addressed experiment capsules
+    └── /results            # Data capsules: fragments, CSVs, and Dashboards
+```
+
+---
+
+## Published Experiments — the Quack investigation
+
+The first published study with this lab: an independent measurement of DuckDB's
+**Quack** client-server protocol (beta, v1.5.3). Each row links the runnable
+config to its committed, verifiable capsule. Full numbers, scaling exponents,
+and verification steps in [docs/published_capsules.md](docs/published_capsules.md).
+
+| Act | Question | Config | Capsule | Finding |
+| :--- | :--- | :--- | :--- | :--- |
+| **I** | What does the protocol cost? | [quack_execution_modes.yaml](sql_benchmarks/experiments/queue/quack_execution_modes.yaml) | `b8e2bfaf` | Attach-mode overhead grows with scan size (2.6× → **9.5×** at 10M rows); pushdown stays flat at ~2×. |
+| **II** | Why is pushdown ~2× and not 1×? | [quack_residual_threads.yaml](sql_benchmarks/experiments/queue/quack_residual_threads.yaml) | `25b0e134` | The residual tracks reduced server-side parallelism (~2–4 of 8 threads), not transport. |
+| **III** | Does it generalize to joins? | [tpch_quack_validation.yaml](sql_benchmarks/experiments/queue/tpch_quack_validation.yaml) | `b198363e` | On canonical TPC-H Q3, pushdown holds (~1.9×); attach mode **cannot run the join at all** (DNF). |
+| **IV** | Does it beat the incumbent? | [quack_vs_postgres.yaml](sql_benchmarks/experiments/queue/quack_vs_postgres.yaml) | `902d1277` | DuckDB-over-Quack (pushdown) beats PostgreSQL by up to **13.2×**, and the gap widens with scale. |
+
+*Act 0 (`b82b4eae`) is the exploratory scout that started it — see [docs/published_capsules.md](docs/published_capsules.md).*
+
+The lab also ships scenario suites for other studies — `selectivity/`,
+`null_logic/`, `null_sentinel/`, `recursion/`, `sort_spill/`, `tpch/`, and more
+under `sql_benchmarks/scripts/sql/` — each runnable across the engine matrix.
+
+---
+
+## Naming & Provenance
+
+The lab works at two layers, named two different ways. Keeping them distinct is
+the difference between a number you can trace and a number you have to trust.
+
+| Layer | What it is | Named by | Example |
+| :--- | :--- | :--- | :--- |
+| **Capsule** | one experiment's complete results | its **Experiment ID** — an 8-char SHA-256 of the *question* (config + SQL + measurement code), assigned by the machine | `48c92f31` |
+| **Release** | a signed set of capsules backing a publication | a human name: **`sqlbenchdag-<topic>-v<N>-<YYYYMMDD>`** | `sqlbenchdag-quack-v1-20260614` |
+
+A release *contains* capsules; a capsule is one experiment. The machine names
+capsules (hashes you can't forge); the author names releases (words that mean
+something). `sqlbenchdag` is the lab's maker's mark — `sql` + `bench` +
+`dag` (Dagster, the orchestration that distinguishes this lab from a bare query
+timer). It is carried on every release this lab produces.
+
+**Two hashes, two jobs** (a capsule contains both — they are not the same thing):
+- the **Experiment ID** (8 chars) is an *address* — it *names* the capsule, and
+  the same question always produces the same address;
+- the **integrity seal** (64 chars, in `integrity.seal`) is a *checksum* — it
+  *verifies* the capsule's contents are untouched. You file by the address; the
+  seal is the tamper-evident lid.
+
+**Reproducibility is pinned to the release.** Because the Experiment ID hashes
+the measurement code, it is stable only at a fixed code revision — which is
+exactly what the signed release tag freezes. To reproduce a published capsule,
+check out its release tag and re-run its config; the same question yields the
+same ID, or the comparison is refused by construction.
+
+> Provenance roadmap: a per-capsule `generator` stamp (`sqlbenchdag@<commit>`)
+> will record the exact build that produced each capsule. It writes through the
+> finalization code, which lives inside the Experiment-ID hash, so it ships with
+> a future release rather than re-numbering capsules already published.
+
+See [docs/published_capsules.md](docs/published_capsules.md) for the full trust
+chain (reproducibility, integrity, timestamp, authorship) and how to verify each.
+Reproducibility and integrity are **automatic** on every run; timestamp and
+signature are **optional** steps you add only when publishing — the producer
+workflow is [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+---
+
+## License
+
+Copyright 2025-2026 Ramona C. Truta. Licensed under the [Apache License 2.0](LICENSE).
+
+Built with **Dagster**, **Polars**, **Docker**, **DuckDB**, and **Postgres**.

sqlbenchdag-0.1.0/README.md

@@ -0,0 +1,173 @@
+# SQL Benchmarking Laboratory
+
+> **A deterministic, orchestrated harness for verifying database performance at scale.**
+> Developed by Ramona C. Truta
+
+---
+
+## The Mission: "Ground Truth" as Code
+
+This platform is a specialized laboratory for testing SQL performance hypotheses. It transforms query tuning from intuition into a reproducible science. 
+
+The core of the system is a **Deterministic Orchestration Harness** that guarantees that if the logic or the environment changes, the benchmark result changes. If they do not, the result is addressable and cached.
+
+**Scope:** the focus to date is **synthetic and canonical (TPC-H) data**, which
+is the right instrument for *mechanism* experiments — where controlled,
+reproducible data isolates the variable under test. Real-data support exists but
+is experimental; see the [FAQ](FAQ.md) for the synthetic-vs-real rationale, the
+container model, and the roadmap (AI-security testbed, real-data trust chain).
+
+---
+
+## Key Features & Innovations
+
+### 1. Context-Aware Semantic Hashing (The Experiment ID)
+The Heart of the system is the **Experiment ID**, an 8-character hash that governs the entire lifecycle. This hash is a SHA-256 fingerprint generated from:
+*   **The Config**: Every dimension in your YAML (rows, skew, parameters).
+*   **The SQL Logic**: The actual content of the benchmarked scripts.
+*   **The Code**: All measurement-relevant Python — orchestration (`assets/`), engine clients (`resources/`), and data generators (`plugins/`).
+
+**Semantic Normalization**: The hashing engine distinguishes between a logic change and a formatting change. 
+*   **SQL**: Comments, whitespace, and case are normalized before hashing.
+*   **Python**: Orchestration scripts are parsed into an **Abstract Syntax Tree (AST)** to strip docstrings and formatting variations, ensuring the Experiment ID only changes when execution logic changes.
+
+### 2. Multi-Layer Cold-Cache Isolation
+To ensure IO-bound performance is not masked by memory buffers, we implement a dual-layer cold start mechanism:
+*   **Out-of-Process (Postgres)**: Mandatory **Docker Container Restarts** before every query to clear engine-level shared buffers.
+*   **Global OS Flush (mmap)**: A specialized `thrash_os_cache` primitive that maps and dirties a file larger than physical RAM. This forces the OS to evict Page Cache entries, ensuring cold read performance for both containerized and in-process (DuckDB) engines.
+
+### 3. Agentic AI Integration
+The platform is built for the future of **Autonomous Engineering**. The Experiment ID allows AI agents to treat the laboratory as a **Deterministic Performance API**.
+*   See [AGENTS.md](AGENTS.md) for the full Agentic Benchmarking Protocol.
+
+### 4. Declarative Matrix Orchestration
+Benchmarks are defined as N-dimensional matrices in YAML. The platform expands these into a Cartesian product of **Independent Dagster Partitions**. This allows for parallel dispatch and granular retries.
+
+---
+
+## Usage & Technical Setup
+
+### Prerequisites
+*   **[uv](https://astral.sh/uv)**: the project's Python environment & dependency manager (fast, modern). `setup.sh` uses it, and it can install Python 3.11 for you.
+*   **Python 3.11+**: core runtime (uv provisions it if missing).
+*   **Docker**: for the containerized engines (Postgres, TypeDB), which the harness manages itself — *not* required for the DuckDB-only quickstart.
+
+### Installation & Setup
+The laboratory includes a comprehensive setup script that manages virtual environments, dependencies, and directory initialization.
+
+```bash
+# 1. Automate Setup
+chmod +x setup.sh && ./setup.sh
+
+# 2. Activate Laboratory
+source venv/bin/activate
+```
+
+### The Execution Workflow (CLI)
+While the system is powered by Dagster, the primary interface is the CLI for automated workflows.
+
+```bash
+# QUICKSTART: DuckDB only, no Docker required — runs in seconds
+./run.sh sql_benchmarks/experiments/queue/quickstart.yaml --auto
+
+# FULL BENCHMARK: Run all queued experiments (requires Docker for Postgres)
+./run.sh queue --auto
+
+# SINGLE EXPERIMENT: Pass a specific config path
+./run.sh sql_benchmarks/experiments/queue/quack_execution_modes.yaml --auto
+```
+
+To write your own experiment, start from the annotated template and see the
+catalog of published runs in **[docs/experiments.md](docs/experiments.md)**.
+
+---
+
+## Project Structure
+Managed with a strict separation between Harness and Scenario:
+
+```text
+/sql_benchmarks
+├── /assets                 # THE HARNESS: Dagster factories & pipeline logic
+├── /resources              # THE INFRASTRUCTURE: DB drivers & Docker management
+├── /scripts/sql            # THE SCENARIOS: Raw SQL partitioned by scenario
+├── /plugins                # THE DATA: Declarative generators & scenario providers
+├── /utils                  # THE BRAIN: AST-hashing, common logic, & system primitives
+└── /experiments            # THE LABORATORY
+    ├── active.yaml         # Current active partition matrix
+    ├── /queue              # Staging area for new experiment configs
+    ├── /archive            # Library of previously defined experiment templates
+    ├── /configs            # Registry of immutable, hash-addressed experiment capsules
+    └── /results            # Data capsules: fragments, CSVs, and Dashboards
+```
+
+---
+
+## Published Experiments — the Quack investigation
+
+The first published study with this lab: an independent measurement of DuckDB's
+**Quack** client-server protocol (beta, v1.5.3). Each row links the runnable
+config to its committed, verifiable capsule. Full numbers, scaling exponents,
+and verification steps in [docs/published_capsules.md](docs/published_capsules.md).
+
+| Act | Question | Config | Capsule | Finding |
+| :--- | :--- | :--- | :--- | :--- |
+| **I** | What does the protocol cost? | [quack_execution_modes.yaml](sql_benchmarks/experiments/queue/quack_execution_modes.yaml) | `b8e2bfaf` | Attach-mode overhead grows with scan size (2.6× → **9.5×** at 10M rows); pushdown stays flat at ~2×. |
+| **II** | Why is pushdown ~2× and not 1×? | [quack_residual_threads.yaml](sql_benchmarks/experiments/queue/quack_residual_threads.yaml) | `25b0e134` | The residual tracks reduced server-side parallelism (~2–4 of 8 threads), not transport. |
+| **III** | Does it generalize to joins? | [tpch_quack_validation.yaml](sql_benchmarks/experiments/queue/tpch_quack_validation.yaml) | `b198363e` | On canonical TPC-H Q3, pushdown holds (~1.9×); attach mode **cannot run the join at all** (DNF). |
+| **IV** | Does it beat the incumbent? | [quack_vs_postgres.yaml](sql_benchmarks/experiments/queue/quack_vs_postgres.yaml) | `902d1277` | DuckDB-over-Quack (pushdown) beats PostgreSQL by up to **13.2×**, and the gap widens with scale. |
+
+*Act 0 (`b82b4eae`) is the exploratory scout that started it — see [docs/published_capsules.md](docs/published_capsules.md).*
+
+The lab also ships scenario suites for other studies — `selectivity/`,
+`null_logic/`, `null_sentinel/`, `recursion/`, `sort_spill/`, `tpch/`, and more
+under `sql_benchmarks/scripts/sql/` — each runnable across the engine matrix.
+
+---
+
+## Naming & Provenance
+
+The lab works at two layers, named two different ways. Keeping them distinct is
+the difference between a number you can trace and a number you have to trust.
+
+| Layer | What it is | Named by | Example |
+| :--- | :--- | :--- | :--- |
+| **Capsule** | one experiment's complete results | its **Experiment ID** — an 8-char SHA-256 of the *question* (config + SQL + measurement code), assigned by the machine | `48c92f31` |
+| **Release** | a signed set of capsules backing a publication | a human name: **`sqlbenchdag-<topic>-v<N>-<YYYYMMDD>`** | `sqlbenchdag-quack-v1-20260614` |
+
+A release *contains* capsules; a capsule is one experiment. The machine names
+capsules (hashes you can't forge); the author names releases (words that mean
+something). `sqlbenchdag` is the lab's maker's mark — `sql` + `bench` +
+`dag` (Dagster, the orchestration that distinguishes this lab from a bare query
+timer). It is carried on every release this lab produces.
+
+**Two hashes, two jobs** (a capsule contains both — they are not the same thing):
+- the **Experiment ID** (8 chars) is an *address* — it *names* the capsule, and
+  the same question always produces the same address;
+- the **integrity seal** (64 chars, in `integrity.seal`) is a *checksum* — it
+  *verifies* the capsule's contents are untouched. You file by the address; the
+  seal is the tamper-evident lid.
+
+**Reproducibility is pinned to the release.** Because the Experiment ID hashes
+the measurement code, it is stable only at a fixed code revision — which is
+exactly what the signed release tag freezes. To reproduce a published capsule,
+check out its release tag and re-run its config; the same question yields the
+same ID, or the comparison is refused by construction.
+
+> Provenance roadmap: a per-capsule `generator` stamp (`sqlbenchdag@<commit>`)
+> will record the exact build that produced each capsule. It writes through the
+> finalization code, which lives inside the Experiment-ID hash, so it ships with
+> a future release rather than re-numbering capsules already published.
+
+See [docs/published_capsules.md](docs/published_capsules.md) for the full trust
+chain (reproducibility, integrity, timestamp, authorship) and how to verify each.
+Reproducibility and integrity are **automatic** on every run; timestamp and
+signature are **optional** steps you add only when publishing — the producer
+workflow is [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+---
+
+## License
+
+Copyright 2025-2026 Ramona C. Truta. Licensed under the [Apache License 2.0](LICENSE).
+
+Built with **Dagster**, **Polars**, **Docker**, **DuckDB**, and **Postgres**.

sqlbenchdag-0.1.0/infrastructure/debug_aws.py

@@ -0,0 +1,40 @@
+import boto3
+import sys
+
+def check_instance_viability():
+    # Setup AWS client
+    # This will use the credentials from ~/.aws/credentials which the user already set up
+    ec2 = boto3.client('ec2', region_name='us-east-1')
+
+    print("--- DIAGNOSTIC: Checking t2.micro availability ---")
+    
+    try:
+        # 1. Describe Offerings to find valid AZs for t2.micro
+        response = ec2.describe_instance_type_offerings(
+            LocationType='availability-zone',
+            Filters=[{'Name': 'instance-type', 'Values': ['t2.micro']}]
+        )
+        
+        valid_azs = [o['Location'] for o in response['InstanceTypeOfferings']]
+        print(f"Valid AZs for t2.micro: {valid_azs}")
+        
+        if not valid_azs:
+            print("CRITICAL: t2.micro is NOT available in this region/account.")
+            return False
+
+        # 2. Check current default subnets
+        subnets = ec2.describe_subnets(Filters=[{'Name': 'default-for-az', 'Values': ['true']}])
+        print(f"Default Subnets Found: {len(subnets['Subnets'])}")
+        
+        for s in subnets['Subnets']:
+            print(f" - Subnet {s['SubnetId']} in {s['AvailabilityZone']}")
+            
+        print("--------------------------------------------------")
+        return True
+
+    except Exception as e:
+        print(f"AWS Error: {e}")
+        return False
+
+if __name__ == "__main__":
+    check_instance_viability()