mainsequence-metatable 0.1.6.dev7__tar.gz → 0.1.7.dev9__tar.gz

{mainsequence_metatable-0.1.6.dev7/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.7.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.6.dev7
+Version: 0.1.7.dev9
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/api/0001-unified-api-storage-and-local-sqlite.md

@@ -14,6 +14,13 @@ Status: Accepted.
 Owner: MetaTables API. Scope: runtime binding, storage and bootstrap, with shared
 client/API execution constraints.
 
+Clarified 2026-10-01 (MetaTables #9): applications automatically obtain the
+selected runtime DataSource from this API after Environment-scoped deployment
+discovery. UID and SQL dialect belong to the same fresh descriptor. Applications
+need no source configuration for the default path; an uninitialized API reports
+a configuration error. ADR 0010 permits optional bounded reads from registered
+external sources without changing this runtime's catalog or write destination.
+
 Client endpoint selection is governed by
 [client ADR 0003](../client/0003-api-endpoint-resolution.md). Its endpoint cache
 does not cache this API's runtime context or select its runtime mode or DataSource.

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/api/0007-database-enforced-table-access.md

@@ -17,6 +17,14 @@ and repair; the Python client and examples use DataSource-only SQL requests.
 
 Owner: MetaTables API.
 
+Clarified 2026-10-01 (MetaTables #9): automatic compiler source resolution must
+preserve the selected runtime's restricted SQL identity. An explicit different
+source UID is not SQL admission, even with `operation=select`; return a specific
+source-policy conflict rather than claiming the database is unavailable. ADR
+0010's registered-table reader remains the supported external read path. General
+external SQL requires a separate permission design that preserves caller grants
+without using the source's shared account as an unrestricted SQL identity.
+
 Related decisions: [API ADR 0001: Unified API storage](0001-unified-api-storage-and-local-sqlite.md),
 [API ADR 0002: Administration and table ownership](0002-application-administration-and-table-ownership.md)
 and [API ADR 0008: Database backend contract](0008-mysql-mssql-table-workflows.md).

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/api/0008-mysql-mssql-table-workflows.md

@@ -11,6 +11,13 @@ Date: 2026-09-29
 
 Status: Accepted.
 
+Clarified 2026-10-01 (MetaTables #9): the compiler obtains the runtime DataSource
+UID, dialect and parameter style together, with no caller configuration. The
+default path covers PostgreSQL/TimescaleDB, SQLite, MySQL and MSSQL. An explicit
+different source must not inherit the runtime source's dialect. Offline explicit
+UID/dialect compilation remains supported but does not relax API execution
+binding. Optional external bounded reads retain ADR 0010's source selection.
+
 Amended 2026-09-29: one selected execution DataSource, explicit workflow and
 transaction ownership, first-bootstrap recovery, and a Compose database test suite.
 

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/api/0010-import-external-tables-and-views.md

@@ -9,6 +9,15 @@ client and Vite import/Rows views. Verification and boundaries are recorded belo
 
 Owner: MetaTables API. The Python client and Vite application consume its contract.
 
+Clarified 2026-10-01 (MetaTables #9): default compiler calls discover the API's
+runtime DataSource automatically. Selecting an imported MetaTable for an optional
+external read uses that table's registered source through `read_rows()` or
+`iter_rows()` and the same API. It does not mutate the default, replace Environment
+selection or authorize external writes. Arbitrary external SQL and joins remain
+outside this implementation; SQL selection of another source reports a specific
+policy conflict. Client guides must show the working external read workflow and
+must not present `data_source_uid` alone as enabling arbitrary external SQL.
+
 Related decisions: [ADR 0002: Administration and ownership](0002-application-administration-and-table-ownership.md),
 [ADR 0007: Database-enforced table access](0007-database-enforced-table-access.md),
 [ADR 0008: Database backend contract](0008-mysql-mssql-table-workflows.md), and

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/client/0003-api-endpoint-resolution.md

@@ -9,8 +9,16 @@ Owner: MetaTables Python client, including the CLI.
 
 Related decision: [API ADR 0001: One API execution path with SQLite for local development](../api/0001-unified-api-storage-and-local-sqlite.md).
 
-The client implements this decision using the SDK's exact-name release filter
-and existing release-access operation.
+The client implements this decision using the SDK's Environment context,
+exact-name release filter, owning-branch metadata and release-access operation.
+
+Amended 2026-10-01 ([MetaTables #11](https://github.com/mainsequence-projects/MetaTables/issues/11)):
+hosted discovery must select the caller's resolved Organization Environment.
+The previous visibility-only lookup and hosted URL workaround violated that
+contract. `METATABLES_API_URL` is reserved for loopback development APIs. Identical
+deployment names in different Environments are expected and must work without
+user configuration. Connection and configuration documentation must describe
+this distinction and the Environment-specific failure cases.
 
 Amended 2026-09-29: obtain the target name from the MetaTables automatic
 deployment. Remove the proposed conventional name and manually configured
@@ -25,7 +33,7 @@ with the client and use the SDK for the subsequent release lookup and access.
 Previously, the client constructed resource URLs from a model's `ROOT_URL` or
 `METATABLES_API_URL`, and failed when neither was configured. The CLI separately
 required the environment variable. This decision replaces that duplicated
-selection with automatic discovery and an explicit URL override.
+selection with automatic hosted discovery and a local development URL override.
 
 A client connecting to a hosted MetaTables deployment obtains the correct name
 from the automatic deployment's authoritative metadata. Users should not copy
@@ -37,8 +45,11 @@ local API through an environment variable.
 The SDK supplies generic platform release operations. Ordinary release collection
 queries currently infer the consuming repository's branch, whereas the MetaTables
 deployment can belong to another repository. A name filter alone does not solve
-that distinction. Release names are also not currently guaranteed to be unique;
-text search or selecting the first result cannot establish the intended target.
+that distinction. The caller's Environment, obtained from the SDK's resolved
+repository context or authenticated runtime credential, selects the intended
+deployment across repositories. Release names can repeat across Environments;
+visibility alone, text search or selecting the first result cannot establish the
+intended target. Selecting the wrong API also selects the wrong runtime DataSource.
 
 Endpoint selection is a client transport concern. The API's runtime mode,
 bootstrap and DataSource binding remain governed by API ADR 0001. Connecting to
@@ -47,7 +58,7 @@ runtime mode through Settings.
 
 ## Decision
 
-### 1. One resolver with an explicit URL override
+### 1. One resolver with a local development URL override
 
 All Python resource models, runtime-context requests, readers, updaters and CLI
 commands use one client endpoint resolver. Migration commands use the same
@@ -57,19 +68,21 @@ The resolver uses the following precedence:
 
 | Configuration | Behavior |
 | --- | --- |
-| Nonempty `METATABLES_API_URL` | Use that explicit base URL and skip all deployment discovery. |
-| URL unset or empty | Obtain the MetaTables API's name from its automatic-deployment metadata, then resolve that named deployment through the SDK. |
+| Nonempty `METATABLES_API_URL` | Require a loopback HTTP(S) development URL, use it and skip platform Environment/deployment discovery. |
+| URL unset or empty | Obtain the MetaTables API's name from its automatic-deployment metadata and resolve that deployment in the caller's SDK-owned Environment. |
 
 The deployment name is derived data, owned by the automatic deployment. There is
 no hardcoded default such as `metatables`, and no manually maintained
 `METATABLES_API_DEPLOYMENT_NAME` setting. The client must consume the actual name
 produced by that deployment, so changing it does not require editing consuming
-projects. `METATABLES_API_URL` remains the explicit client override; there is no
+projects. `METATABLES_API_URL` remains the local development override; there is no
 additional automatic/manual mode variable.
 
-An explicit URL may target a local or hosted API. Preserve any deployment path
-prefix when joining resource routes. A nonempty invalid URL produces a
-configuration error; it must not fall through to automatic discovery. Model-level
+An explicit URL must target `localhost` or a loopback IP address. Hosted URLs
+are rejected with an instruction to unset the variable and use Environment
+discovery. Preserve any local path prefix when joining resource routes. A nonempty
+invalid URL produces a configuration error; it must not fall through to automatic
+discovery. Model-level
 `ROOT_URL` assignments must no longer independently override the environment or
 split different resources across different API targets.
 
@@ -101,25 +114,30 @@ for exact-name lookup and stable endpoint retrieval. It does not call platform
 routes directly, inspect platform persistence models, derive hostnames from UIDs,
 or maintain a second platform client.
 
-Discovery must operate in the platform's permitted release scope without
-implicitly restricting the result to the consuming application's repository
-branch. The SDK owns the generic lookup capability and its platform contract.
-This decision does not relax branch or Environment requirements on ordinary SDK
-resource operations, and does not make local development require a registered
-branch.
-
-The client calls `ResourceRelease.filter_admin(name=..., release_kind="fastapi")`
-using the existing explicit SDK collection interface, which does not infer the
-consumer's branch. This is an exact bounded query, not enumeration of all releases.
-Backend visibility and runtime scope still apply. The client requires one match
-and calls that release's `resolve_runtime_access()` for the backend-issued URL.
-No SDK context reset, branch override or new platform metadata endpoint is needed.
-
-Exactly one matching release is required. Missing or ambiguous target metadata,
-no matching release, multiple matches, the wrong release kind, or a missing
-usable endpoint produces a specific resolution error.
-Ambiguous deployments must be given distinct names or use the explicit URL
-override. There is no first-result selection or fallback to another release.
+Resolve the caller's Environment with the public SDK
+`resolve_organization_environment_uid()` helper. The SDK owns Git registration,
+authenticated runtime context and authorization. A developer's signed-in process
+connecting to a hosted API follows the same Environment selection rule. Local
+development URL selection does not require a registered branch or Environment.
+
+The installed SDK does not expose an Environment filter on `ResourceRelease`.
+Use `ResourceRelease.filter_admin(name=..., release_kind="fastapi")` only to
+obtain exact-name candidates, without restricting them to the consuming
+application's repository branch. Each candidate supplies its owning
+`code_repository_branch_uid`. Read those public `CodeRepositoryBranch` records
+through the SDK using `filter(uid__in=...)`, in batches of at most 100 unique UIDs,
+and compare their `organization_environment_uid` with the caller's Environment.
+The client must verify ownership before requesting runtime access, even if only
+one release is visible. Missing or inconsistent ownership metadata fails closed.
+An owning branch with no Environment cannot match an Environment-bound caller.
+
+Require exactly one match **within that Environment**, then call the selected
+release's `resolve_runtime_access()` for its backend-issued URL. The same name in
+other Environments is neither an error nor a fallback. Zero matches report a
+missing deployment in the selected Environment; multiple matches report duplicate
+deployments within it. Neither error recommends a URL override or globally unique
+deployment names. No first-result selection, SDK context reset, consumer branch
+override, direct platform request or new platform endpoint is needed.
 
 Existing SDK release-access operations may report a starting or unavailable
 runtime. Such a result is not a successful endpoint resolution. Respect the
@@ -131,18 +149,21 @@ mechanism, credential type, account-binding policy or Organization policy.
 
 Resolve lazily on the first operation that needs an API address. Cache a
 successful result in process memory for the selected platform endpoint and
-automatic-deployment target, including its derived name. The discovery sequence
-obtains target metadata, resolves the exact name and retrieves the endpoint;
-subsequent operations reuse its result without repeating any of those steps.
+resolved Organization Environment. The entry holds the release UID and derived
+deployment name. The discovery sequence obtains target metadata, verifies the
+candidate owners' Environments and retrieves the endpoint; subsequent operations
+reuse its result without repeating those platform lookups. Read the SDK-owned
+process context when selecting the cache key; do not maintain a separate
+Environment cache or reuse an endpoint after that context changes.
 
 Concurrent first callers share one resolution attempt. Do not cache failed,
 ambiguous, starting or unavailable results as successful entries. Later calls
 can retry after a failed attempt. Forked or new processes start with their own
 cache; no discovered address is persisted to disk.
 
-The explicit URL is checked before consulting the discovery cache, so setting
+The local URL is checked before consulting the discovery cache, so setting
 `METATABLES_API_URL` takes effect even after automatic resolution. Configuration
-changes invalidate the previous target's cache; an explicit client reset or
+and Environment changes invalidate the previous target's cache; an explicit client reset or
 process restart also permits a fresh lookup, including reacquiring the name from
 the packaged workflow. Editable installs observe workflow changes on that fresh
 lookup; installed wheels use their immutable workflow snapshot. Stable configuration
@@ -155,6 +176,25 @@ silently select another deployment or replay a mutation against a different API.
 
 ### 4. Keep endpoint discovery separate from runtime state
 
+Amended 2026-10-01 ([MetaTables #9](https://github.com/mainsequence-projects/MetaTables/issues/9)):
+the compiler's default is Environment → API deployment → fresh `/runtime-context/`
+→ selected DataSource UID and SQL dialect. Consuming applications configure none
+of these values. Runtime bootstrap and Settings remain operator responsibilities.
+The client preserves the runtime descriptor's public `data_source` dictionary
+and uses a shared validated UID accessor. Missing, unavailable or malformed source
+metadata raises `DataSourceResolutionError`, including when the compiler is given
+an isolated runtime descriptor. UID, dialect and parameter style must describe
+the same source. Never combine an explicit different source UID with the runtime
+source's inferred dialect. Supplying both a UID and dialect retains offline
+compilation; execution still applies API source binding and grants.
+
+Optional reads from another registered source use the imported MetaTable's source
+through ADR 0010's bounded reader. They do not change the resolved API, runtime
+default or write destination. General SQL on another source needs a separate
+database-permission design; the client must not imply that an explicit UID grants
+that capability. Document default compilation, offline compilation, source-specific
+errors and the distinction between bounded external reads and runtime SQL.
+
 Cache only the stable endpoint and the release identity needed to describe that
 selection. Do not cache temporary release-access tokens, admission/readiness
 decisions, permission facts or the API's effective DataSource with it. SDK session
@@ -165,7 +205,7 @@ Keep it in a separate, memory-only SDK `SessionJWTAuthProvider`, outside the
 endpoint cache and shared platform session. The SDK request helper retries a
 401 once: reacquire access for the same release UID and reject a changed URL
 instead of retargeting the request. This does not repeat name discovery or add an
-authentication contract. Local and explicit-URL transports retain their existing
+authentication contract. Local development transports retain their existing
 SDK session behavior.
 
 The API's `/runtime-context/` response remains fresh under API ADR 0001. Resetting
@@ -177,8 +217,8 @@ those changes or introduce client database access.
 
 | Owner | Responsibility |
 | --- | --- |
-| MetaTables client | Read the packaged workflow, configuration precedence, shared endpoint resolver, process cache and resolution errors. |
-| Main Sequence SDK/platform | Generic exact-name release discovery, accessible release scope, endpoint and release-access retrieval. |
+| MetaTables client | Read the packaged workflow, select the release in the SDK-owned Environment, enforce the local URL override, share and cache endpoints, and report resolution errors. |
+| Main Sequence SDK/platform | Resolve the caller's Environment and provide authorized release discovery, owning-branch metadata and release access. |
 | MetaTables API | Own the automatic deployment declaration, runtime descriptor, admission, Settings, bootstrap and its enforced DataSource binding. |
 
 This is a separate client ADR because API runtime selection and storage ownership
@@ -186,9 +226,10 @@ do not change. API ADR 0001's prohibition on caching effective runtime context
 remains in force. The Vite Admin site's connection configuration is outside this
 Python-client decision.
 
-Existing explicit URL configurations continue to work. Automatic mode adds a
-platform discovery dependency only when no URL is provided. A deleted or replaced
-deployment can require an explicit reset or process restart to discover a new
+Local explicit URL configurations continue to work. Existing hosted URL overrides
+must be removed; Environment discovery replaces them. Hosted selection requires
+SDK Environment context and authorized reads of candidate branch metadata. A
+deleted or replaced deployment can require an explicit reset or process restart to discover a new
 address; normal requests do not repeatedly search for one.
 
 ## Implementation and acceptance criteria
@@ -206,17 +247,22 @@ The workflow must be applied on the platform before the hosted launch can find i
 
 - The client obtains the actual MetaTables deployment name from automatic
   deployment metadata and resolves it through the SDK without a user-supplied
-  name or UID, including outside the consuming repository's branch.
+  name, UID or URL, including outside the consuming repository's branch but
+  always within its resolved Environment.
+- Identically named deployments in other Environments are ignored; a lone release
+  in the wrong Environment cannot be selected. Missing Environment context,
+  unverifiable ownership or duplicate releases within the selected Environment
+  fail before runtime access. Test both signed-in and authenticated runtime context.
 - Tests use distinct deployment-generated names and verify that a fresh lookup
   after an editable-workflow rename uses updated metadata without edits to
   consuming projects. Wheels retain their packaged deployment declaration.
   Missing or ambiguous metadata/names fail clearly without a constant fallback.
 - Repeated and concurrent operations across resource classes and CLI consumers
   perform one successful discovery sequence per process and configuration.
-- An explicit URL bypasses all discovery, including automatic-deployment metadata
-  retrieval and a populated cache, and preserves route prefixes. Invalid explicit
-  URLs do not trigger discovery.
-- Failed resolution remains retryable; reset, configuration changes and process
+- A local loopback URL bypasses all discovery, including Environment and
+  automatic-deployment metadata retrieval and a populated cache, and preserves
+  route prefixes. Invalid URLs and hosted URL overrides fail without discovery.
+- Failed resolution remains retryable; reset, Environment/configuration changes and process
   forks do not reuse a stale target.
 - Local explicit-URL operations still work on an unregistered branch without
   introducing a platform release or Environment requirement.
@@ -225,7 +271,9 @@ The workflow must be applied on the platform before the hosted launch can find i
 - Resource calls and migration lifecycles consistently use their selected API;
   the resolver never redirects ordinary SDK platform requests to that API.
 - Update connection guides, configuration reference and executable examples with
-  automatic and explicit modes once behavior is verified. Keep dependency and
+  automatic hosted discovery and local development selection once behavior is verified.
+  Document removal of hosted URL overrides and Environment-specific deployment
+  errors without suggesting URL or name workarounds. Keep dependency and
   authentication boundaries covered by the existing checks.
 
 ## References

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/adr/index.md

@@ -16,7 +16,7 @@ decisions belong in the SDK repository and are linked as dependencies.
 
 | ADR | Status | Scope |
 | --- | --- | --- |
-| [0003: Automatic API endpoint resolution](client/0003-api-endpoint-resolution.md) | Accepted and implemented; live hosted verification pending | Read the name from the packaged API workflow, resolve through the SDK, cache the endpoint per process, and allow an explicit URL override. |
+| [0003: Automatic API endpoint resolution](client/0003-api-endpoint-resolution.md) | Accepted and implemented; live hosted verification pending | Resolve the packaged API name within the SDK-owned Environment, cache per platform/Environment, and reserve URL overrides for local development. |
 | [0011: Local CLI workflow with reusable Admin](client/0011-cli-local-development-with-managed-admin.md) | Accepted; implemented | Download missing Admin source once, reuse ready dependencies, launch the installed API with Vite, and expose explicit bootstrap, application-owned migrations and local client connection. |
 
 ## API

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/client/installation-and-connection.md

@@ -112,9 +112,13 @@ checkout. After upgrading the client, rerun it to refresh the copied bundle.
 
 ## Connect to an API
 
-Authenticate through the SDK. With no explicit URL, the client reads the API
-deployment name from the workflow bundled with MetaTables, finds exactly one
-visible FastAPI release through the SDK, and caches its endpoint in this process:
+Authenticate through the SDK. Hosted connections require no API URL. The client
+reads the API deployment name from the workflow bundled with MetaTables and
+selects exactly one release in the caller's resolved Organization Environment.
+The SDK obtains that Environment from the registered consuming branch or the
+authenticated runtime credential. This also applies when running on a developer
+machine and connecting to a hosted API. The endpoint is cached per platform and
+Environment in this process:
 
 ```bash
 mainsequence login
@@ -122,10 +126,10 @@ unset METATABLES_API_URL
 metatables --json meta-table detail TABLE_UID
 ```
 
-To select an explicit endpoint, set `METATABLES_API_URL`. It overrides discovery,
-including an already cached deployment. It is the base URL mounting `/meta-tables` and related
-routes. The checked-in API mounts them at its root. If a deployment adds a path
-prefix, include that prefix in the value:
+`METATABLES_API_URL` is only for a local development API on `localhost` or a
+loopback IP address. `--local` and `configure_local_client()` set it automatically
+from the launcher's private connection file. A manual local URL overrides
+discovery, including an already cached deployment, and can include a path prefix:
 
 ```bash
 export METATABLES_API_URL=http://127.0.0.1:18473
@@ -134,9 +138,19 @@ export METATABLES_API_URL=http://127.0.0.1:18473
 The name comes from `.mainsequence/workflows/metatables-api.yaml` in the
 MetaTables repository, packaged unchanged with installed clients. No deployment
 UID or name variable is needed in consuming projects. Missing or ambiguous
-deployments fail clearly. Apply the workflow before using hosted discovery;
+deployments **within the selected Environment** fail clearly. The same name in
+other Environments is expected and requires no configuration. A lone deployment
+in another Environment is never used as a fallback. Apply the workflow in the
+intended Environment before using hosted discovery;
 having the Python package installed does not create a deployment.
 
+Remove existing hosted `METATABLES_API_URL` values; non-loopback overrides are
+rejected. If the SDK cannot resolve the caller's Environment, fix the consuming
+branch registration or runtime context. If no deployment matches, apply the API
+workflow in that Environment; if several match within it, remove the duplicates.
+Discovery also requires authorized SDK reads of the candidate releases' owning
+branch metadata to verify their Environments.
+
 Call `metatables.endpoint.reset_api_endpoint()` or restart the process to resolve
 again. This rereads the workflow in editable installs; a wheel uses its packaged
 snapshot. Renamed deployment declarations require the matching package build.
@@ -144,7 +158,7 @@ See [client ADR 0003](../adr/client/0003-api-endpoint-resolution.md).
 
 The client uses SDK-issued release access for automatically discovered deployments,
 separate from the platform session. SDK request handling renews rejected release
-credentials for the same target without repeating name discovery. Explicit URLs
+credentials for the same target without repeating name discovery. Local URLs
 retain the existing SDK session behavior. The
 platform ingress supplies the caller proof consumed by the API. Direct callers
 cannot replace that proof with an unsigned user UID.
@@ -156,7 +170,8 @@ Git source facts remain required; platform branch registration is unnecessary.
 ## Keep the scopes explicit
 
 Use SDK configuration for platform authentication and repository identity. Use
-automatic deployment discovery or `METATABLES_API_URL` for table operations. The API selects the effective DataSource. The client discovers its storage capabilities and
+Environment-scoped discovery for hosted table operations and the local development
+connection for a local API. The API selects the effective DataSource. The client discovers its storage capabilities and
 dialect through `/runtime-context/`. Never point the SDK session
 at the MetaTables URL to make table requests work.
 

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/client/query-and-mutate.md

@@ -10,20 +10,38 @@ authorize the caller; the selected engine backend executes the database operatio
 Use `metatables.compiled_sql.v1.compile_sqlalchemy_statement(...)` to compile a
 SQLAlchemy Core statement with bound parameters. A request selects one DataSource;
 the database applies your Reader and Writer grants to every table it touches.
-[The query example](../examples/query.py) selects account rows by name:
+Omit source and dialect configuration for the normal application path:
 
 ```python
-from metatables.examples.query import find_accounts
+from sqlalchemy import String, column, select, table
 
-result = find_accounts("runtime-data-source-uuid", "Savings")
+from metatables import MetaTable
+from metatables.compiled_sql.v1 import compile_sqlalchemy_statement
+
+accounts = table("ledger_account", column("name", String))
+operation = compile_sqlalchemy_statement(
+    select(accounts).where(accounts.c.name == "Savings"), operation="select"
+)
+result = MetaTable.execute_operation(operation)
 ```
 
-The compiler can obtain the DataSource and dialect from the API runtime context.
+The client discovers the MetaTables deployment in the caller's Environment. The
+compiler obtains the DataSource UID, dialect and parameter style together from
+that API's fresh runtime context. No URL or DataSource UID is needed in the
+application. The API operator configures and initializes the runtime in Settings.
+An absent, unavailable or malformed runtime source raises the public
+`metatables.DataSourceResolutionError`; it never selects another source as a fallback.
+
 For offline compilation, supply both `data_source_uid=` and `dialect=`. PostgreSQL
 and MySQL use `pyformat`, SQL Server uses ordered `qmark`, and SQLite uses named
 parameters. The API checks the wire dialect and the runtime binding. There is no
 list of declared table scopes and no SQL parser in the API.
 
+If only a UID is supplied, it must match the runtime source before the compiler
+can infer its dialect. A different UID cannot borrow the runtime's dialect.
+Supplying a UID and dialect offline creates a payload; it does not authorize
+execution against another source. See the explicit [query example](../examples/query.py).
+
 For applications still passing `scope_tables` or importing the removed scope
 classes, follow [upgrade a legacy application](upgrade-legacy-app.md). Remove the
 scope machinery instead of recreating it as per-query client checks.
@@ -48,6 +66,28 @@ an explicit commit inside a write batch can persist writes before a later error.
 Use the supported table operations when an operation needs their transaction and
 journal guarantees. See [database access](../security/index.md#sql-and-schema-boundary).
 
+## Read another registered source
+
+Keep the same API connection and runtime default. An administrator first
+[imports the source's tables or views](register-existing-tables.md); Readers and
+Writers then select an imported MetaTable and use its registered source:
+
+```python
+from metatables import MetaTable
+
+external_table = MetaTable.get_by_uid("imported-table-uuid")
+page = external_table.read_rows(columns=["symbol"], limit=100)
+```
+
+Use `iter_rows()` to consume bounded pages incrementally. These operations honor
+table and namespace grants, source availability and read-only access. They do
+not change the catalog, runtime DataSource selection or write destination.
+The current external reader accepts structured columns, predicates and ordering;
+it does not accept SQL or joins. `run_query()` and `execute_operation()` against
+another source return HTTP 409 with `data_source_not_selected_runtime`, rather
+than HTTP 503 suggesting an outage. General external SQL requires a separate
+permission model; `operation="select"` alone does not establish that boundary.
+
 ## Metadata and search
 
 `MetaTable.filter_by_body(...)` supports catalog filtering and pagination.

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/client/register-existing-tables.md

@@ -90,6 +90,10 @@ namespace grants. These application grants do not create roles or permissions in
 the external database. Runtime SQL security can remain uninitialized while
 external imports and reads work. Arbitrary SQL remains restricted to the selected
 runtime DataSource and its database-enforced caller permissions.
+`read_rows()` and `iter_rows()` derive the source from the imported MetaTable;
+callers do not replace the API URL or the runtime default to read another source.
+An external UID passed to a SQL endpoint returns the explicit
+`data_source_not_selected_runtime` conflict (HTTP 409).
 
 For SQLite runtime views, bounded reads allow only the approved view's output.
 Arbitrary SQL still requires grants on its underlying tables: SQLite's view-origin

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/client/upgrade-legacy-app.md

@@ -88,7 +88,16 @@ def execute_repository_operation(operation, *, context):
 ```
 
 The compiler resolves missing DataSource or dialect values from the selected API
-runtime. A MetaTable UID is not a DataSource UID. For offline compilation supply
+runtime. Leave `context.data_source_uid` as `None` for the automatic path: the
+Environment selects the API deployment, and its runtime supplies the source and
+dialect together. No application URL or source setting is needed. Missing or
+malformed source metadata raises `metatables.DataSourceResolutionError`.
+An explicit UID must match that runtime when its dialect is inferred; another
+source cannot inherit the runtime dialect. Optional external reads use imported
+MetaTables' `read_rows()`/`iter_rows()` under existing grants; arbitrary SQL remains
+runtime-bound. See [query and mutate](query-and-mutate.md).
+
+A MetaTable UID is not a DataSource UID. For offline compilation supply
 both `data_source_uid` and `dialect`. For example, this exercises the replacement
 compiler above without registration, credentials or a running API:
 

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/concepts/runs-and-execution-graphs.md

@@ -89,7 +89,7 @@ today's definitions.
 
 ## Runs in Admin
 
-**Runs** lists recorded attempts by default. Use **Attempts → Root invocations**
+**Runs** lists recorded attempts by default. Use **Root invocations only**
 to restrict history to roots. The compact history on the left identifies each
 run by date/time, source updater, outcome indicator, and duration. Selecting a row
 shows that Run's UID, timestamps, outcome and duration on the right. The updater

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/operations/configuration.md

@@ -5,14 +5,16 @@ implement a second platform HTTP client or token exchange.
 
 | Setting | Consumer | Purpose |
 | --- | --- | --- |
-| `METATABLES_API_URL` | Python client / CLI | Explicit base URL; unset/empty selects automatic discovery from the packaged API workflow. |
+| `METATABLES_API_URL` | Python client / CLI | Local development only: loopback HTTP(S) base URL, set automatically by `--local` or `configure_local_client()`. Unset/empty resolves the packaged API deployment in the caller's SDK-owned Environment. Hosted URL overrides are rejected. |
 | `local_mode_available` in `configuration.yaml` | API / launcher | Enables developer Local/Hosted selection; strict boolean, default false. |
 | `METATABLES_LOCAL_TOKEN` | Local launcher and client | Private ASCII token of at least 40 characters. |
 | `METATABLES_LOCAL_ALLOWED_ORIGINS` | Local API | Comma-separated exact loopback HTTP(S) origins with explicit ports; empty by default. |
 | `METATABLES_LOCAL_STORAGE_DIR` | Local API | Root for the checkout's local runtime SQLite file, shared across Git branches; defaults to `~/.local/share/metatables`. |
 
-Client discovery uses the name derived from the API automatic-deployment file,
-not a deployment-name environment variable. It caches only the resolved endpoint
+Client discovery uses the name derived from the API automatic-deployment file
+and the caller's resolved Organization Environment. Identical names in other
+Environments do not require URL configuration or renaming. The cache is scoped
+to the platform and Environment and retains only the resolved endpoint
 and target identity; `/runtime-context/` continues to supply fresh DataSource
 state. See [client connection](../client/installation-and-connection.md).
 

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/operations/run-history.md

@@ -14,8 +14,9 @@ In Admin, open **Runs**. The left-hand list shows all recorded attempts by defau
 including dependency attempts and older records without a captured graph. Each
 entry shows its timestamp, outcome and duration; dependency attempts are indented
 under their invocation's root when both are on the page. Select one to inspect its
-invocation and logs. Choose **Root invocations** in the **Attempts** filter to
-restrict the list explicitly, or filter by updater, outcome or start-time interval.
+invocation and logs. The filters head the list: updater, outcome, a start-time
+range (last hour, 24 hours, 7 days or a custom local-time range) and **Root
+invocations only**. **Clear filters** keeps the selected run.
 The URL keeps these filters and the selected run. On narrow screens, the list
 appears above the run.
 Use **Hide history** to give the run the full width; **Show history** restores

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/docs/reference/python.md

@@ -22,6 +22,7 @@ Import application APIs from `metatables`. This list is generated from `metatabl
 | `DEFAULT_ALEMBIC_VERSION_TABLE_NAME` | `metatables` | constant |
 | `DEFAULT_PLATFORM_MANAGED_PROVISIONING` | `metatables` | constant |
 | `DataSource` | `metatables.models` | class |
+| `DataSourceResolutionError` | `metatables.runtime_contract` | class |
 | `LastUpdateIndexTimePayload` | `metatables.models` | class |
 | `LastUpdateMultiIndexStatsPayload` | `metatables.models` | class |
 | `ManagedMetaTableCollectionCreateRow` | `metatables.models` | class |

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.6.dev7"
+version = "0.1.7.dev9"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/scripts/check_boundaries.py

@@ -23,10 +23,11 @@ SDK_MODULES = frozenset({
 })
 SHARED_MODULES = frozenset({'metatables.local_connection', 'metatables.local_files', 'metatables.sdk_compat', 'metatables.update_configuration_contract',
                            'metatables.transfer_contract', 'metatables.runtime_contract', 'metatables.log_contract', 'metatables.local_run_logs'})
-# Read-only platform provenance for the initialization descriptor. These exact
-# identifiers are allowed only at the SDK admission/display boundary; catalog
+# Read-only platform provenance for initialization and endpoint discovery. These exact
+# identifiers are allowed only at the SDK admission/display/discovery boundary; catalog
 # models, constraints and storage policy remain forbidden from owning them.
 DISPLAY_PROVENANCE = {
+    "src/metatables/endpoint.py": {"environment_uid", "organization_environment_uid", "resolve_organization_environment_uid"},
     "src/metatables/cli/local.py": {"sdk_session_environment", "vite_environment", "api_environment"},
     "src/metatables/sdk_compat.py": {"is_organization_admin"},
     'src/metatables/api/app/auth/boundary.py': {'environment_uid', 'organization_environment_uid', 'is_organization_admin'},

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.6.dev7
+Version: 0.1.7.dev9
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.6.dev7 → mainsequence_metatable-0.1.7.dev9}/src/mainsequence_metatable.egg-info/SOURCES.txt

@@ -419,6 +419,7 @@ tests/contracts/capabilities.json
 tests/contracts/client_signatures.json
 tests/contracts/database_operations.json
 tests/contracts/test_bounded_transfer.py
+tests/contracts/test_compiler_runtime_source.py
 tests/contracts/test_relation_batching.py
 tests/contracts/test_relation_import.py
 tests/contracts/test_storage_layouts.py