vgi-python 0.37.0__tar.gz → 0.37.2__tar.gz

{vgi_python-0.37.0 → vgi_python-0.37.2}/.github/workflows/ci.yml

@@ -35,6 +35,11 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      - name: Install Bun for browser discovery regression tests
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.14"
+
       - name: Install dependencies
         run: uv sync --all-extras
 

{vgi_python-0.37.0 → vgi_python-0.37.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.37.0
+Version: 0.37.2
 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.37.0 → vgi_python-0.37.2}/pyproject.toml

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

vgi_python-0.37.2/tests/test_landing_discovery.py

@@ -0,0 +1,81 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Exercise the vendored browser client against the Python HTTP server."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import threading
+from pathlib import Path
+from wsgiref.simple_server import make_server
+
+import pyarrow as pa
+import pytest
+
+from vgi.scalar_function import ScalarFunction
+from vgi.serve import create_app
+from vgi.worker import Worker
+
+
+class _Double(ScalarFunction):
+    class Meta:
+        name = "double"
+
+    def compute(self, x: pa.Int64Array) -> pa.Int64Array:
+        return pa.compute.multiply(x, 2)
+
+
+class _LandingWorker(Worker):
+    functions = [_Double]
+
+
+@pytest.mark.skipif(shutil.which("bun") is None, reason="Bun is required to execute the shipped browser client")
+def test_served_browser_client_discovers_catalog(tmp_path: Path) -> None:
+    """A successful asset GET is insufficient: the bundle must speak the current RPC protocol."""
+    script = tmp_path / "discover.mjs"
+    script.write_text("""
+const url = process.argv[2];
+let rpc;
+try {
+  const response = await fetch(url + '/vgi-client.js');
+  if (!response.ok) throw new Error('bundle HTTP ' + response.status);
+  const path = new URL('./client.mjs', import.meta.url);
+  await Bun.write(path, await response.arrayBuffer());
+  const browser = await import(path.href);
+  rpc = browser.httpConnect(url);
+  const client = new browser.VgiClient(rpc);
+  const infos = await client.catalogsInfo();
+  if (!infos.length) throw new Error('No catalogs discovered');
+  const attached = await client.catalogAttach(infos[0].name);
+  const schemas = await client.schemas(attached.attach_opaque_data);
+  const names = [];
+  for (const schema of schemas) {
+    const functions = await client.schemaContentsFunctions(attached.attach_opaque_data, schema.path, 'SCALAR_FUNCTION');
+    names.push(...functions.map(f => f.name));
+  }
+  console.log(JSON.stringify(names));
+} catch (error) {
+  console.error(error.stack || String(error));
+  process.exitCode = 1;
+} finally {
+  rpc?.close();
+}
+""")
+    app = create_app(_LandingWorker, signing_key=b"landing-discovery-test-key")
+    with make_server("127.0.0.1", 0, app) as server:
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        try:
+            result = subprocess.run(
+                ["bun", str(script), f"http://127.0.0.1:{server.server_port}"],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            assert result.returncode == 0, result.stderr
+            assert "double" in json.loads(result.stdout)
+        finally:
+            server.shutdown()
+            thread.join(timeout=5)

{vgi_python-0.37.0 → vgi_python-0.37.2}/uv.lock

@@ -2580,7 +2580,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.37.0"
+version = "0.37.2"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

vgi_python-0.37.2/vgi/_test_fixtures/secret_cache.py

@@ -0,0 +1,237 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+"""Cacheable fixtures whose results depend on a secret.
+
+The C++ result cache keys a secret-dependent result on a fingerprint of the
+secrets its bind resolved (never their values), so a result is reused while the
+secret is unchanged and recomputed the moment it is rotated, re-scoped or
+dropped. Each fixture here reads the ``vgi_example`` secret's ``secret_string``
+and advertises cacheability, one per cache path the fingerprint has to reach:
+
+* ``secret_cache_nonce()`` — producer table function; the secret is declared in
+  ``Meta.required_secrets``. Also exposed as the ``data.secret_cache_nonce``
+  table with ``inline_bind=True``, which covers the client's inline-bind path
+  (no bind RPC; the secrets are resolved client-side for init).
+* ``secret_cached_scalar(x)`` — scalar, per-value memoized; secret declared via
+  a ``Secret()`` annotation.
+* ``secret_cached_lateral(x)`` — blended map, per-value memoized, called under
+  ``LATERAL``; the secret is requested in ``on_bind`` (the two-phase bind).
+
+Every output carries a ``nonce`` minted only when the worker really runs. It is
+random rather than a counter because a pooled worker may run several processes,
+and a per-process counter can repeat across them: equal nonces prove a cache
+HIT, different ones a MISS, on any pool size.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, cast
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi.arguments import Arg, OutputLength, Param, Returns, Secret, SecretLookupEntry
+from vgi.cache_control import CacheControl
+from vgi.invocation import BindResponse
+from vgi.metadata import FunctionExample
+from vgi.scalar_function import ScalarFunction
+from vgi.schema_utils import schema
+from vgi.table_function import (
+    BindParams,
+    ProcessParams,
+    TableFunctionGenerator,
+    bind_fixed_schema,
+    init_single_worker,
+)
+from vgi.table_in_out_function import RowTransformFunction
+
+if TYPE_CHECKING:
+    from vgi.protocol import VgiOutputCollector
+
+#: The secret type every fixture here reads. Registered by the C++ extension's
+#: test build (``CREATE SECRET ... (TYPE vgi_example, secret_string '...')``).
+SECRET_TYPE = "vgi_example"
+
+#: Long enough that TTL never lapses mid-test.
+_TTL_SECONDS = 300
+
+
+def _nonce() -> int:
+    """A value unique to this invocation, across every process in a worker pool."""
+    return int.from_bytes(os.urandom(7), "big")
+
+
+def _secret_string(secret: dict[str, Any]) -> str | None:
+    """The ``secret_string`` field of a resolved secret, or None when there is none."""
+    value = secret.get("secret_string")
+    if value is None:
+        return None
+    return str(value.as_py()) if isinstance(value, pa.Scalar) else str(value)
+
+
+# ---------------------------------------------------------------------------
+# secret_cache_nonce — producer
+# ---------------------------------------------------------------------------
+@dataclass(slots=True, frozen=True)
+class SecretCacheNonceArgs:
+    """Arguments for SecretCacheNonceFunction (none)."""
+
+
+@dataclass(kw_only=True)
+class _SecretCacheNonceState(ArrowSerializableDataclass):
+    """The one row to emit, minted on a real invocation."""
+
+    secret_string: str | None
+    nonce: int
+    done: bool = False
+
+
+@init_single_worker
+@bind_fixed_schema
+class SecretCacheNonceFunction(TableFunctionGenerator[SecretCacheNonceArgs, _SecretCacheNonceState]):
+    """One row: the secret's ``secret_string`` and a per-invocation nonce; cacheable.
+
+    ``initial_state`` runs only on a cache MISS, so the nonce is stable across
+    HITs. A rotated secret must MISS and report the new value; restoring the
+    original secret must HIT the entry it produced.
+    """
+
+    class Meta:
+        """Metadata for SecretCacheNonceFunction."""
+
+        name = "secret_cache_nonce"
+        description = "One row with a secret's value and a per-invocation nonce; cacheable per secret"
+        categories = ["generator", "cache", "secret", "testing"]
+        required_secrets = [SecretLookupEntry(secret_type=SECRET_TYPE)]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM secret_cache_nonce()",
+                description="The nonce is stable while the vgi_example secret is unchanged",
+            ),
+        ]
+
+    FunctionArguments = SecretCacheNonceArgs
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema(secret_string=pa.string(), nonce=pa.int64())
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[SecretCacheNonceArgs]) -> _SecretCacheNonceState:
+        """Read the secret and mint a nonce for this (real) invocation."""
+        secret = next(iter(params.secrets.of_type(SECRET_TYPE)), {})
+        return _SecretCacheNonceState(secret_string=_secret_string(secret), nonce=_nonce())
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[SecretCacheNonceArgs],
+        state: _SecretCacheNonceState,
+        out: OutputCollector,
+    ) -> None:
+        """Emit the single row once, advertising a cache TTL."""
+        if state.done:
+            out.finish()
+            return
+        batch = pa.RecordBatch.from_pydict(
+            {"secret_string": [state.secret_string], "nonce": [state.nonce]},
+            schema=params.output_schema,
+        )
+        cast("VgiOutputCollector", out).emit(batch, cache_control=CacheControl(ttl=_TTL_SECONDS))
+        state.done = True
+
+
+# ---------------------------------------------------------------------------
+# secret_cached_scalar — scalar, per-value
+# ---------------------------------------------------------------------------
+class SecretCachedScalarFunction(ScalarFunction):
+    """``x`` -> ``'<secret_string>|<nonce>'``, memoized per value per secret.
+
+    With no secret resolved the label is ``'|<nonce>'``.
+
+    One nonce per ``compute`` call, shared by the batch, so a served value keeps
+    the nonce of the call that produced it. ``per_value`` is a test choice, as on
+    ``cached_double_scalar``: the point is coverage of the tier, not economics.
+    """
+
+    CACHE_CONTROL = CacheControl(ttl=_TTL_SECONDS, per_value=True)
+
+    class Meta:
+        """Function metadata."""
+
+        name = "secret_cached_scalar"
+        description = "Returns '<secret_string>|<nonce>' per value; memoized per value per secret"
+        examples = [
+            FunctionExample(
+                sql="SELECT secret_cached_scalar(1)",
+                description="Stable while the vgi_example secret is unchanged",
+            ),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.Int64Array, Param(doc="Any value; the output ignores it")],
+        _length: Annotated[int, OutputLength()],
+        vgi_example: Annotated[dict[str, pa.Scalar[Any]] | None, Secret(SECRET_TYPE)] = None,
+    ) -> Annotated[pa.StringArray, Returns(pa.string())]:
+        """Label every row with the secret's value ('' when none) and this call's nonce.
+
+        The framework omits a ``Secret()`` argument when no such secret exists,
+        hence the default: a dropped secret is a state this fixture must serve.
+        """
+        label = f"{_secret_string(vgi_example or {}) or ''}|{_nonce()}"
+        return pa.array([label] * _length, type=pa.string())
+
+
+# ---------------------------------------------------------------------------
+# secret_cached_lateral — blended map, per-value, two-phase secret
+# ---------------------------------------------------------------------------
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _SecretCachedLateralArgs:
+    """One positional input column; the output ignores its value."""
+
+    x: Annotated[int, Arg(0, doc="Input column")]
+
+
+class SecretCachedLateralFunction(RowTransformFunction[_SecretCachedLateralArgs]):
+    """1->1 map emitting the secret's ``secret_string`` and a per-call nonce.
+
+    Requests the secret from ``on_bind`` — the two-phase bind, so the secret is
+    discovered at bind time rather than declared — and advertises ``per_value``
+    so a correlated ``LATERAL`` call is memoized per input value per secret.
+    """
+
+    class Meta:
+        """Function metadata."""
+
+        name = "secret_cached_lateral"
+        description = "Blended map emitting a secret's value and a per-call nonce; memoized per secret"
+        categories = ["blended", "cache", "secret", "test"]
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_SecretCachedLateralArgs]) -> BindResponse:
+        """Request the secret (two-phase) and declare the output columns."""
+        params.secrets.get(SECRET_TYPE)
+        return BindResponse(output_schema=schema(secret_string=pa.string(), nonce=pa.int64()))
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_SecretCachedLateralArgs],
+        state: None,
+        batch: pa.RecordBatch,
+        out: OutputCollector,
+    ) -> None:
+        """Emit one row per input row, all carrying this call's nonce."""
+        secret = next(iter(params.secrets.of_type(SECRET_TYPE)), {})
+        rows = batch.num_rows
+        cast("VgiOutputCollector", out).emit(
+            pa.record_batch(
+                {
+                    "secret_string": pa.array([_secret_string(secret)] * rows, type=pa.string()),
+                    "nonce": pa.array([_nonce()] * rows, type=pa.int64()),
+                }
+            ),
+            cache_control=CacheControl(ttl=_TTL_SECONDS, per_value=True),
+        )

{vgi_python-0.37.0 → vgi_python-0.37.2}/vgi/_test_fixtures/table/__init__.py

@@ -113,6 +113,7 @@ from vgi._test_fixtures.table.partition_columns import (
     OverlappingRangePartitionedFunction,
     PartitionedWithExplicitOverrideFunction,
     RegionYearPartitionedFunction,
+    TrailingPartitionSalesFunction,
 )
 from vgi._test_fixtures.table.partition_columns_broken import (
     BrokenMissingPartitionValuesFunction,
@@ -264,6 +265,7 @@ __all__ = [
     "RFF_SIMPLE_COLUMNS",
     "RFF_STRUCT_COLUMNS",
     "RegionYearPartitionedFunction",
+    "TrailingPartitionSalesFunction",
     "RepeatValueIntFunction",
     "RepeatValueStrFunction",
     "RffMultiScanFunction",

{vgi_python-0.37.0 → vgi_python-0.37.2}/vgi/_test_fixtures/table/partition_columns.py

@@ -23,6 +23,11 @@ Fixtures:
 * :class:`RegionYearPartitionedFunction` — multi-column SINGLE_VALUE.
   Each chunk has a single ``(region, year)`` tuple.
 
+* :class:`TrailingPartitionSalesFunction` — same contract as the
+  country fixture, but the partition column is declared LAST rather
+  than first, so the worker-schema and scan-local index spaces do not
+  coincide. Also exposed as a catalog table.
+
 * :class:`PartitionedWithProjectedOutColumnFunction` — declares
   partition on ``category`` but DOES NOT include ``category`` in the
   emitted batch. Uses the explicit ``partition_values=`` override on
@@ -49,7 +54,7 @@ from __future__ import annotations
 
 import struct
 from dataclasses import dataclass
-from typing import Annotated, ClassVar, cast
+from typing import Annotated, Any, ClassVar, cast
 
 import pyarrow as pa
 from vgi_rpc import ArrowSerializableDataclass
@@ -285,6 +290,126 @@ class RegionYearPartitionedFunction(TableFunctionGenerator[_RegionYearArgs, _Reg
         state.current_idx = rpp
 
 
+# =============================================================================
+# SINGLE_VALUE_PARTITIONS with the partition column NOT first
+# =============================================================================
+
+
+@dataclass(slots=True, frozen=True)
+class _TrailingPartitionArgs:
+    """Arguments for ``trailing_partition_sales``."""
+
+    rows_per_country: Annotated[int, Arg(0, doc="Rows to emit per country partition", ge=1)]
+
+
+@dataclass(kw_only=True)
+class _TrailingPartitionState(ArrowSerializableDataclass):
+    """Per-worker cursor over countries (same shape as the country fixture)."""
+
+    current_country: str | None = None
+    current_country_idx: int = -1
+    current_idx: int = 0
+
+
+@bind_fixed_schema
+@_cardinality_from_count
+class TrailingPartitionSalesFunction(TableFunctionGenerator[_TrailingPartitionArgs, _TrailingPartitionState]):
+    """``country`` is single-valued per chunk, but sits LAST in the schema.
+
+    Identical contract to :class:`CountryPartitionedSalesFunction`; the only
+    difference is where the partition column lives. That difference is the
+    point: every other partitioned fixture declares its partition column at
+    index 0, which makes two distinct index spaces accidentally agree.
+
+    ``CanUsePartitionedAggregate`` asks ``get_partition_info`` about
+    WORKER-SCHEMA indices, but the sink later asks ``get_partition_data``
+    about SCAN-LOCAL ones (positions in the scan's own ``column_ids``, after
+    projection pushdown). ``GROUP BY country`` projects just ``country`` and
+    ``sales``, so here the sink asks about scan-local 0 while the declared
+    index is 3 — and a client that compares them without mapping raises
+    "sink requested partition column 0 that is not in the declared partition
+    set", which is fatal. With the partition column at index 0 both spaces
+    say 0 and the bug is invisible.
+
+    Also registered as a catalog TABLE (``example.data.trailing_partition_sales``)
+    because the two paths install their scan functions separately: a client can
+    wire ``get_partition_info`` for direct function calls and miss it for
+    catalog tables, in which case the planner silently never picks
+    ``PARTITIONED_AGGREGATE`` for a table however it is declared.
+    """
+
+    FIXED_SCHEMA: ClassVar[pa.Schema] = pa.schema(
+        cast(
+            "list[pa.Field[Any]]",
+            [
+                pa.field("seq", pa.int64()),
+                pa.field("label", pa.string()),
+                pa.field("sales", pa.int64()),
+                partition_field("country", pa.string()),
+            ],
+        )
+    )
+
+    class Meta:
+        name = "trailing_partition_sales"
+        projection_pushdown = True
+        description = (
+            "Per-country sales rows, one Arrow batch per country, with the "
+            "SINGLE_VALUE partition column declared LAST in the schema "
+            "instead of first."
+        )
+        categories = ["generator", "partitioning"]
+        partition_kind = PartitionKind.SINGLE_VALUE_PARTITIONS
+        examples = [
+            FunctionExample(
+                sql="SELECT country, SUM(sales) FROM trailing_partition_sales(100) GROUP BY country",
+                description="Partitioned aggregate over a non-leading partition column",
+            ),
+        ]
+
+    @classmethod
+    def on_init(cls, params: InitParams[_TrailingPartitionArgs]) -> GlobalInitResponse:
+        items = [struct.pack(_QUEUE_ITEM_FMT, i) for i in range(len(_COUNTRIES))]
+        params.storage.queue_push(items)
+        return GlobalInitResponse()
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_TrailingPartitionArgs]) -> _TrailingPartitionState:
+        return _TrailingPartitionState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_TrailingPartitionArgs],
+        state: _TrailingPartitionState,
+        out: OutputCollector,
+    ) -> None:
+        if state.current_country is None or state.current_idx >= params.args.rows_per_country:
+            item = params.storage.queue_pop()
+            if item is None:
+                out.finish()
+                return
+            (state.current_country_idx,) = struct.unpack(_QUEUE_ITEM_FMT, item)
+            state.current_country = _COUNTRIES[state.current_country_idx]
+            state.current_idx = 0
+
+        rpc = params.args.rows_per_country
+        # Same deterministic sales values as country_partitioned_sales, so a
+        # test can assert the two agree column-for-column despite the layout.
+        base = state.current_country_idx * 1_000_000
+        batch = pa.RecordBatch.from_pydict(
+            {
+                "seq": list(range(rpc)),
+                "label": [f"{state.current_country}-{i}" for i in range(rpc)],
+                "sales": [base + i for i in range(rpc)],
+                "country": [state.current_country] * rpc,
+            },
+            schema=cls.FIXED_SCHEMA,
+        )
+        out.emit(batch)
+        state.current_idx = rpc
+
+
 # =============================================================================
 # Projected-out partition column — exercises explicit override path
 # =============================================================================

{vgi_python-0.37.0 → vgi_python-0.37.2}/vgi/_test_fixtures/worker.py

@@ -130,6 +130,11 @@ from vgi._test_fixtures.scalar import (
     UpperCaseFunction,
     WhoAmIFunction,
 )
+from vgi._test_fixtures.secret_cache import (
+    SecretCachedLateralFunction,
+    SecretCachedScalarFunction,
+    SecretCacheNonceFunction,
+)
 from vgi._test_fixtures.table import (
     _VERSIONED_CONSTRAINTS_SCHEMAS,
     _VERSIONED_SCHEMAS,
@@ -243,6 +248,7 @@ from vgi._test_fixtures.table import (
     SplitZeroFunction,
     StructSettingsFunction,
     TenThousandFunction,
+    TrailingPartitionSalesFunction,
     TxCachedValueFunction,
     TypedProbeFunction,
     UnionVarargsFunction,
@@ -450,6 +456,9 @@ _EXAMPLE_CATALOG = Catalog(
                 BufferInputFunction,
                 FilterBySettingFunction,
                 SecretInOutFunction,
+                # Secret-dependent + per_value: cached per secret fingerprint
+                # (see vgi/_test_fixtures/secret_cache.py).
+                SecretCachedLateralFunction,
                 RepeatInputsFunction,
                 SlowCancellableInOutFunction,
                 MultiBatchFinishFunction,
@@ -528,6 +537,7 @@ _EXAMPLE_CATALOG = Catalog(
                 OverlappingRangePartitionedFunction,
                 PartitionedWithExplicitOverrideFunction,
                 RegionYearPartitionedFunction,
+                TrailingPartitionSalesFunction,
                 # Deliberately-broken batch_index fixtures (see
                 # vgi/_test_fixtures/table/batch_index_broken.py). Registered
                 # so SQL integration tests in batch_index_contract.test can
@@ -571,6 +581,7 @@ _EXAMPLE_CATALOG = Catalog(
                 SecretDemoFunction,
                 MultiSecretDemoFunction,
                 ScopedSecretDemoFunction,
+                SecretCacheNonceFunction,
                 ExpressionFilterTestFunction,
                 SequenceFunction,
                 # Split-capable scans (plan() -> named units -> per-split init).
@@ -650,6 +661,7 @@ _EXAMPLE_CATALOG = Catalog(
                 RandomBytesFunction,
                 RandomIntFunction,
                 ReturnSecretValueFunction,
+                SecretCachedScalarFunction,
                 # Schema-disambiguation probes: each name is also registered in
                 # the `data` schema below with a different body. The scalar
                 # covers the scalar bind path; the table-in-out and buffered
@@ -883,6 +895,20 @@ _EXAMPLE_CATALOG = Catalog(
                     columns=schema(n=pa.int64()),
                     comment="123456 integers; stats served by the sequence function, not the table",
                 ),
+                # PartitionColumns as a CATALOG TABLE. A table's scan function is
+                # built through a different path than a direct function call, so a
+                # client can support partitioned aggregates for one and silently
+                # not the other; only a table exercises the catalog path. Paired
+                # with a partition column declared last — see the fixture docstring.
+                Table(
+                    name="trailing_partition_sales",
+                    function=TrailingPartitionSalesFunction,
+                    arguments=Arguments(positional=(pa.scalar(100),)),
+                    comment=(
+                        "Per-country sales, SINGLE_VALUE partition column declared last; "
+                        "GROUP BY country must plan as PARTITIONED_AGGREGATE"
+                    ),
+                ),
                 # Result-cache fixtures, exposed as function-backed tables so the
                 # catalog-attached path (SELECT ... FROM ex.data.<name>) exercises
                 # the C++ result cache. See vgi/_test_fixtures/table/cache.py.
@@ -896,6 +922,15 @@ _EXAMPLE_CATALOG = Catalog(
                     function=CacheNonceFunction,
                     comment="One-row cacheable result whose value changes per real invocation",
                 ),
+                # A secret-dependent cacheable table, pre-bound (inline_bind) so a
+                # scan takes the client's no-RPC bind path, where the secrets the
+                # cache keys on are resolved client-side. See secret_cache.py.
+                Table(
+                    name="secret_cache_nonce",
+                    function=SecretCacheNonceFunction,
+                    inline_bind=True,
+                    comment="One-row cacheable result keyed on the vgi_example secret",
+                ),
                 Table(
                     name="cache_multicol",
                     function=CacheMultiColFunction,