Release sfdctrust 1.0.0#

#12 owns release progress, approvals and final evidence. Preparation does not authorize publication. Keep the tracker open until the maintainer explicitly approves closure. The proposed changelog date is 2026-11-15, America/Denver; review it before merging if the release date changes. Do not select a next development version during this release.

Source, validation and frozen artifacts#

The previous reachable stable tag is 0.2.0; the intended annotated tag is 1.0.0, without a v prefix. The distribution and import name are sfdctrust. Python remains >=3.12, advertising 3.12–3.15. Preserve #10’s accepted policy, fixed phase timeouts, single-host SQLite boundary and retired legacy migration. Runtime requirements remain HTTPX >=0.28.1,<1.0.0 and Pydantic ==2.14.3.

Leave preparation edits uncommitted for review. Commits, pushes, PR creation and merge require separate authorization. After review/merge, require a clean main checkout equal to remote main. Record the full final commit SHA; the preparation branch’s base SHA plus dirty files is not a release source identity.

Follow Validate CI and prepare publishing for lock validation, offline tests, Ruff, Bandit, online locked-runtime auditing, strict Sphinx, strict Twine, artifact inspection, separate non-editable wheel/sdist checks and downstream typing. Also run the python-stable-release skill’s artifact inspector and Actionlint on both workflows. Keep retrieval/advisory requests separate from outbound-blocked behavior checks. Never inspect credentials or contact Salesforce during preparation.

Require exact-final-commit hosted SDK validation: policy, audit, packaging/docs, public compatibility/typing, Linux 3.12/3.13/3.14/3.15 and macOS/Windows 3.12. Verify native SQLite permissions and spawned-process steps, actual skips and all job conclusions. Historical #9/#10/#11 evidence supports their completed gates; it does not qualify new stable artifacts. Verify Read the Docs separately.

Build and inspect again from the clean final main commit. Preserve these local artifacts as comparison evidence, with their source SHA, sizes and digests. Then prepare the following validation-only dispatch; obtain dispatch approval before execution. release_sha must be the verified final main SHA, not a base commit, placeholder, PR head or merge preview.

release_sha='REPLACE_WITH_VERIFIED_FINAL_MAIN_40_CHARACTER_SHA'
test "$(git rev-parse HEAD)" = "$release_sha"
test "$(git rev-parse origin/main)" = "$release_sha"
test -z "$(git status --porcelain --untracked-files=all)"
poetry check --lock --strict
poetry run python tools/ci/artifacts.py source --destination validate \
  --sha "$release_sha" --version 1.0.0 --ref refs/heads/main
# Only after explicit dispatch authorization:
gh workflow run release.yml --repo jeffshurtliff/sfdctrust --ref main \
  -f destination=validate -f source_sha="$release_sha" -f version=1.0.0 -f upload=false

Record the returned run’s URL/ID, attempt, head SHA and inputs. Download its approved-release artifact to a fresh permanent release-evidence directory:

release_run='REPLACE_WITH_SUCCESSFUL_VALIDATION_RUN_ID'
release_bundle='/absolute/path/to/new/frozen-1.0.0-bundle'
gh run download "$release_run" --repo jeffshurtliff/sfdctrust \
  --name approved-release --dir "$release_bundle"
poetry run python tools/ci/artifacts.py transfer --dist "$release_bundle/dist" \
  --manifest "$release_bundle/evidence/release-manifest.json"

Independently inspect the bundle manifest’s version, clean source state, exact SHA, two filenames, sizes and hashes. Reconcile it with the final local build; investigate any mismatch. Freeze and retain the reviewed hosted wheel, sdist, evidence/SHA256SUMS, manifest and qualification evidence beyond GitHub’s 30-day artifact retention. Record both file identities in #12. No subsequent build implicitly replaces this frozen set.

Exact-wheel qualification owned by #8#

#8 requires both live phases on the frozen stable wheel. Ask separately before updating that issue. Prior 0.2.0 results and the distinct TestPyPI rehearsal are not stable qualification. The maintainer supplies credentials privately and runs the live commands.

Install the frozen wheel without rebuilding it. The following setup is offline after retrieving active locked dependencies with tools/ci/qualify.py prepare. Set release_wheels to that reviewed wheelhouse. Its constraints pin active runtime dependencies; this setup never retrieves or discovers Salesforce secrets.

