Dependency Compatibility

Dependency versions can change parsing, generated values, serialization, SQL policy, or validation without changing this package. The release evidence therefore distinguishes a minimum candidate profile from the latest tested lock. A profile is supported only after its CI job passes; declaring a range in package metadata alone is not compatibility evidence.

Semantic Dependency Inventory

Dependency Surface affected Base or extra
Faker Seeded semantic values and locale behavior Base
Pydantic DatasetSpec, profile, manifest, and report parsing/validation Base
PyYAML YAML spec and business-rule parsing Base
PyArrow Parquet reading, writing, and schema conversion parquet
MCP Generator and Trino transport schemas mcp
sqlglot Read-only SQL parsing and policy enforcement postgres, trino
Trino client Connection construction and bounded query execution trino
OpenAI Optional advisor-provider request/response transport openai
GigaChat Optional advisor-provider request/response transport gigachat
Psycopg Read-only PostgreSQL connection boundary postgres

Transitive packages are recorded by the lock and supply-chain evidence, but do not receive an independent support promise unless they affect one of these contract surfaces directly.

Profiles

Minimum candidates match the lower bounds in pyproject.toml. Latest versions are the versions in the reviewed uv.lock used by the release gate on 2026-08-12.

Profile Python Direct dependency set
base-minimum 3.11 Faker 25.0.0; Pydantic 2.7.0; PyYAML 6.0.0
parquet-minimum 3.11 Base minimum; PyArrow 15.0.0
mcp-minimum 3.11 Faker 25.0.0; Pydantic 2.11.0; PyYAML 6.0.0; MCP 1.28.1
trino-minimum 3.11 Base minimum; sqlglot 30.0.0; Trino 0.330.0
openai-minimum 3.11 Base minimum; OpenAI 2.46.0
gigachat-minimum 3.11 Base minimum; GigaChat 0.2.3
postgres-minimum 3.11 Base minimum; Psycopg 3.2.0; sqlglot 30.0.0
latest-all 3.11–3.14 Faker 40.35.0; Pydantic 2.13.4; PyYAML 6.0.3; PyArrow 25.0.0; MCP 2.2.0; sqlglot 30.13.0; Trino 0.338.0; OpenAI 3.18.0; GigaChat 0.2.3; Psycopg 3.3.4

MCP 1.28.1 requires Pydantic 2.11.0, so its minimum profile cannot reuse the base Pydantic 2.7.0 candidate. The minimum profiles otherwise isolate one optional extra at a time. latest-all tests the locked dependency set across every supported Python version. The CI matrix installs these profiles without silently upgrading minimum candidates and runs the contract tests relevant to each surface.

Contract Coverage

The minimum profiles run focused contracts instead of the full locked suite:

Profile Required behavior CI contract
base-minimum Deterministic generation and validation; Pydantic JSON and PyYAML parsing tests/test_io_workflows.py, tests/test_business_rules.py
parquet-minimum Parquet serialization and loading tests/test_io_commands.py
mcp-minimum Generator and Trino MCP transport schemas and real bounded stdio tests/test_mcp_generator_transport.py, tests/test_mcp_trino_transport.py, tests/test_mcp_sdk_roundtrip.py
trino-minimum SQL policy and Trino client construction tests/test_mcp_trino_server.py
openai-minimum Provider request, response, and error contracts tests/test_openai_provider.py
gigachat-minimum Provider request, response, TLS, authentication, and error contracts tests/test_gigachat_provider.py
postgres-minimum Read-only connection, SQL query policy, allowlists, budgets, and profile normalization tests/test_postgres_config.py, tests/test_postgres_client.py, tests/test_postgres_query_builders.py, tests/test_postgres_profiler.py, tests/test_sql_query_source.py

The latest-all quality matrix runs the complete test suite on every supported Python version. A minimum profile must not be replaced by a resolver check alone: its behavior contract must also pass in the isolated environment.

Reproducibility Guarantees

