Support TablePathPrefix and namespaced tables

.agents/architecture.md

@@ -28,6 +28,8 @@ The language packages in `internal/codegen` produce files from that resolved mod
 
 ## Compilation boundary
 
+Static absolute TablePathPrefix resolution belongs to the shared analyzer. A named query or schema source has one validated prefix; different named queries and schema files do not inherit it. The catalog stores resolved physical paths while relation aliases retain their authored SQL identity. Resolved table-reference token bindings travel with executable syntax for generators such as jOOQ, so table mapping does not reimplement path semantics. Source pragmas and authored table references remain in executable YQL; wildcard reanalysis refreshes the token bindings. The compiler rejects conflicting or late prefixes instead of modeling statement-local prefix changes.
+
 `analyzer.Analyze(schema, queries)` is the default compilation entry point; `AnalyzeWithOptions(schema, queries, Options)` accepts an explicit function contract with a fixed arity. The CLI invokes `AnalyzeWithOptions` for offline analysis or `AnalyzeWithDatabase` for connected analysis once per `sql` configuration entry, then gives the shared resolved result to every selected generator. `compile` stops after analysis. Planned macro processing belongs inside this boundary; see [the roadmap](roadmap.md). A separate compiler package is unnecessary while the analyzer owns these stages.
 
 `model.Type` owns structural equality and YQL type formatting. The analyzer, built-in function resolver and Python model reuse checks share those operations. Go's native and database/sql generators bind root Struct parameters and list-of-Struct batches through generated named types; both bind scalar List parameters, while nested Struct/List fields remain unsupported. SDK-specific type mapping stays in each generator.

.agents/development.md

@@ -39,7 +39,7 @@ go tool cover -html=coverage.out -o coverage.html
 
 `make coverage` runs the root Go module's tests without caching and writes `coverage.out` in atomic mode. `-coverpkg=./...` includes calls across package boundaries, so CLI and golden tests contribute to analyzer and generator coverage. The final `total` from `go tool cover` is the combined statement coverage; the per-test-package percentages are not independent package coverage figures. The denominator contains only sqlc-ydb runtime code, including the CLI entry point even when untested. Unit and end-to-end tests run and contribute coverage of that code, but their own source is not measured. Examples, the `internal/endtoend` harness, `*_test.go` files, golden outputs, `.github` tooling and the external ANTLR parser dependency are outside this scope. Go already excludes test source and the separate examples module from the profile; `codecov.yml` also explicitly excludes the repository's non-runtime paths. This local profile excludes live YDB tests unless their environment variables are set, and excludes optional SDK checks unless explicitly enabled.
 
