mainsequence-metatable 0.1.5.dev6__tar.gz → 0.1.6__tar.gz

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/.agents/skills/client/metatables-local-development/SKILL.md

@@ -12,11 +12,11 @@ development fixtures and test writes in the local runtime, then return to the
 intended environment as part of the requested workflow. Respect an explicitly
 requested target or backend-specific test scope.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. In the MetaTables source checkout, resolve
 them from the repository root. Read `docs/operations/local-runtime.md` for runtime
 selection and persistence, and `docs/client/installation-and-connection.md` when
-installing or troubleshooting. `examples/local_app/README.md` provides a complete
+installing or troubleshooting. `src/metatables/examples/local_app/README.md` provides a complete
 installed-package migration/write/read example.
 
 ## Select local storage deliberately

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -12,7 +12,7 @@ client. It covers application-facing models and workflows. Client-library
 implementation, this repository's development/release tooling, and API internals
 have separate ownership.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -51,7 +51,7 @@ contract. Preserve the user's existing authorization and scope.
   evolution.
 - Existing externally owned tables use `register_external_sqlalchemy_model` with
   their actual physical binding. Registration does not create the physical table;
-  see `docs/client/register-existing-tables.md` and `examples/external_table.py`.
+  see `docs/client/register-existing-tables.md` and `src/metatables/examples/external_table.py`.
 - `backend_managed` is a separate low-level API provisioning intent. Do not use it
   as a substitute for ordinary managed application-table migrations.
 
@@ -62,7 +62,7 @@ are fingerprints, not table identity. See `docs/concepts/identity-and-scope.md`.
 
 ## SQLAlchemy contract rules
 
-Use `examples/tables.py` as the tested pattern. Declare an explicit
+Use `src/metatables/examples/tables.py` as the tested pattern. Declare an explicit
 application-prefixed physical name with `schema_table_name(app, concept)`, a
 stable logical identifier, and an intention-rich `__metatable_description__`.
 Give columns useful `info={"label": ..., "description": ...}` metadata. Explain
@@ -84,7 +84,7 @@ revisions; do not recompute identity from columns or rewrite applied history.
 
 ## Queries and mutations
 
-Read `docs/client/query-and-mutate.md` and `examples/query.py`. Use
+Read `docs/client/query-and-mutate.md` and `src/metatables/examples/query.py`. Use
 `compile_sqlalchemy_statement` with bound parameters. The request sends SQL and
 selects one DataSource; the API executes as the authenticated user, and the
 selected database backend enforces Reader/Writer permissions on the tables

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/.agents/skills/client/metatables-migrations/SKILL.md

@@ -16,7 +16,7 @@ For upgrading older client imports, SQL scopes or provider integration, use the
 [legacy upgrade skill](../metatables-upgrade-legacy-app/SKILL.md). This skill
 covers authoring and running application schema revisions.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -28,7 +28,7 @@ verification within the requested scope.
 
 Read `docs/client/define-and-migrate-tables.md`,
 `docs/concepts/table-contracts-and-lifecycle.md`, and the tested
-`examples/tables.py`. Managed authoring is migration-first: define SQLAlchemy
+`src/metatables/examples/tables.py`. Managed authoring is migration-first: define SQLAlchemy
 models, select a provider, author and apply a revision with the client, then
 finalize catalog bindings through the API. Use the
 [table skill](../metatables-meta-tables/SKILL.md) for contract design.
@@ -106,7 +106,7 @@ and finalizes contracts through the API. Treat connection material as private.
 
 Use the application's setup entry point when available. Python code can call
 `metatables.upgrade_application("ledger.migrations:migration")`;
-`examples/scripts/setup_metatables.py` shows the pattern. Remove the retired
+`src/metatables/examples/scripts/setup_metatables.py` shows the pattern. Remove the retired
 `application_migration_providers` setting and use Python references instead of aliases.
 Application migration histories remain separate from API system migrations.
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/.agents/skills/client/metatables-time-index-table-updates/SKILL.md

