ancongui · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/.github/workflows/pr-gate.yaml b/.github/workflows/pr-gate.yaml
@@ -177,8 +177,8 @@ jobs:
           uv pip install --editable ".[dev]"
       - name: Check handwritten SDK code
         run: |
-          uv run ruff check flyquery_sdk/client.py tests examples
-          uv run ruff format --check flyquery_sdk/client.py tests examples
+          uv run ruff check flyquery_sdk/client.py flyquery_sdk/agent_read_client.py tests examples
+          uv run ruff format --check flyquery_sdk/client.py flyquery_sdk/agent_read_client.py tests examples
       - name: Test SDK imports and HTTP contract
         run: |
           uv run mypy flyquery_sdk tests

diff --git a/.github/workflows/publish-sdks.yaml b/.github/workflows/publish-sdks.yaml
@@ -185,8 +185,8 @@ jobs:
         run: |
           uv venv
           uv pip install --editable ".[dev]"
-          uv run ruff check flyquery_sdk/client.py tests examples
-          uv run ruff format --check flyquery_sdk/client.py tests examples
+          uv run ruff check flyquery_sdk/client.py flyquery_sdk/agent_read_client.py tests examples
+          uv run ruff format --check flyquery_sdk/client.py flyquery_sdk/agent_read_client.py tests examples
           uv run mypy flyquery_sdk tests
           uv run pytest -q tests
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,37 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 the project uses [CalVer](https://calver.org/) (YY.MM.PP) per the
 Firefly Framework convention (memory: `firefly_uses_calver`).
 
+## [26.10.4] - Unreleased
+
+### Fixed
+
+- Confine table, snapshot, change and schema-object reads to the requested
+  tenant and workspace, including the parent table's scope. Report a current
+  snapshot only when its table, dataset, tenant and workspace match; an
+  unresolved pointer returns unavailable metadata without changing stored data.
+
+### Added
+
+- Add the Python `AgentReadClient` for bounded GET-only dataset, table catalog,
+  exact table and schema-object reads. It uses agent routes and a fixed
+  tenant/workspace/dataset, validates returned scope and parent snapshot, and
+  refuses mixed, oversized or declared incomplete catalogs. Its default pool
+  allows four connections and two keepalive connections. Redirects, automatic
+  retries and environment proxies are disabled independently.
+- Include the existing Apache license in the Java binary and source JARs. An
+  existing NOTICE file is included when present; this source has no NOTICE file.
+
+### Qualification scope
+
+- Source-host cohorts passed 72 server controls and 70 SDK controls. These are
+  separate focused cohorts, not a complete current integration suite. The SQL
+  fixture is prepared; native PostgreSQL, RLS, ASGI and installed SDK acceptance
+  remain pending. The retained SDK environment lacks third-party dateutil stubs
+  for the broad type check; focused changed-file type checks pass.
+- REST DTOs, query execution, existing SDK clients and dependency pins are
+  unchanged. The Forge adapter and agent GET mirror for prepared query results
+  are separate pending work. This candidate has not been published.
+
 ## [26.10.3] - 2026-10-14
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -30,11 +30,15 @@ JSONL, Parquet, Avro, ORC, Arrow and Feather, plus their `.gz`,
 [![OpenAPI](https://img.shields.io/badge/api-openapi%203.1-green)](docs/api-reference.md)
 [![DuckDB](https://img.shields.io/badge/query%20engine-duckdb-yellow)](docs/architecture.md)
 [![pgvector](https://img.shields.io/badge/vector--store-pgvector-336791)](docs/architecture.md)
-[![Version](https://img.shields.io/badge/version-26.10.3-green.svg)](#)
+[![Version](https://img.shields.io/badge/version-26.10.4-green.svg)](#)
+
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
 </div>
 
+This source prepares 26.10.4. Native acceptance and publication are pending;
+26.10.3 remains the published release.
+
 ---
 
 > **In a hurry?** &nbsp;Jump to the [**Quickstart →**](QUICKSTART.md) &nbsp;·&nbsp; SDK paths: [Python](sdks/python/README.md) · [Java](sdks/java/README.md) &nbsp;·&nbsp; Wire payloads: [**Payload reference →**](docs/payload-reference.md)

diff --git a/Taskfile.yml b/Taskfile.yml
@@ -117,7 +117,7 @@ tasks:
           -g python
           -o sdks/python
           --package-name flyquery_sdk
-          --additional-properties=packageVersion=26.10.3,projectName=flyquery-sdk,library=asyncio
+          --additional-properties=packageVersion=26.10.4,projectName=flyquery-sdk,library=asyncio
           --skip-validate-spec
       - cd sdks/python && uv pip install --system --quiet . || true
 
@@ -142,5 +142,5 @@ tasks:
           --invoker-package com.firefly.flyquery
           --api-package com.firefly.flyquery.api
           --model-package com.firefly.flyquery.model
-          --additional-properties=artifactId=flyquery-sdk,groupId=com.firefly,artifactVersion=26.10.3,library=webclient,dateLibrary=java8,java8=true,useJakartaEe=true
+          --additional-properties=artifactId=flyquery-sdk,groupId=com.firefly,artifactVersion=26.10.4,library=webclient,dateLibrary=java8,java8=true,useJakartaEe=true
           --skip-validate-spec
diff --git a/docs/release.md b/docs/release.md
@@ -32,17 +32,20 @@ The tag push fans out to two workflows:
 
 ### 1. Version sync
 
-Every artifact must read the same CalVer string. The five places
-that hold a version literal:
+Every candidate artifact must read the same CalVer string. Version-bearing
+surfaces include:
 
 | File | Pattern |
 |---|---|
-| `pyproject.toml` | `version = "26.5.10"` |
-| `pyfly.yaml` | `pyfly.app.version: 26.5.10` |
-| `sdks/python/pyproject.toml` | `version = "26.5.10"` |
-| `sdks/java/pom.xml` | `<version>26.5.10</version>` |
-| `Taskfile.yml` | `packageVersion=26.5.10` + `artifactVersion=26.5.10` (two occurrences) |
-| `README.md` | `version-26.5.10-green` badge URL |
+| `pyproject.toml`, `src/flyquery/__init__.py`, `pyfly.yaml` | Server package, runtime and actuator version |
+| `uv.lock` | Editable `flyquery` package version; preserve the remaining graph |
+| `openapi.json`, `sdks/java/api/openapi.yaml` | `info.version`; preserve protocol shapes |
+| `sdks/python/pyproject.toml`, `setup.py`, SDK `__init__.py` | Python package version |
+| Python SDK `api_client.py`, `configuration.py` | Runtime user agent and diagnostic versions |
+| `sdks/java/pom.xml`, `build.gradle` | Java artifact version |
+| `Taskfile.yml` | Python `packageVersion` and Java `artifactVersion` |
+| Generated Python/Java source headers | OpenAPI document version |
+| `README.md` | Version badge |
 
 Note: `publish-sdks.yaml` *also* rewrites the SDK versions from the
 git tag at publish time, so a forgotten local bump will not produce

diff --git a/docs/sdks.md b/docs/sdks.md
@@ -24,9 +24,10 @@ that a package with the same name on PyPI is maintained by this project:
 uv add https://github.com/fireflyframework/flyquery/releases/download/v26.10.3/flyquery_sdk-26.10.3-py3-none-any.whl
 ```
 
-Keep service and client versions aligned. This release uses version `26.10.3`;
-read the release notes and API snapshot before upgrading. The repository also
-retains earlier releases and their original assets.
+Keep service and client versions aligned. The published release above is
+`26.10.3`; this source prepares `26.10.4`, whose publication and native acceptance
+are pending. Read the release notes and API snapshot before upgrading. The
+repository retains earlier releases and their original assets.
 
 ## Scope and authentication
 
@@ -43,12 +44,54 @@ token's permissions constrain the operation. Adding an agent-token header to a
 user-route helper does not change which route it calls. The
 [security model](security-model.md) explains token issuance and permissions.
 
+Table reads report a current snapshot only when it belongs to the same table,
+dataset, tenant and workspace. If the retained pointer is missing or does not
+resolve within that scope, `current_snapshot_id` and `n_columns` are `null`.
+This means the current snapshot is unavailable through this read; it does not
+repair the stored pointer or establish that no snapshot exists. A valid snapshot
+with zero columns still reports its ID and `n_columns: 0`.
+
 Lookup-or-create helpers fall back to creation only after a 404. Other errors
 propagate, and a concurrent creator can return a 409. For mutating operations,
 use the API's idempotency-key mechanism where appropriate.
 
 ## Operations
 
+### Bounded agent reads in candidate 26.10.4
+
+`flyquery_sdk.agent_read_client.AgentReadClient` provides four GET-only methods:
+`get_dataset()`, `list_tables()`, `get_table(table_id)` and
+`get_object(table_id, object_id)`. This addition is not in the published 26.10.3
+SDK. Use the qualified 26.10.4 candidate source with a compatible service until
+its release is published.
+
+The client fixes one tenant, workspace and dataset at construction. Supply an
+issued agent token with `flyquery.datasets:read` and `flyquery.schema:read` as
+needed. The methods call only `/api/v1/agent/*`; there is no user-tier credential
+fallback. Every returned record must match the configured scope. An object also
+must match its requested parent table and the snapshot observed in that parent
+read. Missing or mismatched scope refuses the whole response, including a mixed
+catalog page.
+
+HTTPS, no redirects, no retries and no environment proxies apply independently.
+The default operation deadline is 10 seconds, including both GETs for an object;
+the maximum configurable deadline is 30 seconds. Responses default to 256 KiB,
+with an upper bound of 1 MiB, and catalogs allow at most 100 items. A larger
+catalog is refused rather than silently truncated. The catalog route is a full
+list: declared `has_more: true`, a nonzero offset, or a total different from the
+item count refuses the response. Missing or null pagination metadata is accepted
+for compatibility with the full-list endpoint. The default transport pool allows
+at most four connections and two idle keepalive connections. Errors and 404 never trigger
+a write, a new query or another provider. Returned content containing this
+client's agent token is refused without reflecting it in the exception.
+
+These records are reported observations, not an atomic snapshot across GETs or
+an authorization guarantee beyond the service's actual token checks. Snapshot
+history DTOs omit some scope fields; this client does not expose that history.
+Agent GET routes for prepared query results do not exist yet, so this client
+offers no query-result, natural-language, SQL, upload, export or execution method.
+The existing `FlyqueryClient` and generated APIs keep their current contracts.
+
 | Operation | Python entry point |
 |---|---|
 | Workspace and dataset setup | `find_or_create_workspace`, `find_or_create_dataset` |

diff --git a/openapi.json b/openapi.json
@@ -6206,7 +6206,7 @@
       "url": "https://github.com/fireflyframework/flyquery/blob/main/LICENSE"
     },
     "title": "flyquery",
-    "version": "26.10.3"
+    "version": "26.10.4"
   },
   "openapi": "3.1.0",
   "paths": {

diff --git a/pyfly.yaml b/pyfly.yaml
@@ -12,7 +12,7 @@ pyfly:
   # and admin tooling identify the service correctly.
   app:
     name: flyquery
-    version: 26.10.3
+    version: 26.10.4
     description: >-
       Operational Structured-Data Intelligence (upload-driven).
       Multi-tenant ingestion + Text-to-SQL over user-uploaded structured

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "flyquery"
 # CalVer YY.MM.PP per memory `firefly_uses_calver`.
-version = "26.10.3"
+version = "26.10.4"
 description = "Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL service over user-uploaded structured files. Part of Firefly Framework."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

diff --git a/sdks/java/README.md b/sdks/java/README.md
@@ -18,7 +18,9 @@ default headers.
 
 ## Install
 
-For release 26.10.3, use the matching Maven coordinate:
+The current published release is 26.10.3. Candidate source prepares 26.10.4;
+its native acceptance and publication are pending. For the published release,
+use the matching Maven coordinate:
 
 ```xml
 <dependency>

diff --git a/sdks/java/api/openapi.yaml b/sdks/java/api/openapi.yaml
@@ -13,7 +13,7 @@ info:
     name: Apache-2.0
     url: https://github.com/fireflyframework/flyquery/blob/main/LICENSE
   title: flyquery
-  version: 26.10.3
+  version: 26.10.4
 servers:
 - description: This service
   url: /

diff --git a/sdks/java/build.gradle b/sdks/java/build.gradle
@@ -2,7 +2,7 @@ apply plugin: 'idea'
 apply plugin: 'eclipse'
 
 group = 'com.firefly'
-version = '26.10.3'
+version = '26.10.4'
 
 buildscript {
     repositories {

diff --git a/sdks/java/pom.xml b/sdks/java/pom.xml
@@ -5,7 +5,7 @@
     <artifactId>flyquery-sdk</artifactId>
     <packaging>jar</packaging>
     <name>flyquery-sdk</name>
-    <version>26.10.3</version>
+    <version>26.10.4</version>
     <url>https://github.com/fireflyframework/flyquery</url>
     <description>Java SDK for flyquery -- Operational Structured-Data Intelligence. Auto-generated from the flyquery OpenAPI 3.1 spec. Targets Java 25 + Spring Boot 3.5.9 + WebFlux.</description>
     <scm>
@@ -32,6 +32,20 @@
     </developers>
 
     <build>
+        <resources>
+            <resource>
+                <directory>${project.basedir}/src/main/resources</directory>
+            </resource>
+            <resource>
+                <directory>${project.basedir}</directory>
+                <targetPath>META-INF</targetPath>
+                <filtering>false</filtering>
+                <includes>
+                    <include>LICENSE</include>
+                    <include>NOTICE</include>
+                </includes>
+            </resource>
+        </resources>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/ApiClient.java b/sdks/java/src/main/java/com/firefly/flyquery/ApiClient.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/JavaTimeFormatter.java b/sdks/java/src/main/java/com/firefly/flyquery/JavaTimeFormatter.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/RFC3339DateFormat.java b/sdks/java/src/main/java/com/firefly/flyquery/RFC3339DateFormat.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/RFC3339InstantDeserializer.java b/sdks/java/src/main/java/com/firefly/flyquery/RFC3339InstantDeserializer.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/RFC3339JavaTimeModule.java b/sdks/java/src/main/java/com/firefly/flyquery/RFC3339JavaTimeModule.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/ServerConfiguration.java b/sdks/java/src/main/java/com/firefly/flyquery/ServerConfiguration.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/ServerVariable.java b/sdks/java/src/main/java/com/firefly/flyquery/ServerVariable.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/StringUtil.java b/sdks/java/src/main/java/com/firefly/flyquery/StringUtil.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/auth/ApiKeyAuth.java b/sdks/java/src/main/java/com/firefly/flyquery/auth/ApiKeyAuth.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

diff --git a/sdks/java/src/main/java/com/firefly/flyquery/auth/Authentication.java b/sdks/java/src/main/java/com/firefly/flyquery/auth/Authentication.java
@@ -2,7 +2,7 @@
  * flyquery
  * Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.
  *
- * The version of the OpenAPI document: 26.10.3
+ * The version of the OpenAPI document: 26.10.4
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).