MCP 2.2.0 was selected for compatibility testing on 2026-09-23. The shared adapter supports both SDK server APIs while preserving wire aliases and the per-request budget. SDK 2 unexpected tool exceptions produce the fixed Tool execution failed message before SDK logging; validation errors remain redacted. This does not add row-returning tools or relax transport limits.

Scope Guarantee
Same environment Reusing the recorded package, Python, dependencies, locale, serializer, spec, rules, and seed provides the logical reproducibility baseline. Recorded artifact digests can verify an exact repeat.
Same package version Logical behavior is supported only on dependency profiles that pass CI. Different Python, dependency, locale, or serializer versions may change generated values, ordering, and bytes.
Cross-version DatasetSpec compatibility follows its schema-version policy, but generated values, ordering, and byte identity are not guaranteed. Package release notes describe intentional semantic changes.

The manifest records the environment evidence needed to compare runs. Its byte_identical_across_versions: false field is normative: a seed is not a cross-version snapshot promise. normalized_dependencies uses canonical lowercase distribution names and includes installed optional integrations; normalized_dependencies_sha256 fingerprints that map. The legacy dependencies fields remain for additive manifest compatibility.

Support Rules

  • Same package, Python, dependency, locale, serializer, spec, rules, and seed provide the logical reproducibility baseline recorded in the manifest.
  • Byte identity is checked only where an artifact digest is recorded; it is not promised across Python, package, dependency, locale, or serializer changes.
  • A dependency update that changes parsing, generation, SQL policy, or validation semantics requires review, compatibility evidence, and a package release.
  • MCP accepts <3 after migration of server, JSON-RPC and context handling; OpenAI accepts <4 with 2.46.0 minimum and 3.18.0 latest coverage. No new upper major bound is implied for Faker, Pydantic, PyYAML, PyArrow, sqlglot, or Trino until minimum/latest matrix evidence justifies it.
  • GigaChat remains on >=0.2.3,<0.2.4 because its SDK changed the chat API between 0.2.1 and 0.2.3; each later release needs a compatibility review.
  • A failing profile is unsupported until fixed or explicitly removed from the documented range with release notes.

The lockfile is evidence for the latest profile, not a promise that unrelated future dependency versions are compatible.

The release gate treats .github/dependency-compatibility.toml as the reviewed machine-readable record. It rejects runtime dependencies missing from that inventory, lower-bound or lockfile drift, CI profiles that lose their minimum constraints, undocumented reviewed versions, and incomplete or incorrectly hashed dependency evidence in a generated manifest.

Upper-Bound Decisions

Dependency Decision Evidence
MCP Accept <3.0.0 MCP 2.2.0 transport contracts cover byte budgets, redaction and request context; MCP 1.28.1 remains the minimum.
OpenAI Accept <4.0.0 OpenAI 3.18.0 evaluated with offline real-SDK HTTP transport, provider privacy contracts and doctor checks; 2.46.0 minimum retained.
GigaChat Retain <0.2.4 The adapter is tested against the current 0.2.3 chat.create contract; earlier 0.2.x releases use an incompatible call shape.
Faker, Pydantic, PyYAML, PyArrow, sqlglot, Trino, Psycopg Add no upper bound The minimum/latest profiles prove the documented candidates, but do not prove that a future major is incompatible.

A newly discovered incompatibility must first be reproduced by a focused contract test. Narrowing a range then requires a user-facing changelog entry and a package release; an unreviewed speculative bound is not accepted.

Installation Footprint

The CI dependency ceilings are intentionally small enough to catch accidental growth:

Profile Capability Maximum installed distributions
base CSV and JSON 10
parquet Parquet files 11
mcp Generator MCP server 35
openai Optional structured-output advisor 20
gigachat Experimental GigaChat advisor 20
trino Trino client and safe SQL parser 25
postgres Read-only PostgreSQL profiling driver 12

These are regression budgets, not a guarantee that every platform installs the same count. PyArrow is the largest optional wheel, so keep parquet out of environments that do not produce Parquet files.