@@ -12,7 +12,7 @@ client. It covers application-facing models and workflows. Client-library
 implementation, this repository's development/release tooling, and API internals
 have separate ownership.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -24,8 +24,8 @@ verification within the requested scope.
 
 Read `docs/client/build-an-updater.md`,
 `docs/concepts/time-index-tables-and-updates.md`, and the tested
-`examples/updater.py`. Use `docs/client/read-existing-time-index-tables.md` and
-`examples/reader.py` for consumers that only need existing output.
+`src/metatables/examples/updater.py`. Use `docs/client/read-existing-time-index-tables.md` and
+`src/metatables/examples/reader.py` for consumers that only need existing output.
 
 The storage contract is a `PlatformTimeIndexMetaTable` SQLAlchemy class. The
 producer is a `TimeIndexTableUpdater`; the API record is `TimeIndexTableUpdate`.
@@ -41,7 +41,7 @@ choices, first-run/backfill bounds, and whether identity must be preserved from
 the task and existing code. Clarify only unresolved choices that change the
 published contract. Keep storage description, namespace, identifier, cadence,
 columns, and FK/index metadata on the authoring model, not the updater config.
-Use intention-rich table and column descriptions; see `examples/tables.py`.
+Use intention-rich table and column descriptions; see `src/metatables/examples/tables.py`.
 
 Migrate and bind the output class before constructing the producer. Pass explicit
 `config` and `output_table`; do not create/register tables inside `update()`.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/.agents/skills/client/metatables-upgrade-legacy-app/SKILL.md

@@ -14,7 +14,7 @@ in the MainSequence SDK.
 
 Read `docs/client/upgrade-legacy-app.md` for the conversion table and before/after
 repository compiler examples. In a copied skill, resolve the `docs/` and
-`examples/` paths here relative to this skill's `references/` directory. In the
+`src/metatables/examples/` paths here relative to this skill's `references/` directory. In the
 MetaTables source checkout, resolve them from the repository root.
 
 Use `docs/client/installation-and-connection.md` to establish the target package

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/MANIFEST.in

@@ -1,8 +1,9 @@
 include alembic.ini mkdocs.yml uv.lock compose.database-tests.yml
 include .mainsequence/workflows/metatables-api.yaml
-include api/metatables/configuration.yaml
+include api/metatables/main.py
+include src/metatables/api/metatables/configuration.yaml
 recursive-include docs *.md *.json *.py *.csv *.mako *.svg
-recursive-include examples *.md *.json *.py *.csv *.mako
+recursive-include src/metatables/examples *.md *.json *.py *.csv *.mako
 recursive-include scripts *.py
 recursive-include tests *.py *.json Dockerfile Dockerfile.dockerignore
 graft .agents/skills/client

{mainsequence_metatable-0.1.5.dev6/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.5.dev6
+Version: 0.1.6
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -100,7 +100,7 @@ through Settings; startup never runs Alembic.
 The [documentation index](docs/index.md) separates client, API, operations, and
 contributor guides. The [capability reference](docs/reference/capabilities.md)
 records implemented and unavailable operations, including inherited methods and
-CLI commands. Runnable guide assets live in [examples](examples/README.md).
+CLI commands. Runnable guide assets live in [examples](src/metatables/examples/README.md).
 
 ## Client skills
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/README.md

@@ -45,7 +45,7 @@ through Settings; startup never runs Alembic.
 The [documentation index](docs/index.md) separates client, API, operations, and
 contributor guides. The [capability reference](docs/reference/capabilities.md)
 records implemented and unavailable operations, including inherited methods and
-CLI commands. Runnable guide assets live in [examples](examples/README.md).
+CLI commands. Runnable guide assets live in [examples](src/metatables/examples/README.md).
 
 ## Client skills
 

mainsequence_metatable-0.1.6/alembic.ini

@@ -0,0 +1,3 @@
+[alembic]
+script_location = src/metatables/api/backend/migrations
+

mainsequence_metatable-0.1.6/api/metatables/main.py

@@ -0,0 +1,5 @@
+"""Hosted workflow entrypoint; the server is installed as metatables.api."""
+
+from metatables.api.metatables.main import app
+
+__all__ = ["app"]

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/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.5.dev6 → mainsequence_metatable-0.1.6}/docs/adr/api/0004-approved-application-migrations.md