qual_repo="$(pwd -P)"
qual_wheel="$release_bundle/dist/sfdctrust-1.0.0-py3-none-any.whl"
release_wheels='/absolute/path/to/reviewed/locked-wheelhouse'
qual_dir="$(mktemp -d "${TMPDIR:-/tmp}/sfdctrust-1.0.0-live.XXXXXX")"
python3.12 -m venv "$qual_dir/venv"
qual_py="$qual_dir/venv/bin/python"
"$qual_py" -I -m pip install --no-cache-dir --no-index --find-links "$release_wheels" \
  --constraint "$release_wheels/locked-active.txt" "$qual_wheel"
"$qual_py" -I -m pip check
"$qual_py" -I - "$qual_wheel" "$release_bundle/evidence/release-manifest.json" <<'PY'
from datetime import datetime, UTC
from hashlib import sha256
from importlib.metadata import version
import json
from pathlib import Path
import platform
import sys
import sysconfig
import sfdctrust

wheel = Path(sys.argv[1])
manifest = json.loads(Path(sys.argv[2]).read_text())
record = manifest['files'][wheel.name]
assert manifest['version'] == version('sfdctrust') == sfdctrust.__version__ == '1.0.0'
assert manifest['source_status'] == ''
assert wheel.stat().st_size == record['size']
assert sha256(wheel.read_bytes()).hexdigest() == record['sha256']
assert Path(sfdctrust.__file__).resolve().is_relative_to(Path(sysconfig.get_path('purelib')).resolve())
print('Source', manifest['source_commit'], 'Wheel', wheel.name)
print('Bytes', record['size'], 'SHA-256', record['sha256'])
print('SDK', version('sfdctrust'), 'Import', sfdctrust.__file__)
print('Python', platform.python_version(), 'Platform', platform.system(), platform.machine())
print('UTC', datetime.now(UTC).isoformat())
PY
"$qual_py" -I "$qual_repo/tests/offline/run.py" "$qual_repo/tests/package_smoke.py"

Phase A, only after separate read-only authorization: run the hidden-prompt command from Qualify an installed wheel against My Trust Center in this environment:

(cd "$qual_dir" && "$qual_py" -I "$qual_repo/tests/live_read_smoke.py" --live)

It checks both clients’ five reads, continuation where available, status grouping, event/tenant scope, history and timelines. Record each outcome and explicit maintainer dispositions for data-dependent skips; exit 0 alone is insufficient.

Phase B, only after separate rotation authorization: follow the exact seed, one-refresh, persistence, replacement-read, old-PAT-401 and fresh-process-reopen commands in Qualify one deliberate PAT rotation, using the same qual_py and a new private store for a dedicated non-production lineage. Quiesce other users of the lineage. Never blindly retry an ambiguous refresh; keep the original process alive for persistence-only recovery when required.

Record only sanitized results, exact wheel/hash, source SHA, SDK/Python/platform, date, phase authorizations and skip dispositions. Link accepted #8 evidence into #12. Any artifact-affecting source change requires a new manifest and an explicit requalification decision.

Production setup, tag and draft#

Read-only inspection on 2026-11-15 found main unprotected, no rulesets, and only the testpypi environment. A protected production pypi environment is required before any production upload dispatch. Propose required maintainer reviewers, prevent self-review and disable administrator bypass; restrict deployments to the approved tag 1.0.0, excluding branches. If unavailable under the repository plan or solo-maintainer arrangement, stop for an explicit production alternative. Do not inherit the rehearsal’s self-approval exception.

The separate PyPI Trusted Publisher must bind owner jeffshurtliff, repository sfdctrust, workflow release.yml, environment pypi. Verify it in the project’s PyPI publishing settings; the public package API cannot establish current private publisher settings. Review public per-file attestation/transparency publication. Settings changes and publisher registration each need approval. Use GitHub OIDC.

Prepare an annotated 1.0.0 tag on the verified final main SHA. Creating the local tag, pushing that tag, and creating a draft GitHub Release each require separate authorization. Recheck tag/version availability before these actions. Prepare reviewed notes without MyST labels and attach exactly the frozen wheel, sdist and SHA256SUMS. Verify draft=true, prerelease=false and the tag’s peeled target SHA. Never let release creation implicitly create a tag or substitute a branch head.

Prepare these commands for individual approvals; execute only the specifically authorized step. release_notes is the reviewed local Markdown notes file.

