docs: correct catalog capabilities and worker requirements

Author: rustyconover

docs/api/index.md

@@ -32,7 +32,7 @@ added incrementally.
 | [Auth & Secrets](auth.md) | `AuthContext`, `CallContext`, bearer/JWT authenticators, secret protocol | HTTP: `[http]`; JWT: `[oauth]` |
 | [Observability](observability.md) | OpenTelemetry tracing, worker logging configuration | `[otel]` for tracing |
 | [HTTP](http.md) | Worker page, blob storage, request-size middleware | `pip install vgi-python[http]` |
-| [Transactor](transactor.md) | `TransactorClient`, `TransactorProtocol` | `pip install vgi-python[transactor]` |
+| [Transactor](transactor.md) | `TransactorClient`, `TransactorProtocol` | `[transactor]` extra and a [compatible engine build](transactor.md#runtime-requirements) |
 | [Exceptions](exceptions.md) | VGI exception types | — |
 
 ## Import Convention

docs/api/transactor.md

@@ -6,7 +6,27 @@
     [function patterns](../how-to/function-patterns.md) if you're new to VGI.
 
 The transactor is a long-lived subprocess that gives worker functions transactional access to a
-database, mediated by `TransactorClient` over the `TransactorProtocol`. Requires
-`pip install vgi-python[transactor]`.
+database, mediated by `TransactorClient` over the `TransactorProtocol`.
+
+## Runtime requirements
+
+The bundled transactor requires both:
+
+- `pip install 'vgi-python[transactor]'` for its Python dependencies.
+- A VGI fork build of `duckdb-python` providing `DuckDBPyConnection.subcursor()`,
+  which lets reads share an open write transaction. This extension has not yet
+  been merged into Haybarn or upstream DuckDB; installing the extra alone is
+  insufficient.
+
+Engine resolution prefers `haybarn` when installed, then falls back to `duckdb`.
+Use an environment where the selected engine provides `subcursor()`; installing
+a compatible `duckdb` build alongside an incompatible `haybarn` installation
+does not override that preference.
+
+These requirements apply to the bundled transactor. Workers can implement
+[table writes](../catalog-interface.md#table-writes-and-indexes) against their own
+backing data sources without using it.
+
+## API
 
 ::: vgi.transactor

docs/authentication.md

@@ -24,7 +24,7 @@ the principal in the `AuthContext` available to functions.
 | Variable | Description |
 |----------|-------------|
 | `VGI_BEARER_TOKENS` | Comma-separated `token=principal` pairs for static bearer auth |
-| `VGI_JWT_ISSUER` | JWT issuer URL (requires `vgi[oauth]` extra) |
+| `VGI_JWT_ISSUER` | JWT issuer URL (requires `vgi-python[oauth]` extra) |
 | `VGI_JWT_AUDIENCE` | JWT audience string, comma-separated for multiple audiences (required when `VGI_JWT_ISSUER` is set) |
 | `VGI_JWT_JWKS_URI` | JWKS endpoint URL (auto-discovered from issuer if omitted) |
 | `VGI_OAUTH_RESOURCE` | OAuth resource URL for RFC 9728 metadata |

docs/catalog-interface.md

@@ -944,16 +944,41 @@ if __name__ == "__main__":
 
 ---
 
-## API Limitations
+## Catalog capabilities and limitations { #api-limitations }
 
 The current CatalogInterface has the following limitations:
 
 - **Functions**: Cannot be created or dropped via catalog methods (use `Worker.functions`)
 - **Tags**: Cannot be updated after object creation
 - **Schema metadata**: Comments and tags cannot be updated on schemas
 - **Constraints**: Only NOT NULL can be added/dropped (no ALTER for UNIQUE/CHECK)
-- **Indexes**: Not supported
-- **INSERT/UPDATE/DELETE**: Not yet implemented (metadata only)
+
+### Table writes and indexes
+
+`INSERT`, `UPDATE`, and `DELETE` are supported when the catalog supplies a write
+function for the operation. For declarative catalogs, configure the
+[`Table`][vgi.catalog.descriptors.Table] descriptor:
+
+| Operation | Descriptor field | Requirement |
+|-----------|------------------|-------------|
+| `INSERT` | `insert_function` | A `TableInOutGenerator` that accepts rows to insert |
+| `UPDATE` | `update_function` | A write function and a scan `function` that provides row IDs |
+| `DELETE` | `delete_function` | A write function and a scan `function` that provides row IDs |
+
+Each field defaults to `None`, which leaves that operation unsupported. Custom
+catalogs implement `table_insert_function_get()`, `table_update_function_get()`,
+or `table_delete_function_get()` to return the corresponding `ScanFunctionResult`.
+The worker's write functions implement the changes to the backing data source;
+declaring a table alone does not make it writable.
+
+`ReadOnlyCatalogInterface` rejects catalog DDL, but can expose these write functions
+on declarative tables. Table writes do not require the bundled
+[transactor](api/transactor.md); that is an optional database-access service with
+additional engine requirements.
+
+Index metadata can be declared with [`Index`][vgi.catalog.descriptors.Index]. Custom
+catalogs can implement `index_get()`, `index_create()`, and `index_drop()`; support
+depends on the catalog implementation and backing data source.
 
 ---
 

docs/cli.md

@@ -545,7 +545,7 @@ vgi-fixture-worker --log-format json
 | `VGI_QUIET=1` | Suppress the interactive-terminal startup warning (same as `--quiet`) |
 | `VGI_FILTER_DEBUG=1` | Enable filter pushdown debug logging |
 | `VGI_BEARER_TOKENS` | Comma-separated `token=principal` pairs for static bearer auth (HTTP only) |
-| `VGI_JWT_ISSUER` | JWT issuer URL for JWT/JWKS auth (requires `vgi[oauth]` extra) |
+| `VGI_JWT_ISSUER` | JWT issuer URL for JWT/JWKS auth (requires `vgi-python[oauth]` extra) |
 | `VGI_JWT_AUDIENCE` | JWT audience string, comma-separated for multiple audiences (required when `VGI_JWT_ISSUER` is set) |
 | `VGI_JWT_JWKS_URI` | JWKS endpoint URL (auto-discovered if omitted) |
 | `VGI_OAUTH_RESOURCE` | OAuth resource URL for RFC 9728 metadata |

docs/how-to/function-patterns.md

@@ -1,5 +1,5 @@
 ---
-description: "How to write each of the four VGI function patterns: scalar, table, table-in-out, and aggregate — with a complete runnable worker for each."
+description: "How to write each of the five VGI function patterns: scalar, table, table-in-out, aggregate, and buffering — with a complete runnable worker for each."
 ---
 
 # Function patterns
@@ -178,11 +178,14 @@ ATTACH 'aggregates' (TYPE vgi, LOCATION 'uv run sum_worker.py');
 SELECT category, aggregates.vgi_sum(value) FROM t GROUP BY category;
 ```
 
-??? info "State must be an `ArrowSerializableDataclass`"
-    Table generators and aggregates keep state between calls. Because that state is serialized
-    across parallel workers (aggregates) and HTTP round-trips, the framework requires it to extend
-    `ArrowSerializableDataclass`. Annotate fields with `ArrowType(...)` so the wire type is
-    explicit.
+??? info "State must be serializable"
+    Table generators and aggregates keep state between calls. A state type must provide
+    `serialize_to_bytes()` and `deserialize_from_bytes()` so the framework can carry it across
+    HTTP round-trips or persist it between aggregate calls. `ArrowSerializableDataclass`
+    implements these methods for you and is the usual starting point. Custom state types can
+    implement the same [`StreamStateCodec`][vgi.function.StreamStateCodec] contract without
+    inheriting from `ArrowSerializableDataclass`. See
+    [State Class](../aggregate-functions.md#state-class) for both approaches.
 
 ## Buffering
 

docs/how-to/state-storage.md

@@ -22,9 +22,11 @@ function that coordinates partial results across workers.
 
 ## Two kinds of "state" — don't confuse them
 
-- **Generator cursor state** — the small `ArrowSerializableDataclass` a table generator keeps
-  *within one scan* (see [streaming with state](function-patterns.md#streaming-with-state)). It
-  lives in the worker for the duration of the call.
+- **Generator cursor state** — the small serializable object a table generator keeps
+  *within one scan* (see [streaming with state](function-patterns.md#streaming-with-state)).
+  Over HTTP, the framework serializes it between requests. `ArrowSerializableDataclass`
+  supplies the serialization methods; custom types can implement
+  [`StreamStateCodec`][vgi.function.StreamStateCodec] instead.
 - **Shared storage** (this page) — state that must outlive a single call or be shared across
   **separate worker processes**, e.g. combining partial aggregate results. This is backed by a
   pluggable store.

docs/shared-storage.md

@@ -10,7 +10,7 @@ variable.
 | Backend | Value | Use Case | Dependencies |
 |---------|-------|----------|-------------|
 | SQLite | `sqlite` (default) | Local / subprocess transport | None (stdlib) |
-| Azure SQL | `azure-sql` | Azure cloud deployments | `vgi[azure]` |
+| Azure SQL | `azure-sql` | Azure cloud deployments | `vgi-python[azure]` |
 | Cloudflare DO | `cloudflare-do` | Edge / multi-cloud deployments | None (stdlib) |
 
 ## SQLite (Default)
@@ -36,7 +36,7 @@ workers run on separate hosts.
 1. Install the Azure extra:
 
 ```bash
-pip install vgi[azure]
+pip install 'vgi-python[azure]'
 ```
 
 2. Create an Azure SQL Database (Serverless recommended for cost):

vgi/_duckdb.py

@@ -7,8 +7,8 @@
 fixtures) resolves it through this module, which prefers Query Farm's
 ``haybarn`` distribution when installed and falls back to stock ``duckdb``.
 
-Install one via the extras: ``pip install vgi[haybarn]`` (preferred) or
-``pip install vgi[duckdb]``.
+Install one via the extras: ``pip install 'vgi-python[haybarn]'`` (preferred) or
+``pip install 'vgi-python[duckdb]'``.
 """
 
 from __future__ import annotations
@@ -50,7 +50,7 @@ def engine_module() -> ModuleType:
         else:
             raise ImportError(
                 "No DuckDB-compatible engine is installed. Install 'haybarn' (preferred) "
-                "or 'duckdb', e.g. `pip install vgi[haybarn]` or `pip install vgi[duckdb]`."
+                "or 'duckdb', e.g. `pip install 'vgi-python[haybarn]'` or `pip install 'vgi-python[duckdb]'`."
             )
     return _engine