@@ -50,7 +50,7 @@ remain explicit Settings operations.
 
 ## Example integration
 
-`examples/scripts/setup_metatables.py` only reserves, upgrades and finalizes the
+`src/metatables/examples/scripts/setup_metatables.py` only reserves, upgrades and finalizes the
 tutorial provider. Every data-dependent tutorial command calls it first. VS Code
 launches then seed instruments and run producers through `--prepare-data` before
 the requested example. Offline preview and endpoint-only connect skip preparation.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/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.5.dev6 → mainsequence_metatable-0.1.6}/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.
 
@@ -46,7 +53,7 @@ ownership and unknown-outcome reconciliation. Local verification is complete; ho
 
 `POST /data-sources/` accepts `mysql` and `mssql`, and validation opens their
 connections and runs `SELECT 1`. At the time of the original decision, the
-static feature registry declared no table support for either. The physical operations in `api/backend/integrations/`
+static feature registry declared no table support for either. The physical operations in `src/metatables/api/backend/integrations/`
 use PostgreSQL or SQLite connections, SQL and introspection; they cannot act on
 the registered MySQL or MSSQL source.
 
@@ -172,14 +179,14 @@ engine matrices in routes, Admin and documentation.
 
 Refactor the current SQLite and PostgreSQL paths into this contract before
 adding MySQL and MSSQL implementations. In particular, remove engine decisions
-from `api/app/bootstrap.py`, `api/app/routes/application_migrations.py`,
-`api/app/routes/table_sql.py`, `api/app/routes/runtime_context.py`, and
-`api/backend/integrations/source_validation.py`; route existing SQLite and
+from `src/metatables/api/app/bootstrap.py`, `src/metatables/api/app/routes/application_migrations.py`,
+`src/metatables/api/app/routes/table_sql.py`, `src/metatables/api/app/routes/runtime_context.py`, and
+`src/metatables/api/backend/integrations/source_validation.py`; route existing SQLite and
 PostgreSQL work through the bound backend in this first step, before implementing
 MySQL or MSSQL table support. During the refactor, retain the existing MySQL/MSSQL
 connection probes without pretending they satisfy the full backend contract.
 Move the branches in `postgresql_*`
-physical helpers and `api/backend/database_operations/runtime.py` into adapter
+physical helpers and `src/metatables/api/backend/database_operations/runtime.py` into adapter
 implementations or shared engine-neutral helpers. This refactor must preserve
 current SQLite and PostgreSQL behavior under the existing contract tests. It
 prevents the new engines from multiplying conditionals across every endpoint.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/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
@@ -60,10 +69,10 @@ explicitly identified as belonging to the Vite application.
 
 | Area | Current evidence | Required change |
 | --- | --- | --- |
-| HTTP workflow | Generated OpenAPI has `POST /meta-tables/register/` and `POST /meta-tables/{uid}/introspect/`, but no import action. `api/app/routes/table_registration.py` requires one caller-authored contract. | One import operation with discovery, preview, selection, reconciliation, and structured results. |
-| Discovery | `TableBackend` in `api/backend/backends/contracts.py` introspects a known name. It has no relation discovery or batch introspection contract. | Add narrow discovery and read operations to this existing facet. |
+| HTTP workflow | Generated OpenAPI has `POST /meta-tables/register/` and `POST /meta-tables/{uid}/introspect/`, but no import action. `src/metatables/api/app/routes/table_registration.py` requires one caller-authored contract. | One import operation with discovery, preview, selection, reconciliation, and structured results. |
+| Discovery | `TableBackend` in `src/metatables/api/backend/backends/contracts.py` introspects a known name. It has no relation discovery or batch introspection contract. | Add narrow discovery and read operations to this existing facet. |
 | External source resolution | `CatalogDataSourceProvider.get()` calls `RuntimeStorageBinding.require_execution_source()`. A saved non-runtime source cannot be used by table operations. | Resolve sources according to the authorized operation; preserve the runtime restriction for managed DDL, migrations, and caller-written SQL. |
