Qualify the public compatibility baseline#
The Public compatibility for the 1.x series policy defines the 1.x public surface.
This gate compares the latest published pre-1.0 wheel (0.2.0 at this handoff)
with a locally built candidate, without editable installs, real credentials,
or Salesforce requests. It complements the existing offline suite rather than
reimplementing every behavior test.
Live-service qualification remains owned by
issue #8.
Operator recovery is complete under
issue #9’s closing evidence,
including successful macOS/Windows/Ubuntu hosted rehearsals at
3b7438ecf9f0ad8c9c922982c8afe1d101b55fbc. Do not rerun those gates to satisfy
issue #10. The upgrade check here only reopens baseline-created ready/pending
stores and verifies public compare-and-swap protection; it performs no refresh
or operator recovery rehearsal.
Preparation and isolated installations#
Run from the repository root with Python 3.12 (the inventory/checker interpreter) and the locked development tools.
Choose a fresh work directory for each run. The commands below are the local
POSIX commands used for this qualification. On Windows, use each venv’s
Scripts/python.exe instead of bin/python. The new compatibility job uses
Ubuntu/Python 3.12; the existing matrix continues to validate native storage
and the rest of the SDK on all configured runners.
Package retrieval is an explicit network-enabled preparation step. Record the
release source, versions and hashes; the published wheel is not rebuilt from
a tag. Keep dependency versions equivalent between the two environments for
this comparison. Retain pip freeze outputs with evidence if the resolver
selects different dependency versions on another date.
git branch --show-current
git rev-parse HEAD
git status --short --branch
poetry check --lock --strict
poetry install --with docs
poetry build
mkdir -p /private/tmp/sfdctrust-compat/wheels
poetry run python -m pip download --only-binary=:all: \
--dest /private/tmp/sfdctrust-compat/wheels 'sfdctrust==0.2.0' 'mypy==1.20.2'
poetry run python -m venv /private/tmp/sfdctrust-compat/baseline
poetry run python -m venv /private/tmp/sfdctrust-compat/candidate
/private/tmp/sfdctrust-compat/baseline/bin/python -I -m pip install --no-index \
--find-links /private/tmp/sfdctrust-compat/wheels \
/private/tmp/sfdctrust-compat/wheels/sfdctrust-0.2.0-py3-none-any.whl 'mypy==1.20.2'
/private/tmp/sfdctrust-compat/candidate/bin/python -I -m pip install --no-index \
--find-links /private/tmp/sfdctrust-compat/wheels \
dist/sfdctrust-1.0.0-py3-none-any.whl 'mypy==1.20.2'
/private/tmp/sfdctrust-compat/baseline/bin/python -I -m pip check
/private/tmp/sfdctrust-compat/candidate/bin/python -I -m pip check
/private/tmp/sfdctrust-compat/baseline/bin/python -I -m pip freeze
/private/tmp/sfdctrust-compat/candidate/bin/python -I -m pip freeze
Mypy is the single checker and a development dependency only. CI obtains its
version from the Poetry lock installation and installs that version in the
candidate venv. It is not included in runtime metadata. The strict fixture
imports only public paths, checks model/results, both clients, lazy async
iteration, and structural conformance of custom sync/async PAT stores. It is
checked, never executed. No MYPYPATH, missing-import suppression, SDK stubs,
Pydantic plugin, editable installation, or skipped SDK imports are used. The
checker discovers the installed PEP 561 package in its own interpreter, per
mypy’s installed-package guidance.
Assertions of inferred types prevent an Any return from disguising a broken
public annotation. This does not claim that all SDK internals pass strict mypy.
Behavioral comparison and store upgrade#
Each invocation below requires -I, rejects optimized execution and editable
imports, verifies package bytes against its specified wheel, and confirms the
shipped py.typed marker. A socket/DNS audit guard is installed before importing
the SDK or executing behavior. The event loop is initialized first because
Windows may need a socket pair for its internal wakeup mechanism. Qualification
cannot open any sockets after that point. The two deliberate guard self-tests
are counted separately; any other socket/DNS attempt fails qualification.
The checked inventory contains supported exports, method parameter kinds,
keyword-only defaults, return types, call/await invocation, model fields/aliases,
exception inheritance and probe values. It normalizes the private environment
omission sentinel and the equivalent builtins.list spelling. It does not
freeze an incidental import or the version string. No module search path is
added by the harness. Its CLI test executes the real installed module inside
the same guarded interpreter with an explicitly named synthetic environment
variable; it does not discover credentials.
/private/tmp/sfdctrust-compat/baseline/bin/python -I tests/compatibility/check_wheel.py \
--wheel /private/tmp/sfdctrust-compat/wheels/sfdctrust-0.2.0-py3-none-any.whl \
--expected-version 0.2.0 --snapshot tests/compatibility/public-api.json \
--evidence /private/tmp/sfdctrust-compat/baseline.json
/private/tmp/sfdctrust-compat/candidate/bin/python -I tests/compatibility/check_wheel.py \
--wheel dist/sfdctrust-1.0.0-py3-none-any.whl \
--expected-version 1.0.0 --snapshot tests/compatibility/public-api.json \
--evidence /private/tmp/sfdctrust-compat/candidate.json
/private/tmp/sfdctrust-compat/baseline/bin/python -I tests/compatibility/check_wheel.py \
--wheel /private/tmp/sfdctrust-compat/wheels/sfdctrust-0.2.0-py3-none-any.whl \
--expected-version 0.2.0 --snapshot tests/compatibility/public-api.json \
--mode seed --store-directory /private/tmp/sfdctrust-compat/stores-final \
--evidence /private/tmp/sfdctrust-compat/seed.json
/private/tmp/sfdctrust-compat/candidate/bin/python -I tests/compatibility/check_wheel.py \
--wheel dist/sfdctrust-1.0.0-py3-none-any.whl \
--expected-version 1.0.0 --snapshot tests/compatibility/public-api.json \
--mode upgrade --store-directory /private/tmp/sfdctrust-compat/stores-final \
--evidence /private/tmp/sfdctrust-compat/upgrade.json
The first baseline inventory was recorded with the explicit developer option
--record-inventory, then reviewed. Normal qualification and CI never use that
option. Do not regenerate the snapshot merely to make a break pass. When future
approved additions cause the baseline and candidate surfaces to diverge, retain
the historical baseline snapshot separately and review candidate changes under
the versioning policy; do not demand that old wheels implement new additions.
The current versions share the same normalized inventory.
Both wheels exercise all five reads in sync/async form, serialization/aliases, omission/null rules, offsets, unknown values, status duplicates and scopes, lazy iteration, continuation and partial failure, HTTP errors versus pagination guards, connection ownership, timeout overrides, bounded retries, cancellation and installed CLI initialization. Detailed read/search/pagination, retries, exception sanitization, async refresh/cancellation and SQLite unsupported-format cases remain in the existing unit suite.
Downstream typing and other checks#
/private/tmp/sfdctrust-compat/baseline/bin/python -I -m mypy --version
/private/tmp/sfdctrust-compat/baseline/bin/python -I -m mypy \
--config-file tests/compatibility/mypy.ini --no-incremental tests/compatibility/downstream.py
/private/tmp/sfdctrust-compat/candidate/bin/python -I -m mypy --version
/private/tmp/sfdctrust-compat/candidate/bin/python -I -m mypy \
--config-file tests/compatibility/mypy.ini --no-incremental tests/compatibility/downstream.py
poetry run pytest -q
poetry run ruff check .
poetry run ruff format --check .
poetry run bandit -r src -q
poetry check --lock --strict
poetry build
poetry run twine check --strict dist/sfdctrust-1.0.0*
poetry run sphinx-build -W --keep-going -E -a -b html docs docs/_build/html
The baseline mypy command intentionally exits 1 with exactly two
assert-type diagnostics: sync and async tenants.list_all() resolve to
list?[Tenant] because the method list shadows the built-in annotation name.
Run it separately from shell sequences that stop on the first failure. The
candidate qualifies builtins.list[Tenant] and must exit 0 with no errors.
This is a typing correction, not a runtime incompatibility or migration.
CI enforces the candidate’s success; the published baseline’s known typing
failure is recorded here and in local evidence, not required to pass.
Local results and closure boundaries#
Qualification date: 2026-11-11 America/Denver (UTC timestamps fall on
2026-11-12). Initial source: clean main at
3b7438ecf9f0ad8c9c922982c8afe1d101b55fbc, package 1.0.0.dev0.
All changes remain uncommitted. See the
sanitized evidence for wheel
and harness hashes, installed paths, Python/platform, dependencies, checker
version, source state and outcomes.
Gate |
Local outcome |
|---|---|
Published 0.2.0 vs candidate normalized public inventory |
Equal |
Non-editable installations and wheel byte identity |
Passed in separate clean venvs |
|
Passed for both |
Offline sync/async behavior, CLI, serialization and pagination/errors |
Passed for both; zero unexpected network attempts |
Reopen baseline-created ready and pending SQLite stores |
Passed; revisions/markers retained and stale CAS refused |
Strict downstream mypy 1.20.2 |
Baseline: two known annotation diagnostics; candidate: passed |
Existing offline suite |
605 passed, 15 platform-specific skips on macOS/Python 3.12.7 |
Ruff lint and format, Bandit, Poetry lock, wheel/sdist build, packaging contents, strict Twine and Sphinx |
Passed |
The maintainer approved deferring public phase-timeout configuration on 2026-11-11. No intentional runtime incompatibility was found; no version bump, new runtime dependency or storage migration was introduced. No real credentials were read, no Salesforce call was made, and GitHub was not modified.
Before issue #10 can close, the maintainer must approve the inventory/versioning and upgrade policy and review the typing correction, and the updated workflow must pass in hosted CI. The local machine does not verify the new Ubuntu job or a new Windows run. Prior issue #9 hosted evidence covers that recovery gate only. Qualification of the exact stable release artifact and live service stays with the release process/#8. Nothing here claims those remaining gates passed.