vgi-python 0.26.0__tar.gz → 0.27.0__tar.gz

{vgi_python-0.26.0 → vgi_python-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.26.0
+Version: 0.27.0
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python

vgi_python-0.27.0/RELEASE-RUNBOOK.md

@@ -0,0 +1,69 @@
+# Release runbook — describe.json retirement + attach-option `required`
+
+All code is committed on `main` in each repo and green. Nothing is pushed.
+This is the ordering and the per-repo trigger; fill in `X.Y.Z` per package.
+
+**Version decision needed first.** Three transports drop `DescribeProvider`
+from their public API (breaking): `@query-farm/vgi-rpc`, `vgi-rpc` (Rust),
+`farm.query:vgirpc`. Choose major or minor per your compatibility policy — it
+cascades into the implementation pins below.
+
+## 1. Transports (must publish first)
+
+| Repo | Trigger | Version lives in |
+|---|---|---|
+| vgi-rpc-typescript | `gh release create vX.Y.Z` (release: published) | `package.json` (+ `bun install` to sync `bun.lock`) |
+| vgi-rpc-rust | tag push — `gh release create vX.Y.Z` | `[workspace.package] version`; `cargo update -w` |
+| vgi-rpc-java | `gh release create vX.Y.Z` (release: published) | `build.gradle.kts` |
+| vgi-rpc-go | tag push — `gh release create vX.Y.Z` | none (module proxy reads the tag) |
+
+Then wait for index propagation: npm, `https://index.crates.io/3/v/vgi-rpc`,
+Maven Central, Go proxy.
+
+## 2. Implementation dependency pins
+
+These currently cannot build against published transports:
+
+- **vgi-typescript** — peer range is `>=0.18.1 <0.19.0`; widen to the new
+  transport version. `LandingInfo` resolves only once the transport publishes.
+- **vgi-rust** — workspace dep already bumped to `vgi-rpc 0.20.0`; adjust if you
+  pick a different number. The `[patch.crates-io]` block stays uncommitted (it
+  is documented in `Cargo.toml` for local co-development only).
+- **vgi-java** — bump `api("farm.query:vgirpc:X")` and the `VGI_RPC_JAVA_REF`
+  pin in `.github/workflows/integration.yml`. (`landing.yml` was deleted with
+  the contract it checked.)
+- **vgi-go** — self-contained; no pin, but it needs the new vgi-rpc-go tag.
+
+## 3. Implementations
+
+| Repo | Trigger | Version lives in |
+|---|---|---|
+| vgi-python | `gh release create vX.Y.Z --target main` (PyPI on release) | root `pyproject.toml`; `uv lock` |
+| vgi-go | `gh release create vX.Y.Z` (tag → module proxy) | none |
+| vgi-rust | `gh release create vX.Y.Z` (tag → crates.io) | `[workspace.package] version` |
+| vgi-typescript | **`git tag vX.Y.Z && git push origin vX.Y.Z`** — pushing the bump to main does NOT publish and fails silently | `package.json`; `bun install` |
+| vgi-java | `gh release create vX.Y.Z` (Maven Central on release) | `build.gradle.kts` |
+
+## 4. Frontend
+
+- **vgi-web-frontend** — auto-deploys on push to `main`. Push last, so no worker
+  is serving a page newer than its vendored bundle.
+
+## Verified before release
+
+- vgi-python 2175 pass / 99 skip; ruff + mypy clean
+- vgi-go `go test ./...` clean; vet + gofmt clean
+- vgi-rust tests pass; clippy `-D warnings` clean
+- vgi-java `:vgi:test` passes
+- vgi-rpc-typescript 715 pass / 26 fail — exactly the pre-change baseline
+  (confirmed by running the suite at the parent commit in a worktree)
+- Landing page verified in a browser against all four language workers:
+  Python 221 functions, Go 221, Rust 654, Java 219 — each 2 schemas, 59 tables,
+  3 views, with lazy columns loading.
+
+## Not done, tracked
+
+- `vgi-rpc-typescript` has 26 pre-existing test failures (integration/streaming;
+  unrelated to this work, present before it).
+- `~/vgi-java/CLAUDE.md` still references the landing-conformance workflow in
+  its historical notes; the workflow itself is deleted.

{vgi_python-0.26.0 → vgi_python-0.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.26.0"
+version = "0.27.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

vgi_python-0.27.0/tests/catalog/test_attach_option.py

@@ -0,0 +1,192 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Tests for the AttachOption descriptor, its ``required`` flag, and validation."""
+
+from typing import Annotated
+
+import pyarrow as pa
+import pytest
+from vgi_rpc.utils import deserialize_record_batch, serialize_record_batch_bytes
+
+from vgi.catalog._descriptor_spec import _SpecBase
+from vgi.catalog.attach_option import (
+    AttachOption,
+    AttachOptionSpec,
+    MissingAttachOptionsError,
+    extract_attach_option_specs,
+    validate_required_attach_options,
+)
+from vgi.catalog.catalog_interface import ReadOnlyCatalogInterface
+from vgi.catalog.setting import SettingSpec
+
+
+class _Options:
+    """Attach options mixing defaulted and required entries."""
+
+    region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
+    # No class-level assignment: nothing to fall back to, so the caller must supply it.
+    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+
+
+def _roundtrip(spec: AttachOptionSpec) -> AttachOptionSpec:
+    batch, _ = deserialize_record_batch(spec.serialize())
+    return AttachOptionSpec.deserialize(batch)
+
+
+class TestRequiredExtraction:
+    """Extraction of the ``required`` flag from Annotated declarations."""
+
+    def test_defaults_to_false(self) -> None:
+        """An option that isn't declared required isn't required."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["region"].required is False
+        assert specs["region"].default == "us-east-1"
+
+    def test_required_option_extracted(self) -> None:
+        """``required=True`` survives extraction, with no default."""
+        specs = {s.name: s for s in extract_attach_option_specs(_Options)}
+        assert specs["api_key"].required is True
+        assert specs["api_key"].default is None
+
+    def test_required_with_default_rejected(self) -> None:
+        """A required option that also defaults is contradictory."""
+        with pytest.raises(ValueError, match="required but also declares a default"):
+            AttachOptionSpec(name="api_key", desc="", type=pa.string(), default="fallback", required=True)
+
+
+class TestWireFormat:
+    """Serialization of the added ``required`` column."""
+
+    @pytest.mark.parametrize("required", [True, False], ids=["required", "optional"])
+    def test_roundtrip_preserves_required(self, required: bool) -> None:
+        """``required`` survives an Arrow IPC round trip in both states."""
+        spec = AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=required)
+        assert _roundtrip(spec).required is required
+
+    def test_roundtrip_preserves_shared_fields(self) -> None:
+        """Widening the schema doesn't disturb the four shared columns."""
+        spec = AttachOptionSpec(name="region", desc="AWS region", type=pa.string(), default="us-east-1")
+        restored = _roundtrip(spec)
+        assert (restored.name, restored.desc, restored.type, restored.default) == (
+            "region",
+            "AWS region",
+            pa.string(),
+            "us-east-1",
+        )
+
+    def test_setting_wire_format_unchanged(self) -> None:
+        """``Setting`` keeps the original four columns; only AttachOption widened."""
+        assert SettingSpec.ARROW_SCHEMA.names == ["name", "description", "type", "default_value"]
+        assert AttachOptionSpec.ARROW_SCHEMA.names == [
+            "name",
+            "description",
+            "type",
+            "default_value",
+            "required",
+        ]
+
+    def test_reads_batch_without_required_column(self) -> None:
+        """A peer that predates the column yields ``required=False``, not an error."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        legacy = pa.RecordBatch.from_pylist(
+            [{"name": "region", "description": "AWS region", "type": type_bytes, "default_value": None}],
+            schema=_SpecBase.ARROW_SCHEMA,
+        )
+        restored = AttachOptionSpec.deserialize(legacy)
+        assert restored.required is False
+        assert restored.name == "region"
+
+    def test_older_reader_ignores_required_column(self) -> None:
+        """A four-column reader still reads a five-column batch (forward compatible)."""
+        spec = AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=True)
+        batch, _ = deserialize_record_batch(spec.serialize())
+        legacy_read = SettingSpec.deserialize(batch)
+        assert legacy_read.name == "api_key"
+        assert legacy_read.default is None
+
+    def test_null_required_reads_as_false(self) -> None:
+        """An explicit null in the nullable column means "not required"."""
+        type_bytes = pa.schema([pa.field("value", pa.string())]).serialize().to_pybytes()
+        batch = pa.RecordBatch.from_pylist(
+            [
+                {
+                    "name": "region",
+                    "description": "",
+                    "type": type_bytes,
+                    "default_value": None,
+                    "required": None,
+                }
+            ],
+            schema=AttachOptionSpec.ARROW_SCHEMA,
+        )
+        # Round-trip through IPC the way a real peer's bytes would arrive.
+        restored, _ = deserialize_record_batch(serialize_record_batch_bytes(batch))
+        assert AttachOptionSpec.deserialize(restored).required is False
+
+
+class TestValidateRequiredAttachOptions:
+    """The shared validation helper."""
+
+    SPECS = [
+        AttachOptionSpec(name="region", desc="", type=pa.string(), default="us-east-1"),
+        AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True),
+    ]
+
+    def test_missing_required_raises(self) -> None:
+        """Omitting a required option raises with the names attached."""
+        with pytest.raises(MissingAttachOptionsError) as exc:
+            validate_required_attach_options("demo", self.SPECS, {"region": "eu-west-1"})
+        assert exc.value.missing == ["api_key"]
+        assert "'api_key'" in str(exc.value)
+
+    def test_supplied_required_passes(self) -> None:
+        """Supplying the required option is enough; defaults cover the rest."""
+        validate_required_attach_options("demo", self.SPECS, {"api_key": "secret"})
+
+    def test_case_insensitive_match(self) -> None:
+        """DuckDB lowercases ATTACH option keys; matching follows."""
+        validate_required_attach_options("demo", self.SPECS, {"API_KEY": "secret"})
+
+    def test_no_required_specs_always_passes(self) -> None:
+        """A catalog with no required options accepts an empty mapping."""
+        validate_required_attach_options("demo", [self.SPECS[0]], {})
+
+    def test_multiple_missing_reported_together(self) -> None:
+        """Every missing option is reported in one error, not one at a time."""
+        specs = [
+            AttachOptionSpec(name="api_key", desc="", type=pa.string(), default=None, required=True),
+            AttachOptionSpec(name="tenant", desc="", type=pa.string(), default=None, required=True),
+        ]
+        with pytest.raises(MissingAttachOptionsError) as exc:
+            validate_required_attach_options("demo", specs, {})
+        assert exc.value.missing == ["api_key", "tenant"]
+
+
+class _GatedCatalog(ReadOnlyCatalogInterface):
+    """Read-only catalog that cannot be attached without ``api_key``."""
+
+    catalog_name = "gated"
+    attach_option_specs = [
+        AttachOptionSpec(name="api_key", desc="API key", type=pa.string(), default=None, required=True),
+    ]
+
+
+class TestCatalogAttachEnforcement:
+    """The default ``catalog_attach`` refuses an attach missing required options."""
+
+    def test_attach_without_required_option_raises(self) -> None:
+        """The attach fails loudly rather than yielding an empty-looking catalog."""
+        with pytest.raises(MissingAttachOptionsError, match="api_key"):
+            _GatedCatalog().catalog_attach(
+                name="gated", options={}, data_version_spec=None, implementation_version=None
+            )
+
+    def test_attach_with_required_option_succeeds(self) -> None:
+        """Supplying the option attaches normally."""
+        result = _GatedCatalog().catalog_attach(
+            name="gated",
+            options={"api_key": "secret"},
+            data_version_spec=None,
+            implementation_version=None,
+        )
+        assert result.attach_opaque_data is not None

{vgi_python-0.26.0 → vgi_python-0.27.0}/tests/test_serve.py

@@ -698,8 +698,9 @@ class TestCLI:
             # Give server a moment to start
             time.sleep(0.5)
 
-            # The landing surface: GET / serves the shared static page (which
-            # fetches its data via JS), and the worker name lives in describe.json.
+            # The landing surface: GET / serves the shared static page, which
+            # reads the catalog over the protocol using the client bundle the
+            # worker serves beside it. Worker identity rides on the status doc.
             import json as _json
             import urllib.request
 
@@ -709,10 +710,14 @@ class TestCLI:
                 assert resp.status == 200
                 assert b"vgi-landing-asset" in body
 
-            with urllib.request.urlopen(f"{url}describe.json", timeout=5) as resp:
+            with urllib.request.urlopen(f"{url}?format=json", timeout=5) as resp:
                 doc = _json.loads(resp.read())
-                assert doc["worker"]["name"] == "ExampleWorker"
-                assert doc["landing_schema_version"] >= 1
+                assert doc["worker"] == "ExampleWorker"
+                assert doc["lang"] == "python"
+
+            with urllib.request.urlopen(f"{url}vgi-client.js", timeout=5) as resp:
+                assert resp.status == 200
+                assert resp.headers["Content-Type"].startswith("text/javascript")
         finally:
             proc.terminate()
             proc.wait(timeout=5)

{vgi_python-0.26.0 → vgi_python-0.27.0}/uv.lock

@@ -2338,7 +2338,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.26.0"
+version = "0.27.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.26.0 → vgi_python-0.27.0}/vgi/_test_fixtures/attach_options.py

@@ -31,7 +31,12 @@ from vgi_rpc import ArrowSerializableDataclass
 from vgi_rpc.rpc import CallContext, OutputCollector
 from vgi_rpc.utils import deserialize_record_batch, serialize_record_batch_bytes
 
-from vgi.catalog.attach_option import AttachOption, AttachOptionSpec, extract_attach_option_specs
+from vgi.catalog.attach_option import (
+    AttachOption,
+    AttachOptionSpec,
+    extract_attach_option_specs,
+    validate_required_attach_options,
+)
 from vgi.catalog.catalog_interface import (
     AttachOpaqueData,
     CatalogAttachResult,
@@ -53,6 +58,10 @@ __all__ = [
 
 
 CATALOG_NAME = "attach_options"
+# A second catalog from the same worker, declaring one option the caller must
+# supply. Kept separate from CATALOG_NAME so the defaults-and-round-trip
+# coverage above can keep attaching with no options at all.
+REQUIRED_CATALOG_NAME = "attach_options_required"
 _ATTACH_ID_SEP = b"\x00"
 _UUID_BYTES = 16
 
@@ -109,9 +118,19 @@ class AttachOptions:
     ] = {"a": 1, "b": "x"}
 
 
+class RequiredAttachOptions:
+    """Attach-time options for the catalog that refuses an anonymous ATTACH."""
+
+    # No class-level assignment: there is no default to fall back on, so the
+    # caller has to supply it.
+    api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+    region: Annotated[str, AttachOption(desc="Region")] = "us-east-1"
+
+
 # Resolve once at import time; used both to build the echo function's output schema
 # and to backfill defaults in catalog_attach.
 _ATTACH_OPTION_SPECS: list[AttachOptionSpec] = extract_attach_option_specs(AttachOptions)
+_REQUIRED_OPTION_SPECS: list[AttachOptionSpec] = extract_attach_option_specs(RequiredAttachOptions)
 
 _ECHO_SCHEMA: pa.Schema = schema({spec.name: spec.type for spec in _ATTACH_OPTION_SPECS})
 
@@ -244,8 +263,14 @@ class AttachOptionsCatalog(ReadOnlyCatalogInterface):
         ctx: CallContext | None = None,
     ) -> CatalogAttachResult:
         del data_version_spec, implementation_version, ctx
-        if name != CATALOG_NAME:
-            raise ValueError(f"Unknown catalog: {name!r}. Available: {CATALOG_NAME}")
+        if name not in (CATALOG_NAME, REQUIRED_CATALOG_NAME):
+            raise ValueError(f"Unknown catalog: {name!r}. Available: {CATALOG_NAME}, {REQUIRED_CATALOG_NAME}")
+
+        if name == REQUIRED_CATALOG_NAME:
+            # This interface overrides catalog_attach, so the base class's check
+            # never runs — an overrider that declares required options calls the
+            # shared validator itself.
+            validate_required_attach_options(name, _REQUIRED_OPTION_SPECS, options)
 
         attach_opaque_data = _encode_attach_opaque_data(options)
 
@@ -270,6 +295,12 @@ class AttachOptionsCatalog(ReadOnlyCatalogInterface):
                 data_version_spec=None,
                 attach_option_specs=[spec.serialize() for spec in _ATTACH_OPTION_SPECS],
             ),
+            CatalogInfo(
+                name=REQUIRED_CATALOG_NAME,
+                implementation_version=None,
+                data_version_spec=None,
+                attach_option_specs=[spec.serialize() for spec in _REQUIRED_OPTION_SPECS],
+            ),
         ]
 
     def catalog_version(

{vgi_python-0.26.0 → vgi_python-0.27.0}/vgi/_test_fixtures/http_server.py

@@ -412,25 +412,16 @@ def main() -> None:
                     mw._exempt_prefixes = (*mw._exempt_prefixes, f"{prefix}/__blobs__")
 
         if describe:
-            # Standardized landing surface (shared static page + JSON contract),
-            # describing the reference ExampleWorker catalog.
-            from vgi.http.landing_page import (
-                ColumnsResource,
-                DescribeJsonResource,
-                LandingPageResource,
-            )
+            # Standardized landing surface: the shared static page plus the
+            # browser client build it reads the catalog with.
+            from vgi.http.landing_page import ClientBundleResource, LandingPageResource
 
             oauth_active = oauth_metadata is not None and getattr(oauth_metadata, "client_id", None) is not None
             server_id = getattr(server, "server_id", "")
-            wsgi_app.add_route(prefix or "/", LandingPageResource(server_id=server_id))
-            wsgi_app.add_route(
-                f"{prefix}/describe.json",
-                DescribeJsonResource(ExampleWorker, oauth=oauth_active, server_id=server_id),
-            )
             wsgi_app.add_route(
-                f"{prefix}/describe/{{catalog}}/{{schema}}/{{table}}.json",
-                ColumnsResource(ExampleWorker),
+                prefix or "/", LandingPageResource(ExampleWorker, server_id=server_id, oauth=oauth_active)
             )
+            wsgi_app.add_route(f"{prefix}/vgi-client.js", ClientBundleResource())
 
         # vgi_rpc's make_wsgi_app already advertises VGI-Max-Request-Bytes and
         # installs a Falcon middleware enforcing it with a structured 413 that

{vgi_python-0.26.0 → vgi_python-0.27.0}/vgi/catalog/_descriptor_spec.py

@@ -5,9 +5,16 @@
 [`Setting`][vgi.catalog.setting.Setting] (session-level, resent every call) and
 [`AttachOption`][vgi.catalog.attach_option.AttachOption] (delivered once at
 ``catalog_attach``) are declared the same way — an `Annotated`-hint descriptor
-plus a serializable spec with an identical Arrow IPC wire format. This module
+plus a serializable spec sharing the same four Arrow IPC columns. This module
 holds the machinery both share; the two public modules subclass it so their
-names, wire format, and behaviour are unchanged.
+names and behaviour are unchanged.
+
+A subclass may widen its wire format with additional columns — `AttachOption`
+adds ``required`` — via :meth:`_SpecBase._extra_row` /
+:meth:`_SpecBase._extra_kwargs` and :meth:`_DescriptorBase.extra_spec_kwargs`.
+Because both directions read by column name, the widening is compatible in both
+directions: a reader ignores columns it doesn't know, and a reader whose peer
+never wrote the column falls back to the field default.
 """
 
 from __future__ import annotations
@@ -97,6 +104,24 @@ class _SpecBase:
         ]  # type: ignore[arg-type]
     )
 
