You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Every floor in [project.optional-dependencies] — litestar>=2.15, prometheus-fastapi-instrumentator>=8.0.1, prometheus-client>=0.20, opentelemetry-instrumentation-asgi>=0.46b0, and now fastmcp>=3 / faststream>=0.6 (#175) — is a claim that nothing in CI checks. just install
runs uv lock --upgrade, so every job resolves the newest release of every
dependency; the lowest version each bootstrapper is documented as supporting is
never imported, let alone bootstrapped.
The floors added in #175 were established by hand, in throwaway venvs, against
the release list as it stood on that day. That verification does not survive the
next change to a bootstrapper: a new call into a framework API that landed after
the declared floor raises the real minimum silently, and the declaration decays
into a comment that used to be true.
Add a _checks.yml job that resolves lowest-direct (uv lock --resolution lowest-direct, or uv pip install --resolution lowest-direct per extra) and
runs the suite against it, so a floor that is too low fails here rather than in a
downstream service. Worth deciding when opening this up:
whether the job gates PRs or only runs in scheduled.yml, since a transitive
dependency's own bad floor can break it for reasons unrelated to this repo;
whether it runs the whole suite once on an all-extras lowest-direct lock, or
per-framework the way install-isolation already loops over extras.
Revisit trigger: a downstream report of a bootstrap failing on a version
inside a declared range, which is exactly the failure this job exists to catch.
I ran the two commands this issue proposes against a copy of the tree. Notes below; nothing changed in the repo.
The premise holds, but it understates the problem by half
The issue frames this as declared floors going unchecked. The larger fact is that most direct requirements declare no floor at all, and lowest-direct reads an absent floor as the first release ever published.
Counting [project.optional-dependencies] plus core: 18 distinct direct runtime requirements, 6 of which carry a floor (litestar, prometheus-fastapi-instrumentator, prometheus-client, opentelemetry-instrumentation-asgi, faststream, fastmcp). The other 12 are bare: typing-extensions, orjson, sentry-sdk, pyroscope-io, structlog, fastapi, opentelemetry-api, -sdk, -instrumentation, -exporter-otlp-proto-grpc, -exporter-otlp-proto-http, -instrumentation-fastapi.
So this is not a job that checks existing claims. It is a forcing function that requires ~12 new floors before it can go green. What --resolution lowest-direct resolves today:
extra
resolves to
core only
typing-extensions==3.6.2 (plus the typing PyPI backport)
The floored six behave exactly as this issue hopes. The unfloored twelve resolve to 2013.
The sharpest case is that a bare install does not import:
+ typing-extensions==3.6.2
ImportError: cannot import name 'GenericMeta' from 'typing'
at lite_bootstrap/instruments/base.py:4
typing_extensions.Self needs >=4.0; 4.0.0 imports clean. ADR-0007 documents that dependency as load-bearing and the floor it implies was never written down. That one is a real undeclared floor, not an artifact of the experiment.
uv lock --resolution lowest-direct cannot work here at all
The first command suggested above fails immediately:
hint: `pytest` (v2.0.0) was included because `lite-bootstrap:dev` depends on `pytest`
urllib.error.HTTPError: HTTP Error 403: SSL is required
uv lock always resolves every [dependency-groups] entry and has no --no-dev / --no-default-groups (uv 0.12.5). pytest at lowest-direct is 2.0.0, whose sdist shells out to a 2011 setuptools bootstrap URL that now 403s. The dev and lint groups would each need floors too; only redis>=5.2.1 has one. The per-extra uv pip install --resolution lowest-direct form is the only viable one, which matches what #211 did by hand.
All-extras would hide the failures the job exists to catch
This settles the second open question. lowest-direct floors direct dependencies and takes transitives at highest, so a floor declared in one extra propagates through the shared stack:
litestar-otl declares opentelemetry-instrumentation-asgi>=0.46b0, which drags opentelemetry-api to 1.25.0.
fastapi-otl declares nothing, so it gets opentelemetry-api==1.0.0, -instrumentation-fastapi==0.19b0, -instrumentation-asgi==0.19b0.
Same OpenTelemetryInstrument code, two effective floors 25 minor versions apart, decided by which extra the user installed. An all-extras run resolves the union and tests neither user's reality.
Same effect on core: fastapi alone yields typing-extensions==3.6.2, fastapi-all yields 4.10.0 (pulled up by the instrumentator's pydantic). Whether the library imports at all currently depends on which extra happens to rescue it.
Per-extra is blocked by conftest; per-framework is not
tests/conftest.py imports sentry_sdk, opentelemetry.instrumentation.instrumentor and structlog.typing at module level, so any pytest run needs sentry + otl + logging present. Per-extra suite runs would require restructuring collection. Per-framework over the five -all extras (free-all, fastapi-all, litestar-all, faststream-all, fastmcp-all) works as-is, maps one-to-one onto the five bootstrappers, and preserves the fastapi/litestar OTel divergence above.
The suite measures a stricter claim than the library's floor
The tests reach into internals of their own: faststream._internal.logger.params_storage.ManualLoggerStorage, sentry_sdk.envelope.Envelope, structlog.typing, starlette.testclient. A job that runs the suite pushes floors up to where the test helpers work, which can exceed the library's true minimum and over-constrain downstream services. Worth deciding deliberately: accept test-driven floors as the declared ones (simple, slightly conservative), or keep a narrower import-and-bootstrap smoke as the floor oracle.
The PR-gate objection, corrected
The scheduled-only option is justified above by "a transitive dependency's own bad floor". Under lowest-direct transitives resolve highest, so the real instability is the opposite: a brand-new upstream release landing next to an old direct pin (fastapi==0.1.0 beside starlette==1.6.0, opentelemetry-sdk==1.0.0 beside protobuf==7.36.1). Combinations no user will ever have, changing daily.
That is fixable rather than a reason to demote the job. uv pip compile --resolution lowest-direct works. Commit one resolved file per framework, install --frozen from it in the PR gate, and regenerate it in scheduled.yml so drift reports through the existing report-scheduled-failure.sh. The PR gate becomes hermetic, and the file changes only when a floor changes, which is exactly when a human should look.
Mechanically, _checks.yml is shared by ci.yml and scheduled.yml with workflow_call: {} and no inputs, so "gate PRs or only scheduled" is not expressible by dropping a job into it. It needs a workflow_call input, or the scheduled-only half lives in scheduled.yml.
Cheapest first step
install-isolation already loops 27 extras, builds a venv each, and asserts import lite_bootstrap. Running that loop a second time with --resolution lowest-direct catches "the declared floor does not import" for every extra, with no conftest restructuring, no test-suite floors and no new lockfile. It fails today on core alone, which is the honest starting state.
One adjacent gap
import_checker.py is presence-only (find_spec). A too-old-but-present dependency passes every guard and fails at attribute access inside bootstrap(), never as InstrumentDependencyMissingWarning. There is no runtime version check anywhere, so the declared floor is the only defence. That is why the revisit trigger above, a downstream bug report, is the one signal this design cannot generate for itself.
Suggested reshape
Split in two: one issue to establish and declare floors for the 12 bare requirements (plus the dev and lint groups, which the lock form needs), one for the CI job that holds them. In that order, since the job cannot go green before the floors exist.
Activity
feat: declare minimum compatible versions for fastmcp and faststream (#…
lesnik512 commentedon Sep 12, 2026
I ran the two commands this issue proposes against a copy of the tree. Notes below; nothing changed in the repo.
The premise holds, but it understates the problem by half
The issue frames this as declared floors going unchecked. The larger fact is that most direct requirements declare no floor at all, and
lowest-directreads an absent floor as the first release ever published.Counting
[project.optional-dependencies]plus core: 18 distinct direct runtime requirements, 6 of which carry a floor (litestar,prometheus-fastapi-instrumentator,prometheus-client,opentelemetry-instrumentation-asgi,faststream,fastmcp). The other 12 are bare:typing-extensions,orjson,sentry-sdk,pyroscope-io,structlog,fastapi,opentelemetry-api,-sdk,-instrumentation,-exporter-otlp-proto-grpc,-exporter-otlp-proto-http,-instrumentation-fastapi.So this is not a job that checks existing claims. It is a forcing function that requires ~12 new floors before it can go green. What
--resolution lowest-directresolves today:typing-extensions==3.6.2(plus thetypingPyPI backport)fastapifastapi==0.1.0,starlette==0.47.0loggingstructlog==0.1.0sentrysentry-sdk==0.1.0otlopentelemetry-{api,sdk}==1.0.0,-instrumentation==0.19b0,protobuf==7.36.1pyroscopepyroscope-io==0.3.0litestar/fastmcp/faststream/*-metricsThe floored six behave exactly as this issue hopes. The unfloored twelve resolve to 2013.
The sharpest case is that a bare install does not import:
typing_extensions.Selfneeds >=4.0; 4.0.0 imports clean. ADR-0007 documents that dependency as load-bearing and the floor it implies was never written down. That one is a real undeclared floor, not an artifact of the experiment.uv lock --resolution lowest-directcannot work here at allThe first command suggested above fails immediately:
uv lockalways resolves every[dependency-groups]entry and has no--no-dev/--no-default-groups(uv 0.12.5).pytestat lowest-direct is 2.0.0, whose sdist shells out to a 2011 setuptools bootstrap URL that now 403s. The dev and lint groups would each need floors too; onlyredis>=5.2.1has one. The per-extrauv pip install --resolution lowest-directform is the only viable one, which matches what #211 did by hand.All-extras would hide the failures the job exists to catch
This settles the second open question.
lowest-directfloors direct dependencies and takes transitives at highest, so a floor declared in one extra propagates through the shared stack:litestar-otldeclaresopentelemetry-instrumentation-asgi>=0.46b0, which dragsopentelemetry-apito 1.25.0.fastapi-otldeclares nothing, so it getsopentelemetry-api==1.0.0,-instrumentation-fastapi==0.19b0,-instrumentation-asgi==0.19b0.Same
OpenTelemetryInstrumentcode, two effective floors 25 minor versions apart, decided by which extra the user installed. An all-extras run resolves the union and tests neither user's reality.Same effect on core:
fastapialone yieldstyping-extensions==3.6.2,fastapi-allyields 4.10.0 (pulled up by the instrumentator's pydantic). Whether the library imports at all currently depends on which extra happens to rescue it.Per-extra is blocked by conftest; per-framework is not
tests/conftest.pyimportssentry_sdk,opentelemetry.instrumentation.instrumentorandstructlog.typingat module level, so any pytest run needs sentry + otl + logging present. Per-extra suite runs would require restructuring collection. Per-framework over the five-allextras (free-all,fastapi-all,litestar-all,faststream-all,fastmcp-all) works as-is, maps one-to-one onto the five bootstrappers, and preserves the fastapi/litestar OTel divergence above.The suite measures a stricter claim than the library's floor
The tests reach into internals of their own:
faststream._internal.logger.params_storage.ManualLoggerStorage,sentry_sdk.envelope.Envelope,structlog.typing,starlette.testclient. A job that runs the suite pushes floors up to where the test helpers work, which can exceed the library's true minimum and over-constrain downstream services. Worth deciding deliberately: accept test-driven floors as the declared ones (simple, slightly conservative), or keep a narrower import-and-bootstrap smoke as the floor oracle.The PR-gate objection, corrected
The scheduled-only option is justified above by "a transitive dependency's own bad floor". Under
lowest-directtransitives resolve highest, so the real instability is the opposite: a brand-new upstream release landing next to an old direct pin (fastapi==0.1.0besidestarlette==1.6.0,opentelemetry-sdk==1.0.0besideprotobuf==7.36.1). Combinations no user will ever have, changing daily.That is fixable rather than a reason to demote the job.
uv pip compile --resolution lowest-directworks. Commit one resolved file per framework, install--frozenfrom it in the PR gate, and regenerate it inscheduled.ymlso drift reports through the existingreport-scheduled-failure.sh. The PR gate becomes hermetic, and the file changes only when a floor changes, which is exactly when a human should look.Mechanically,
_checks.ymlis shared byci.ymlandscheduled.ymlwithworkflow_call: {}and no inputs, so "gate PRs or only scheduled" is not expressible by dropping a job into it. It needs aworkflow_callinput, or the scheduled-only half lives inscheduled.yml.Cheapest first step
install-isolationalready loops 27 extras, builds a venv each, and assertsimport lite_bootstrap. Running that loop a second time with--resolution lowest-directcatches "the declared floor does not import" for every extra, with no conftest restructuring, no test-suite floors and no new lockfile. It fails today on core alone, which is the honest starting state.One adjacent gap
import_checker.pyis presence-only (find_spec). A too-old-but-present dependency passes every guard and fails at attribute access insidebootstrap(), never asInstrumentDependencyMissingWarning. There is no runtime version check anywhere, so the declared floor is the only defence. That is why the revisit trigger above, a downstream bug report, is the one signal this design cannot generate for itself.Suggested reshape
Split in two: one issue to establish and declare floors for the 12 bare requirements (plus the dev and lint groups, which the lock form needs), one for the CI job that holds them. In that order, since the job cannot go green before the floors exist.