-CI saves the offline profile together with `coverage-sdk.out` and `coverage-typescript.out` from compiler/SDK-backed generator tests as the `generator-coverage` artifact and uploads them to Codecov with the `unit` flag on pushes to `main` and pull requests. The `ydb-acceptance` job also instruments the semantic, integer pagination, callback, Go generator and Python generator live tests and uploads their five profiles with the `integration` flag, saving them as the `generator-integration-coverage` artifact. Codecov merges these profiles; generated application runtime coverage is not measured. SDK checks contribute coverage of the generator code they execute. The PR comment updates as reports arrive, so the first report can show only offline coverage. [codecov.yml](../codecov.yml) compares project coverage with the base commit (allowing a one percentage point drop) and requires 80% patch coverage. It enables one updated PR comment with the coverage difference and impacted files, including on the first PR without a base report. A successful `main` upload establishes the comparison baseline and populates the README badge.
+CI saves the offline profile together with `coverage-sdk.out` and `coverage-typescript.out` from compiler/SDK-backed generator tests as the `generator-coverage` artifact and uploads them to Codecov with the `unit` flag on pushes to `main` and pull requests. The `ydb-acceptance` job also instruments the semantic, integer pagination, table-path-prefix, callback, Go generator and Python generator live tests and uploads their six profiles with the `integration` flag, saving them as the `generator-integration-coverage` artifact. Codecov merges these profiles; generated application runtime coverage is not measured. SDK checks contribute coverage of the generator code they execute. The PR comment updates as reports arrive, so the first report can show only offline coverage. [codecov.yml](../codecov.yml) compares project coverage with the base commit (allowing a one percentage point drop) and requires 80% patch coverage. It enables one updated PR comment with the coverage difference and impacted files, including on the first PR without a base report. A successful `main` upload establishes the comparison baseline and populates the README badge.
 
 Repository administrators must enable `ydb-platform/sqlc-ydb` in Codecov and grant the [Codecov GitHub App](https://github.com/apps/codecov) access so it can post PR comments. Set the repository Actions secret `CODECOV_TOKEN` to the Codecov upload token, as in ydb-go-sdk. Alternatively, the organization can allow tokenless public uploads with **Global Upload Token → Not required** in Codecov; the action accepts an empty secret in that mode. Public fork PR uploads do not need access to the secret. See [Codecov token authentication](https://docs.codecov.com/docs/codecov-tokens) and [PR comments](https://docs.codecov.com/docs/pull-request-comments). An upload failure fails the CI job rather than silently leaving stale coverage.
 
@@ -81,7 +81,7 @@ Review updated files alongside the SQL, configuration and implementation changes
 
 ## Generated runtime checks
 
-The [examples](../examples/README.md) share one Go module in `examples/`; generated code lives under each example's `go/` directory. Cross-example Go tests and database helpers live in `tests/examples/go`, with a scoped `go.work` connecting the example module without local replace directives. C# framework, TypeScript, Rust and PHP examples share dependencies and test harnesses in `tests/examples/csharp`, `tests/examples/typescript`, `tests/examples/rust` and `tests/examples/php`. TypeScript dependencies resolve from `tests/examples/typescript/package.json`; the shared jOOQ build lives in `tests/examples/java/jooq`. The authors example hosts the Python, Java native/JDBC, Kotlin and ADO.NET builds; its C++ CMake project compiles all five example families. Schema, queries and generator configuration are shared in each example root. The additional `records` and `counters` recipes generate both Go adapters and run in the same sequential Go acceptance step. The counters live tests also invoke `bin/sqlc-ydb` against the opt-in schema-check/discovery configurations, compile and execute the discovered client in a temporary directory, and verify schema drift and the offline override; run `make generate` first to build the CLI. `make generate` and `make check-examples` cover every offline `examples/*/sqlc.yaml` configuration; the release smoke test also compiles, generates and diffs all of them. `make check-examples` fails if generation changes tracked files or creates untracked files under `examples`, so a new generated source cannot be omitted from a commit unnoticed.
+The [examples](../examples/README.md) share one Go module in `examples/`; generated code lives under each example's `go/` directory. Cross-example Go tests and database helpers live in `tests/examples/go`, with a scoped `go.work` connecting the example module without local replace directives. C# framework, TypeScript, Rust and PHP examples share dependencies and test harnesses in `tests/examples/csharp`, `tests/examples/typescript`, `tests/examples/rust` and `tests/examples/php`. TypeScript dependencies resolve from `tests/examples/typescript/package.json`; the shared jOOQ build lives in `tests/examples/java/jooq`. The authors example hosts the Python, Java native/JDBC, Kotlin and ADO.NET builds; its C++ CMake project compiles the five upstream-derived families and namespaces. The shared Java/Kotlin and .NET projects also compile the namespaces profiles; TypeScript, Rust and PHP include their namespaces modules in the existing build/load checks. Schema, queries and generator configuration are shared in each example root. The additional `records` and `counters` recipes generate both Go adapters and run in the same sequential Go acceptance step. The counters live tests also invoke `bin/sqlc-ydb` against the opt-in schema-check/discovery configurations, compile and execute the discovered client in a temporary directory, and verify schema drift and the offline override; run `make generate` first to build the CLI. `make generate` and `make check-examples` cover every offline `examples/*/sqlc.yaml` configuration; the release smoke test also compiles, generates and diffs all of them. `make check-examples` fails if generation changes tracked files or creates untracked files under `examples`, so a new generated source cannot be omitted from a commit unnoticed.
 
 Check all generated example families against their pinned runtime dependencies:
 
@@ -113,6 +113,8 @@ YDB_CONNECTION_STRING=grpc://localhost:2136/local \
 
 `TestLiveYDBIntegerLimits` generates both Go adapters and verifies integer aliases, every supported required/optional pagination width, signed and NULL argument behavior, comma-form LIMIT ordering, and boundary values. It separately checks that YDB rejects unsupported count types and overflowing literals. Run `go test -p 1 -count=1 -timeout=240s ./internal/endtoend -run '^TestLiveYDBIntegerLimits$' -v` with the same disposable DSN. Stable and nightly acceptance run this suite in a separate sequential step with its own 240-second Go test budget and five-minute step timeout; stable CI includes `coverage-integer-limits-live.out` in the integration coverage artifact and Codecov upload. `TestAuthorsPagination` additionally executes the checked-in authors pagination example through both Go adapters.
 
+`TestLiveYDBTablePathPrefix` checks uniquely owned namespaced tables, offline/discovered/local-schema agreement, drift, indexed reads, writes and absolute-path bypass through generated Go native and database/sql clients. Set `SQLC_YDB_TEST_MAVEN=mvn` to include jOOQ runtime checks with the pinned SDK dependencies. Run `go test -p 1 -count=1 -timeout=240s ./internal/endtoend -run '^TestLiveYDBTablePathPrefix$' -v` with the disposable DSN. Stable and nightly CI give this suite its own sequential 240-second Go test budget and five-minute step timeout; stable CI enables the Maven checks and uploads `coverage-table-path-prefix-live.out` as its sixth integration coverage profile. The checked-in namespaces example additionally supplies all generated runtime profiles.
+
 For a manually prepared development schema, see the [local-ydb initialization recipe](../docs/database-analysis.md#prepare-a-disposable-local-database). Automated acceptance uses uniquely named objects and cleans them up instead of sharing a fixed application schema.
 
 The semantic metadata suite compares analyzer result types, nullability and column order directly with YDB, independently of generated code. Run it sequentially with the runtime suites after installing the pinned Python dependencies:

.agents/roadmap.md

@@ -4,11 +4,10 @@ Current behavior is in [compatibility](../docs/compatibility.md), stage ownershi
 
 ## Query compatibility priorities
 
-The following issues track planned work; their examples and acceptance criteria define the scope. Name-mapped INSERT/UPSERT SELECT, trailing Struct commas, verified integer aliases and compatible LIMIT/OFFSET types, and secondary-index metadata with VIEW selection are implemented; their original scope is in [#25](https://github.com/ydb-platform/sqlc-ydb/issues/25), [#26](https://github.com/ydb-platform/sqlc-ydb/issues/26), [#27](https://github.com/ydb-platform/sqlc-ydb/issues/27), and [#28](https://github.com/ydb-platform/sqlc-ydb/issues/28). The [compatibility contract](../docs/compatibility.md#current-analyzer-coverage) records their boundaries. Subsequent changes should remain separate, reviewable PRs.
+The following issues track planned work; their examples and acceptance criteria define the scope. Name-mapped INSERT/UPSERT SELECT, trailing Struct commas, verified integer aliases and compatible LIMIT/OFFSET types, secondary-index metadata with VIEW selection, and static absolute TablePathPrefix resolution are implemented; their original scope is in [#25](https://github.com/ydb-platform/sqlc-ydb/issues/25), [#26](https://github.com/ydb-platform/sqlc-ydb/issues/26), [#27](https://github.com/ydb-platform/sqlc-ydb/issues/27), [#28](https://github.com/ydb-platform/sqlc-ydb/issues/28), and [#29](https://github.com/ydb-platform/sqlc-ydb/issues/29). The [compatibility contract](../docs/compatibility.md#current-analyzer-coverage) records their boundaries. Subsequent changes should remain separate, reviewable PRs.
 
 | Order | Planned capability | Tracking |
 | --- | --- | --- |
-| 2 | TablePathPrefix and consistent table resolution | [#29](https://github.com/ydb-platform/sqlc-ydb/issues/29) |
 | 2 | ALTER COLUMN DROP NOT NULL | [#30](https://github.com/ydb-platform/sqlc-ydb/issues/30) |
 | 3 | Shared Boolean expressions, conditional aggregates and scalar conversions | [#31](https://github.com/ydb-platform/sqlc-ydb/issues/31) |
 | 4 | Scoped tabular expressions, IN subqueries and collection aggregation | [#32](https://github.com/ydb-platform/sqlc-ydb/issues/32) |

.agents/sdk-evidence.md

@@ -4,6 +4,12 @@ This maintainer reference records API snapshots and non-obvious SDK behavior use
 
 Language-level generated API, value mappings and ownership contracts remain in the public guides under `docs/`. C++ build details are in [C++ development](cpp-development.md), and additional C# source evidence is in [C# SDK evidence](csharp-sdk-evidence.md).
 
+## TablePathPrefix execution
+
+On 2026-09-23, the Java generator's pinned SDK tests and `TestLiveYDBTablePathPrefix` validated jOOQ 3.21.0, YDB dialect 2.0.0 and JDBC 2.4.1 with static absolute prefixes. Non-declared queries retain the typed DSL statement as a QueryPart in `dsl.query`/`dsl.resultQuery`, preceded by the exact pragma source; result queries use typed `Field` coercions. This preserves typed binds and the same prefix context as the existing declared JDBC path, including relative RenderMapping outputs. Absolute mapped paths bypass the pragma. Dropping the source pragma would change the root used by relative table mappings. The static wrapper keeps both execution paths consistent without generated runtime path heuristics.
+
+The live suite used `ydbplatform/local-ydb:26.3.1.16` (`sha256:32687d3bc4b7a3e4200e2142800e5fc2e91d48ba46160ea094e9f1ce56794c12`) and also exercised generated native Go/database/sql clients using SDK v3.151.1. It verified actual returned values and writes, including namespace isolation, VIEW, cross-namespace SELECT-backed writes and typed Uint64 boundaries. Compiler/mock checks remain distinct from these server execution checks.
+
 ## Go error stack traces
 
 Checked against the pinned Go SDK 3.151.1 on 2026-09-13: [`pkg/xerrors.WithStackTrace`](https://github.com/ydb-platform/ydb-go-sdk/blob/v3.151.1/pkg/xerrors/stacktrace.go) delegates to the [internal wrapper](https://github.com/ydb-platform/ydb-go-sdk/blob/v3.151.1/internal/xerrors/stacktrace.go), which returns `nil` for `nil`, records the caller location and exposes the original error through `Unwrap`. Generated native methods and Decimal validation helpers wrap returned errors; `database/sql` retains its error behavior. `TestGeneratedYDBErrorStackTraces` compiles separate `:one`, `:many` and `:exec` files against this SDK and executes failure paths to verify generated locations, `errors.Is`/`errors.As`, Decimal validation and successful `Exec` returning `nil`.