Rename vgi/examples → vgi/_test_fixtures; gate fixture deps behind extras

The "examples" directory has grown to ~12,000 lines / 16 files — it's
the regression-test fixture catalog used by the pytest suite, the C++
sqllogictest harness, and the conformance suite, not tutorial code.
Calling it "examples" misled readers and pulled fixture-only deps
(numpy, sqlglot) into the core install.

What changed:

- Moved 13 fixture files vgi/examples/*.py → vgi/_test_fixtures/*.py and
  3 writable-related files into vgi/_test_fixtures/writable/ as a
  subpackage. vgi/transactor/ stays at top level — it's production code,
  not a fixture, even though only the writable fixtures consume it today.

- Renamed vgi-example-* scripts to vgi-fixture-* (no deprecation shims
  per request). vgi-transactor keeps its name. vgi-fixture-worker still
  serves both example and writable catalogs, falling back to example-only
  when the writable extra is absent.

- Gated deps behind new extras:
  - [test-fixtures] → numpy
  - [transactor] → sqlglot
  - [test-fixtures-writable] → vgi[test-fixtures] + vgi[transactor]
  - [dev] now includes all of the above so contributors don't notice
  - Core install drops numpy + sqlglot

- Friendly errors: vgi-fixture-worker, vgi-fixture-writable-worker, and
  vgi-transactor each emit a clear "install vgi[X]" message and exit 1
  when the relevant extra is missing, instead of a raw ImportError.

- Swept all import sites and script-name references across CLAUDE.md,
  README.md, docs/cli.md, vgi/client/cli.py help/default, conftest
  (example_worker → fixture_worker), tests, and the C++ companion repo.

Verified:
- uv run mypy vgi/ → clean
- uv run pytest tests/ -n auto → 1526 passed / 71 skipped
- Lean-install smoke test (no extras): `from vgi.client import Client`
  works; vgi-fixture-worker / vgi-fixture-writable-worker / vgi-transactor
  all print the install hint and exit 1
- C++ aggregate suite passes (12 / 3 skipped) under
  VGI_TEST_WORKER=vgi-fixture-worker
- C++ database_tags.test passes with the renamed worker tag

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rustyconover

CLAUDE.md

@@ -64,7 +64,7 @@ ensure all tests pass — not just the new/changed test file. Adding a function
 **Subprocess transport** (worker spawned as a child process):
 ```bash
 cd ~/Development/vgi
-VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-example-worker" \
+VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-fixture-worker" \
     ./build/release/test/unittest "test/sql/integration/*"
 ```
 
@@ -110,7 +110,7 @@ with elapsed milliseconds. This helps identify slow queries and bottlenecks.
 ```bash
 # Timing output goes to stderr, grep for the bracket-prefixed lines:
 cd ~/Development/vgi
-VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-example-worker" \
+VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-fixture-worker" \
     ./build/release/test/unittest "test/sql/integration/table/writable_table*" \
     2>&1 | grep "^\[stmt\|^\[query" | sort -t']' -k2 -rn
 ```
@@ -157,7 +157,7 @@ Subprocess worker wrapper (`/tmp/vgi-coverage-worker.sh`):
 ```bash
 #!/bin/bash
 cd /Users/rusty/Development/vgi-python
-exec uv run coverage run --parallel-mode -m vgi.examples.worker "$@"
+exec uv run coverage run --parallel-mode -m vgi._test_fixtures.worker "$@"
 ```
 
 HTTP server wrapper (`~/Development/vgi/test/run_http_integration_coverage.sh`):
@@ -189,8 +189,8 @@ external record batch offloading without S3 or any cloud infrastructure.
 
 **Running the example server with demo storage:**
 ```bash
-vgi-example-http --demo-storage
-vgi-example-http --demo-storage --externalize-threshold-bytes 4096 --externalize-compression zstd
+vgi-fixture-http --demo-storage
+vgi-fixture-http --demo-storage --externalize-threshold-bytes 4096 --externalize-compression zstd
 ```
 
 When `--demo-storage` is enabled:
@@ -230,9 +230,9 @@ FIXME: complete this.
 ## CLI Commands
 
 ```bash
-vgi-example-worker                                                    # Run example worker
-vgi-client --input data.parquet --function echo --worker vgi-example-worker
-vgi-client --input data.parquet --function sum_all_columns --worker vgi-example-worker
+vgi-fixture-worker                                                    # Run example worker
+vgi-client --input data.parquet --function echo --worker vgi-fixture-worker
+vgi-client --input data.parquet --function sum_all_columns --worker vgi-fixture-worker
 ```
 
 ## Environment Variables
@@ -276,7 +276,7 @@ Set `VGI_WORKER_DEBUG=1` to enable comprehensive debugging for worker failures.
 2. **Client side**: Forces `passthrough_stderr=True`, streaming worker logs to the terminal in real-time
 
 ```bash
-VGI_WORKER_DEBUG=1 vgi-example-worker
+VGI_WORKER_DEBUG=1 vgi-fixture-worker
 ```
 
 When used from the Python client without this env var, errors from worker failures automatically include captured stderr (last 50 lines) in the `ClientError` message. This means integrators using C++ or other clients get the Python traceback in the error message instead of just a generic exit code.
@@ -301,7 +301,7 @@ Accepts `1`, `true`, or `yes` (case-insensitive). Zero overhead when not set.
 Enable `VGI_FILTER_DEBUG=1` to trace filter pushdown deserialization, parsing, and evaluation. Useful for debugging filter pushdown issues and understanding how filters are applied.
 
 ```bash
-VGI_FILTER_DEBUG=1 vgi-example-worker
+VGI_FILTER_DEBUG=1 vgi-fixture-worker
 ```
 
 **Key events logged:**
@@ -415,7 +415,7 @@ during the bind phase, allowing output schema to depend on setting values.
 Client passes settings when invoking a method:
 
 ```python
-with Client("vgi-example-worker") as client:
+with Client("vgi-fixture-worker") as client:
     for batch in client.table_function(
         function_name="settings_aware",
         arguments=Arguments(positional=(pa.scalar(10),)),

README.md

@@ -433,10 +433,10 @@ without S3 or any cloud infrastructure:
 
 ```bash
 # Start with demo storage (4 KiB threshold for testing)
-vgi-example-http --demo-storage --externalize-threshold-bytes 4096
+vgi-fixture-http --demo-storage --externalize-threshold-bytes 4096
 
 # With zstd compression
-vgi-example-http --demo-storage --externalize-threshold-bytes 4096 --externalize-compression zstd
+vgi-fixture-http --demo-storage --externalize-threshold-bytes 4096 --externalize-compression zstd
 ```
 
 When `--demo-storage` is enabled:
@@ -465,13 +465,13 @@ Workers support `--debug`, `--log-level`, `--log-format`, and `--log-logger` opt
 
 ```bash
 # Enable debug logging
-vgi-example-worker --debug
+vgi-fixture-worker --debug
 
 # JSON-formatted logs for structured pipelines
-vgi-example-worker --log-format json
+vgi-fixture-worker --log-format json
 
 # Target a specific logger
-vgi-example-worker --log-level DEBUG --log-logger vgi.worker
+vgi-fixture-worker --log-level DEBUG --log-logger vgi.worker
 ```
 
 You can also use the `VGI_WORKER_DEBUG=1` environment variable, which enables `--debug` on the worker and stderr passthrough on the client without changing any code or CLI flags:

docs/cli.md

@@ -7,8 +7,7 @@ VGI provides CLI tools for invoking functions and managing catalogs without writ
 | Command | Description |
 |---------|-------------|
 | `vgi-client` | Invoke functions and manage catalogs |
-| `vgi-example-worker` | Run the example worker with demo functions |
-| `vgi-example-catalog-worker` | Run an in-memory catalog for testing |
+| `vgi-fixture-worker` | Run the example worker with demo functions |
 
 ---
 
@@ -31,7 +30,7 @@ vgi-client [OPTIONS]
 | `--format FORMAT` | Output format: `json` (default), `csv`, `parquet` |
 | `--function NAME` | Function name to invoke |
 | `--args JSON` | Function arguments as JSON array (default: `[]`) |
-| `--worker PATH` | Worker command (default: `vgi-example-worker`) |
+| `--worker PATH` | Worker command (default: `vgi-fixture-worker`) |
 | `--type TYPE` | Function type: `auto`, `table`, `table-in-out`, `scalar` |
 | `--projection-id N` | Column IDs to project (repeatable) |
 | `--max-workers N` | Limit parallel workers |
@@ -492,7 +491,7 @@ vgi-client catalog detach $ATTACH_ID --worker ./worker.py
 
 ## Worker Logging
 
-All workers that use `Worker.main()` (including `vgi-example-worker`) support
+All workers that use `Worker.main()` (including `vgi-fixture-worker`) support
 logging options on the command line. Logs are written to stderr.
 
 ### Options
@@ -511,16 +510,16 @@ logging options on the command line. Logs are written to stderr.
 
 ```bash
 # Enable debug logging
-vgi-example-worker --debug
+vgi-fixture-worker --debug
 
 # Set WARNING level only
-vgi-example-worker --log-level WARNING
+vgi-fixture-worker --log-level WARNING
 
 # Target a specific logger at DEBUG
-vgi-example-worker --log-level DEBUG --log-logger vgi.worker
+vgi-fixture-worker --log-level DEBUG --log-logger vgi.worker
 
 # JSON-formatted logs (for structured log pipelines)
-vgi-example-worker --log-format json
+vgi-fixture-worker --log-format json
 ```
 
 ### Available Loggers
@@ -594,12 +593,12 @@ app = create_app(
 
 ## Example Workers
 
-### vgi-example-worker
+### vgi-fixture-worker
 
 Runs the built-in example worker with demo functions.
 
 ```bash
-vgi-example-worker
+vgi-fixture-worker
 ```
 
 **Available functions:**
@@ -628,12 +627,13 @@ vgi-example-worker
 | `bernoulli` | scalar | Generate random booleans (VOLATILE) |
 | `random_bytes` | scalar | Generate pseudo-random binary blobs |
 
-### vgi-example-catalog-worker
+### In-memory catalog example
 
-Runs an in-memory catalog implementation for testing.
+The mutable catalog demo (`vgi/examples/catalog.py`) is no longer installed as a
+console script. Run it from a source checkout via:
 
 ```bash
-vgi-example-catalog-worker
+python -m vgi._test_fixtures.catalog
 ```
 
 ---

pyproject.toml

@@ -7,10 +7,8 @@ requires-python = ">=3.13"
 dependencies = [
     "click",
     "pyarrow",
-    "sqlglot",
     "typer>=0.9",
     "platformdirs",
-    "numpy>=2.4.1",
     "vgi-rpc @ file:///Users/rusty/Development/vgi-rpc",
     "duckdb>=1.5.0",
 ]
@@ -23,6 +21,12 @@ azure = [
     "pymssql>=2.3.0",
     "azure-identity>=1.16.0",
 ]
+test-fixtures = ["numpy>=2.4.1"]
+transactor = ["sqlglot"]
+test-fixtures-writable = [
+    "vgi[test-fixtures]",
+    "vgi[transactor]",
+]
 dev = [
     "mypy",
     "pyarrow-stubs",
@@ -32,17 +36,18 @@ dev = [
     "pytest-ruff",
     "pytest-xdist",
     "ruff",
+    "vgi[test-fixtures,test-fixtures-writable,http,oauth,otel,azure]",
     "vgi-rpc[conformance,external,http,oauth,otel]",
 ]
 [project.scripts]
 vgi-serve = "vgi.serve:main"
 vgi-client = "vgi.client.cli:main"
-vgi-example-worker = "vgi.examples.worker:main"
-vgi-example-http = "vgi.examples.http_server:main"
-vgi-example-versioned-worker = "vgi.examples.versioned:main"
-vgi-example-versioned-tables-worker = "vgi.examples.versioned_tables:main"
-vgi-example-attach-options-worker = "vgi.examples.attach_options:main"
-vgi-example-writable-worker = "vgi.examples.writable_worker:main"
+vgi-fixture-worker = "vgi._test_fixtures.worker:main"
+vgi-fixture-http = "vgi._test_fixtures.http_server:main"
+vgi-fixture-versioned-worker = "vgi._test_fixtures.versioned:main"
+vgi-fixture-versioned-tables-worker = "vgi._test_fixtures.versioned_tables:main"
+vgi-fixture-attach-options-worker = "vgi._test_fixtures.attach_options:main"
+vgi-fixture-writable-worker = "vgi._test_fixtures.writable.worker:main"
 vgi-transactor = "vgi.transactor.server:main"
 
 [tool.hatch.metadata]
@@ -85,7 +90,7 @@ ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
 # These files have type: ignore comments for ty that mypy doesn't need
-module = ["vgi.examples.scalar", "vgi.table_function"]
+module = ["vgi._test_fixtures.scalar", "vgi.table_function"]
 warn_unused_ignores = false
 
 [tool.ty.environment]
@@ -107,8 +112,8 @@ sigterm = true
 branch = true
 # What to measure
 source = ["vgi"]
-# Omit test files and examples from coverage
-omit = ["vgi/examples/*", "tests/*"]
+# Omit test fixtures and tests from coverage
+omit = ["vgi/_test_fixtures/*", "tests/*"]
 
 [tool.coverage.report]
 # Fail if coverage drops below this threshold

scripts/measure_startup.py

@@ -105,7 +105,7 @@ def profile_startup_phases() -> None:
     profiler.enable()
 
     # Import the worker module
-    import vgi.examples.worker  # noqa: F401
+    import vgi._test_fixtures.worker  # noqa: F401
 
     profiler.disable()
 
@@ -138,8 +138,8 @@ def main() -> None:
     )
     parser.add_argument(
         "--worker",
-        default="vgi-example-worker",
-        help="Worker command to measure (default: vgi-example-worker)",
+        default="vgi-fixture-worker",
+        help="Worker command to measure (default: vgi-fixture-worker)",
     )
     args = parser.parse_args()
 
@@ -154,7 +154,7 @@ def main() -> None:
 
     if args.importtime:
         print("\n### Import Time Analysis ###\n")
-        import_times = measure_importtime("vgi.examples.worker")
+        import_times = measure_importtime("vgi._test_fixtures.worker")
 
         # Sort by cumulative time (descending)
         sorted_times = sorted(import_times.items(), key=lambda x: -x[1])
@@ -190,7 +190,7 @@ def main() -> None:
 
     # Also show import time summary
     print("\n### Top 10 Slowest Imports ###\n")
-    import_times = measure_importtime("vgi.examples.worker")
+    import_times = measure_importtime("vgi._test_fixtures.worker")
     sorted_times = sorted(import_times.items(), key=lambda x: -x[1])
 
     print(f"{'Module':<50} {'Time (ms)':>10}")

tests/_http_fixtures.py

@@ -1,4 +1,4 @@
-"""Shared helpers for spawning ``vgi-example-http`` as a subprocess.
+"""Shared helpers for spawning ``vgi-fixture-http`` as a subprocess.
 
 Lifted from ``tests/test_http_demo_storage.py`` so that conformance tests and
 other HTTP-dependent tests can reuse a single lifecycle.
@@ -29,15 +29,15 @@ def run_example_http_server(
     extra_args: Sequence[str] = (),
     env: dict[str, str] | None = None,
 ) -> Iterator[None]:
-    """Run ``vgi-example-http`` in a subprocess on ``port``.
+    """Run ``vgi-fixture-http`` in a subprocess on ``port``.
 
     ``extra_args`` are appended verbatim — e.g. ``("--demo-storage",
     "--externalize-threshold-bytes", "4096")``.
     """
     cmd = [
         sys.executable,
         "-m",
-        "vgi.examples.http_server",
+        "vgi._test_fixtures.http_server",
         "--host",
         "127.0.0.1",
         "--port",
@@ -75,7 +75,7 @@ def start_http_worker(
     extra_args: Sequence[str] = (),
     env: dict[str, str] | None = None,
 ) -> str:
-    """Allocate a port, start ``vgi-example-http`` under ``stack``, return base URL."""
+    """Allocate a port, start ``vgi-fixture-http`` under ``stack``, return base URL."""
     port = free_port()
     base_url = f"http://127.0.0.1:{port}"
     stack.enter_context(run_example_http_server(port=port, extra_args=tuple(extra_args), env=env))

tests/catalog/test_client_catalog.py

@@ -8,10 +8,12 @@
 see tests/catalog/test_integration.py which exercises all catalog operations.
 """
 
+import sys
+
 from vgi.client import Client
 
 # Worker command for catalog tests
-CATALOG_WORKER = "vgi-example-catalog-worker"
+CATALOG_WORKER = f"{sys.executable} -m vgi._test_fixtures.catalog"
 
 
 class TestClientCatalogStatelessOperations:

tests/catalog/test_example_worker_catalog.py

@@ -6,6 +6,7 @@
 
 import pyarrow as pa
 
+from vgi._test_fixtures.worker import ExampleWorker
 from vgi.catalog import (
     AttachId,
     FunctionInfo,
@@ -17,10 +18,9 @@
     ViewInfo,
 )
 from vgi.client import Client
-from vgi.examples.worker import ExampleWorker
 
 # Worker command for catalog tests
-EXAMPLE_WORKER = "vgi-example-worker"
+EXAMPLE_WORKER = "vgi-fixture-worker"
 
 
 def _get_expected_function_names() -> set[str]:
@@ -132,8 +132,17 @@ def test_all_example_functions_listed(self) -> None:
             )
         )
 
+        # Get aggregate functions
+        aggregate_funcs = list(
+            client.schema_contents(
+                attach_id=attach_result.attach_id,
+                name="main",
+                type=SchemaObjectType.AGGREGATE_FUNCTION,
+            )
+        )
+
         # Combine all functions
-        contents = table_funcs + scalar_funcs
+        contents = table_funcs + scalar_funcs + aggregate_funcs
 
         # Get function names
         function_names = {item.name for item in contents}