+    def _extra_row(self) -> dict[str, Any]:
+        """Extra wire columns this spec contributes beyond the shared four.
+
+        Subclasses that widen :data:`ARROW_SCHEMA` return the matching values
+        here. Keys must exist in the subclass's schema.
+        """
+        return {}
+
+    @classmethod
+    def _extra_kwargs(cls, row: dict[str, object]) -> dict[str, Any]:
+        """Constructor kwargs read from the extra wire columns.
+
+        ``row`` is built from the *batch's* schema, so a column a peer never
+        wrote is simply absent — read with ``.get()`` and supply the default.
+        """
+        del row
+        return {}
+
     def serialize(self) -> bytes:
         """Serialize to Arrow IPC bytes."""
         # Serialize type as a single-field schema
@@ -116,6 +141,7 @@ class _SpecBase:
                     "description": self.desc,
                     "type": type_bytes,
                     "default_value": default_bytes,
+                    **self._extra_row(),
                 }
             ],
             schema=self.ARROW_SCHEMA,
@@ -147,6 +173,7 @@ class _SpecBase:
             desc=cast(str, row["description"]),
             type=data_type,
             default=default,
+            **cls._extra_kwargs(row),
         )
 
 
@@ -179,6 +206,15 @@ class _DescriptorBase:
             return self
         return getattr(type(obj), self._name, None)
 