-| Restart invariants | `RuntimeBootstrap.inspect()` in `api/app/bootstrap.py` rejects any `MetaTable` or `PhysicalOperation` referencing another source. | Permit externally owned MetaTables on registered sources, while keeping physical mutation journals and managed tables bound to the runtime source. |
+| Restart invariants | `RuntimeBootstrap.inspect()` in `src/metatables/api/app/bootstrap.py` rejects any `MetaTable` or `PhysicalOperation` referencing another source. | Permit externally owned MetaTables on registered sources, while keeping physical mutation journals and managed tables bound to the runtime source. |
 | View access | `postgresql_access.py` and `sqlite_access.py` require ordinary tables. `hosted.py` rejects MySQL objects other than base tables and MSSQL objects other than user tables. | Explicit view admission and read semantics. Changing an introspection query alone is insufficient. |
 | Physical metadata | `MetaTable.kind` distinguishes relational and time-index tables. Contract normalization preserves extra physical fields but does not validate `relation_kind` as a first-class invariant. | Validate physical relation kind independently of the existing logical kind. A view is a relational MetaTable. |
 | Names and types | `catalog_rules.py` and `table_contracts.py` impose an unqualified 63-character table-name rule; `models.py` stores `String(63)`. Some type validation retains PostgreSQL assumptions. | Preserve legal external identifiers and native types through adapter normalization, without truncation or executing catalog expressions. |
@@ -118,7 +127,7 @@ generic capability registry is introduced.
 ### 2. Extend the existing backend contract
 
 Add these conceptual operations to `DatabaseBackend.tables` in
-`api/backend/backends/contracts.py`; retain `backend_for(source)` as the only
+`src/metatables/api/backend/backends/contracts.py`; retain `backend_for(source)` as the only
 engine dispatch point:
 
 ```text
@@ -556,11 +565,11 @@ availability.
 
 ## Implementation and verification record
 
-- Shared orchestration: `api/backend/operations/import_relations.py`; engine
+- Shared orchestration: `src/metatables/api/backend/operations/import_relations.py`; engine
   discovery, read-only sessions and safe runtime-view validation:
-  `api/backend/backends/relation_tables.py`, selected by the existing registry.
-- Published commands/results: `api/backend/contracts/relation_import.py` and
-  `api/app/routes/table_import.py`. Existing introspect handles Writer refresh.
+  `src/metatables/api/backend/backends/relation_tables.py`, selected by the existing registry.
+- Published commands/results: `src/metatables/api/backend/contracts/relation_import.py` and
+  `src/metatables/api/app/routes/table_import.py`. Existing introspect handles Writer refresh.
 - Migration `0007_external_relation_names` widens hosted physical names to 128
   characters. SQLite retains its descriptive legacy VARCHAR width without a table
   rebuild; SQLite does not enforce that width. Missing relation kinds read as table.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/docs/adr/api/0013-application-owned-migrations.md

@@ -80,7 +80,7 @@ dropped tables. Revision files already applied remain immutable.
 
 ## MetaTables system migrations
 
-The API continues to own `api.backend.migrations`, `metatables_catalog_version`
+The API continues to own `metatables.api.backend.migrations`, `metatables_catalog_version`
 and the explicit admin bootstrap/upgrade operation in Settings. Application
 migration commands do not invoke that operation. Applications must keep their
 physical names and version tables separate from reserved system objects.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6}/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