# Separate authorization: create local tag.
git tag -a 1.0.0 "$release_sha" -m 'sfdctrust 1.0.0'
test "$(git rev-parse '1.0.0^{commit}')" = "$release_sha"
# Separate authorization: push that tag.
git push origin refs/tags/1.0.0
# Separate authorization: create a draft, after verifying the remote tag.
release_notes='/absolute/path/to/reviewed/RELEASE_NOTES.md'
gh release create 1.0.0 --repo jeffshurtliff/sfdctrust --verify-tag --draft \
  --title 'sfdctrust 1.0.0' --notes-file "$release_notes" \
  "$release_bundle/dist/sfdctrust-1.0.0-py3-none-any.whl" \
  "$release_bundle/dist/sfdctrust-1.0.0.tar.gz" "$release_bundle/evidence/SHA256SUMS"

Maintainer-executed upload and mandatory hash comparison#

Only after the preceding gates and dispatch authorization, the maintainer runs:

gh workflow run release.yml --repo jeffshurtliff/sfdctrust --ref 1.0.0 \
  -f destination=pypi -f source_sha="$release_sha" -f version=1.0.0 -f upload=true

This new run rebuilds during validation/build. Its protected publishing job downloads the same-run immutable artifact ID, rechecks its bytes and uploads without rebuilding. Before environment approval, download that new run’s approved-release bundle into a different directory. Verify its run/ref/source and all gates, then compare both files against the frozen #8-qualified set:

upload_bundle='/absolute/path/to/new/upload-run-bundle'
poetry run python tools/ci/artifacts.py transfer --dist "$upload_bundle/dist" \
  --manifest "$release_bundle/evidence/release-manifest.json"
poetry run python - "$release_bundle" "$upload_bundle" <<'PY'
import json
from pathlib import Path
import sys
frozen, upload = [json.loads((Path(p) / 'evidence/release-manifest.json').read_text()) for p in sys.argv[1:]]
for key in ('version', 'source_commit', 'source_status', 'files'):
    assert frozen[key] == upload[key], f'Mismatch: {key}'
assert upload['version'] == '1.0.0' and upload['source_status'] == ''
print('PASS both artifact identities match the frozen manifest')
PY

Stop on either mismatch. Investigate source/tool/build differences and obtain an explicit requalification decision; successful CI does not qualify new live bytes. Only after a successful comparison may the maintainer separately approve the protected deployment for that exact run. This guide does not grant approval.

Verify production and finish#

After the maintainer’s upload, inspect the exact run and its registry-verification artifact. For independent read-only reproduction from the final source, using a fresh upload bundle without an existing evidence/registry directory:

upload_run='REPLACE_WITH_APPROVED_PRODUCTION_RUN_ID'
poetry run python tools/ci/registry.py --destination pypi --bundle "$upload_bundle" \
  --ref refs/tags/1.0.0 --run-id "$upload_run"

This compares both hosted names/sizes/hashes, downloads the hosted bytes, verifies per-file signatures/transparency and repository/workflow/environment/ref/SHA/run claims, then separately installs the hosted wheel and sdist with offline smoke, compatibility and typing checks. Review the retained release.json metadata too: version, Python requirement/classifiers, MIT license/file, Markdown description, runtime requirements and all project URLs must match the approved source. Check description rendering on PyPI. Require exact-source successful Read the Docs build evidence and served stable version 1.0.0; local Sphinx or an older latest page is insufficient. Obtain approval for any documentation settings change.

Only after production verification and separate explicit approval, publish the existing GitHub draft and mark it latest. Verify peeled tag/source, reviewed notes, three asset bytes/digests, stable status and latest designation. Record final evidence in #12, then request explicit closure approval when every acceptance criterion is supported.

# Only after PyPI verification and separate publish/latest authorization:
gh release edit 1.0.0 --repo jeffshurtliff/sfdctrust --draft=false --prerelease=false --latest

For partial uploads, preserve the run and bytes and inspect exact-version JSON, logs and each file’s provenance before retrying anything. If no file exists, seek approval to retry only the protected upload job with its retained same-run artifact. If a matching subset exists, prepare separately approved recovery of only missing original files. Never rebuild an accepted filename, move a public tag, reuse a published version, or use --skip-existing. A verification failure does not prove upload failed. For a bad production release, seek approval for a yank and corrected version. See Validate CI and prepare publishing for the full recovery procedure; withholding approval halts an unstarted deployment.