+    def extra_spec_kwargs(self) -> dict[str, Any]:
+        """Extra keyword arguments this descriptor passes to its spec factory.
+
+        The base declaration carries only ``name``/``desc``/``type``/``default``;
+        a subclass adding a field returns it here so ``_extract_specs`` stays
+        shared.
+        """
+        return {}
+
 
 def _extract_specs[D: _DescriptorBase, S: _SpecBase](
     declaring_cls: type,
@@ -240,6 +276,7 @@ def _extract_specs[D: _DescriptorBase, S: _SpecBase](
                 desc=descriptor.desc,
                 type=arrow_type,
                 default=default,
+                **descriptor.extra_spec_kwargs(),
             )
         )
 

vgi_python-0.27.0/vgi/catalog/attach_option.py

@@ -0,0 +1,157 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""AttachOption descriptor for declarative worker attach-time options.
+
+This module provides the AttachOption descriptor class for declaring options
+that workers accept at ATTACH time (delivered once via catalog_attach, distinct
+from session-level Settings resent on every call).
+
+The declaration mirrors ``vgi.catalog.setting.Setting`` — same Arrow IPC spec
+format, same Python type → Arrow mapping, same extractor shape — so both share
+the machinery in ``vgi.catalog._descriptor_spec``.
+"""
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+import pyarrow as pa
+
+from vgi.catalog._descriptor_spec import _DescriptorBase, _extract_specs, _SpecBase
+
+__all__ = [
+    "AttachOption",
+    "AttachOptionSpec",
+    "MissingAttachOptionsError",
+    "extract_attach_option_specs",
+    "validate_required_attach_options",
+]
+
+
+@dataclass(frozen=True)
+class AttachOptionSpec(_SpecBase):
+    """Extracted attach-option metadata for catalog discovery serialization.
+
+    The resolved form of an `AttachOption`. See
+    `_SpecBase` (in `vgi.catalog._descriptor_spec`) for the shared fields and
+    wire format.
+
+    Attributes:
+        required: The caller must supply this option at ``ATTACH`` time. A
+            catalog that cannot be attached without it advertises that fact at
+            discovery, so a client can say so before attempting the attach
+            rather than surfacing a failure that reads like an empty catalog.
+            Mutually exclusive with ``default`` — an option that falls back to
+            a value is by definition satisfiable without the caller.
+        ARROW_SCHEMA: The shared four columns plus ``required``.
+
+    """
+
+    required: bool = False
+
+    ARROW_SCHEMA: ClassVar[pa.Schema] = pa.schema(
+        [
+            *_SpecBase.ARROW_SCHEMA,
+            # Nullable, and appended last: a peer that predates this column
+            # reads the batch by name and simply doesn't see it.
+            pa.field("required", pa.bool_(), nullable=True),
+        ]
+    )
+
+    def __post_init__(self) -> None:
+        """Reject the contradictory ``required`` + ``default`` combination."""
+        if self.required and self.default is not None:
+            raise ValueError(
+                f"Attach option {self.name!r} is required but also declares a default "
+                f"({self.default!r}); an option with a default is always satisfiable "
+                "without the caller. Drop one."
+            )
+
+    def _extra_row(self) -> dict[str, Any]:
+        return {"required": self.required}
+
+    @classmethod
+    def _extra_kwargs(cls, row: dict[str, object]) -> dict[str, Any]:
+        # Absent column (older peer) and explicit null both mean "not required".
+        return {"required": bool(row.get("required") or False)}
+
+
+@dataclass
+class AttachOption(_DescriptorBase):
+    """Descriptor for declarative attach-option definitions using Annotated.
+
+    Use with Annotated type hints to declare options in a Worker's
+    AttachOptions inner class. The Arrow type is resolved from the base type
+    in the Annotated hint. See
+    `_DescriptorBase` (in `vgi.catalog._descriptor_spec`) for the
+    ``desc`` and ``arrow_type`` attributes.
+
+    Declare a required option by omitting the class-level assignment that would
+    otherwise supply its default::
+
+        class AttachOptions:
+            region: Annotated[str, AttachOption(desc="AWS region")] = "us-east-1"
+            api_key: Annotated[str, AttachOption(desc="API key", required=True)]
+
+    Attributes:
+        required: The caller must supply this option at ``ATTACH`` time.
+
+    """
+
+    required: bool = False
+
+    def extra_spec_kwargs(self) -> dict[str, Any]:
+        """Carry ``required`` through to the `AttachOptionSpec`."""
+        return {"required": self.required}
+
+
+class MissingAttachOptionsError(ValueError):
+    """Raised when ``catalog_attach`` omits options declared ``required``.
+
+    Carries the option names in :attr:`missing` so a caller can act on them
+    without parsing the message.
+
+    Attributes:
+        missing: Names of the required options that were not supplied.
+
+    """
+
+    missing: list[str]
+
+    def __init__(self, catalog_name: str, missing: list[str]) -> None:
+        """Build the error from the catalog name and the missing option names."""
+        self.missing = missing
+        joined = ", ".join(repr(name) for name in missing)
+        super().__init__(
+            f"Catalog {catalog_name!r} cannot be attached without the required "
+            f"option{'s' if len(missing) > 1 else ''} {joined}."
+        )
+
+
+def validate_required_attach_options(
+    catalog_name: str,
+    specs: list[AttachOptionSpec],
+    options: dict[str, Any],
+) -> None:
+    """Raise if any ``required`` spec has no corresponding entry in ``options``.
+
+    Option names are matched case-insensitively, mirroring DuckDB's handling of
+    ``ATTACH`` option keys.
+
+    Args:
+        catalog_name: Catalog being attached, for the error message.
+        specs: The attach-option specs the catalog declares.
+        options: Options the caller supplied at ``ATTACH`` time.
+
+    Raises:
+        MissingAttachOptionsError: If a required option was not supplied.
+
+    """
+    supplied = {key.lower() for key in options}
+    missing = [spec.name for spec in specs if spec.required and spec.name.lower() not in supplied]
+    if missing:
+        raise MissingAttachOptionsError(catalog_name, missing)
+
+
+def extract_attach_option_specs(options_cls: type) -> list[AttachOptionSpec]:
+    """Extract AttachOptionSpec objects from an AttachOptions class."""
+    return _extract_specs(options_cls, descriptor_type=AttachOption, spec_factory=AttachOptionSpec)