**u Chart** is a control chart for monitoring defects per unit when inspection unit size varies between samples, normalizing counts to a standard basis.
## What Is a u Chart?
- **Metric**: Defects per unit (u = c/n where c=defects, n=units inspected)
- **Flexibility**: Handles variable sample sizes
- **Distribution**: Based on Poisson (defect counts)
- **Control Limits**: Vary with sample size for each point
## Why u Charts Matter
Production often involves variable lot sizes. The u chart normalizes defect rates, enabling fair comparison across different sample sizes.
```
u Chart Example (Defects per wafer):
Sample 1: 15 defects in 5 wafers → u₁ = 3.0
Sample 2: 24 defects in 10 wafers → u₂ = 2.4
Sample 3: 8 defects in 4 wafers → u₃ = 2.0
Overall: ū = (15+24+8)/(5+10+4) = 47/19 = 2.47
Control limits for sample i with nᵢ units:
UCLᵢ = ū + 3√(ū/nᵢ)
LCLᵢ = ū - 3√(ū/nᵢ)
```
**u vs. c Chart Selection**:
| Scenario | Chart |
|----------|-------|
| Fixed inspection quantity | c chart |
| Variable inspection quantity | u chart |
| Count defective items | np or p chart |
**U-Net denoiser** is the **core diffusion network that predicts noise or residual signals at each timestep to iteratively clean latent representations** - it is the primary quality and compute driver in most diffusion pipelines.
**What Is U-Net denoiser?**
- **Definition**: Encoder-decoder architecture with skip connections that preserves multiscale information.
- **Conditioning Inputs**: Consumes timestep embeddings and optional text or control features.
- **Attention Blocks**: Self-attention and cross-attention layers improve global coherence and prompt alignment.
- **Prediction Modes**: Can output epsilon, x0, or velocity depending on training formulation.
**Why U-Net denoiser Matters**
- **Quality Control**: Denoiser capacity strongly determines texture realism and compositional accuracy.
- **Compute Footprint**: Most inference latency and memory use come from repeated U-Net evaluations.
- **Adaptation Power**: Fine-tuning the denoiser enables domain-specific or style-specific generation.
- **Reliability**: Architecture and normalization choices affect stability under high guidance settings.
- **Optimization Priority**: Kernel-level and attention optimizations here produce major speed gains.
**How It Is Used in Practice**
- **Efficiency**: Use optimized attention kernels, mixed precision, and memory-aware batch strategies.
- **Training Stability**: Maintain EMA checkpoints and robust augmentation to reduce drift.
- **Regression Coverage**: Test prompt adherence, artifact rates, and latency after any denoiser changes.
U-Net denoiser is **the central model component in diffusion generation quality** - U-Net denoiser improvements usually yield the largest end-to-end gains in diffusion systems.
**U-Shaped Cell** is **a cell layout where process stations are arranged in a U pattern to improve flow and operator flexibility** - It reduces movement distance and supports multi-process staffing.
**What Is U-Shaped Cell?**
- **Definition**: a cell layout where process stations are arranged in a U pattern to improve flow and operator flexibility.
- **Core Mechanism**: The layout enables one operator to monitor and support multiple adjacent steps efficiently.
- **Operational Scope**: It is applied in manufacturing-operations workflows to improve flow efficiency, waste reduction, and long-term performance outcomes.
- **Failure Modes**: Improper station spacing can create ergonomic strain and uneven workload.
**Why U-Shaped Cell Matters**
- **Outcome Quality**: Better methods improve decision reliability, efficiency, and measurable impact.
- **Risk Management**: Structured controls reduce instability, bias loops, and hidden failure modes.
- **Operational Efficiency**: Well-calibrated methods lower rework and accelerate learning cycles.
- **Strategic Alignment**: Clear metrics connect technical actions to business and sustainability goals.
- **Scalable Deployment**: Robust approaches transfer effectively across domains and operating conditions.
**How It Is Used in Practice**
- **Method Selection**: Choose approaches by bottleneck impact, implementation effort, and throughput gains.
- **Calibration**: Optimize station sequence and reach zones using time-motion and safety analysis.
- **Validation**: Track throughput, WIP, cycle time, lead time, and objective metrics through recurring controlled evaluations.
U-Shaped Cell is **a high-impact method for resilient manufacturing-operations execution** - It is a practical cell pattern for compact, responsive operations.
**Ubuntu 26.04 LTS Python Setup Step 1 is to turn a fresh Resolute Raccoon installation into a verified, supportable Python 3.14 development base without replacing Ubuntu’s system interpreter.** Confirm the installed release and environment, validate signed Resolute repositories, apply reviewed updates, install Ubuntu’s complete Python/venv/pip prerequisites through APT, and prove package ownership before any project dependencies are introduced.
Ubuntu 26.04 LTS was released on April 23, 2026. Its LTS-user release summary says the default Python moved from 3.12 to 3.14. Those are release facts, not proof of this customer’s machine: every acceptance command below reads actual local release, package, executable and version state.
| Surface | 26.04 decision | Machine evidence |
|---|---|---|
| release | Resolute 26.04 LTS | `/etc/os-release` |
| environment | native, VM, WSL or container known | virtualization/kernel checks |
| repositories | signed Resolute sources | deb822/APT output |
| updates | reviewed current package state | apt and dpkg audit |
| default Python | Ubuntu `python3` (expected 3.14) | version/executable/dpkg owner |
| development base | full runtime, venv and pip | APT package status |
| system boundary | APT owns `/usr/bin/python3` | no global pip/repointing |
| handoff | user-owned project venv next | prefix/venv readiness |
## Verify this is really Ubuntu 26.04 LTS
Run as the normal user:
```bash
whoami
id
cat /etc/os-release
lsb_release -a 2>/dev/null || true
uname -a
dpkg --print-architecture
```
Expected release facts include `VERSION_ID="26.04"` and codename `resolute`. Do not proceed under a different release while labeling evidence 26.04. The user must not be root; normal development needs sudo only for APT/system administration.
If `lsb_release` is absent, `/etc/os-release` remains the portable source. Do not install extra packages just to reproduce a cosmetic command.
## Identify the installation environment
The client said “installed Ubuntu 26.04 LTS,” which could mean physical hardware, a VM, dual boot, cloud, container or WSL image. Detect rather than assume:
```bash
systemd-detect-virt 2>/dev/null || true
grep -i microsoft /proc/sys/kernel/osrelease 2>/dev/null || true
findmnt -T "$HOME"
```
An output such as `wsl`/Microsoft identifies WSL; KVM/VMware/Hyper-V indicates virtualization; `none` can indicate native hardware. Python package ownership is the same APT-versus-venv principle, but restart, filesystem, networking and GUI behavior differ by environment.
On WSL, keep Linux projects under `/home`, not `/mnt/c`. On native Ubuntu, use the Linux home filesystem and normal backup policy. Do not move virtual environments across these targets.
## Confirm LTS and support posture
Inspect Ubuntu Pro/support status without attaching a token:
```bash
pro status 2>/dev/null || true
```
LTS status does not mean every third-party repository/package receives Canonical security maintenance. Record which archive components and organizational services are approved. Do not attach a personal Pro token to a customer system without authorization.
No release upgrade is required: the customer is already on 26.04. Do not run `do-release-upgrade`, enable development releases, or change the release prompt in this setup.
## Inspect Resolute APT sources
Ubuntu 26.04 normally uses deb822 source definitions. List and review:
```bash
find /etc/apt/sources.list /etc/apt/sources.list.d -maxdepth 1 -type f -print 2>/dev/null
grep -RhsE '^(Types:|URIs:|Suites:|Components:|Signed-By:|deb )' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null
```
Official source suites should correspond to `resolute`, updates, security and optional backports as configured. `Signed-By` should reference the Ubuntu archive keyring for official archives.
Do not copy Noble/24.04 or interim-release source lines into Resolute. Mixing release suites can create an unsupported dependency graph. Do not add PPAs, vendor repositories, unsigned keys, HTTP mirrors or `[trusted=yes]` merely to install Python.
On enterprise networks, use the approved mirror/proxy/CA process. Never embed credentials in source URLs, shell history or screenshots.
## Update the fresh installation
Refresh metadata:
```bash
sudo apt update
```
Read every warning. DNS, TLS, signature, time, suite or mirror failures must be resolved before installation.
Review available changes:
```bash
apt list --upgradable
```
Apply normal upgrades interactively:
```bash
sudo apt upgrade
```
The guide omits `-y` so the customer reviews additions/removals/download size/config prompts. Packages kept back may be phased; do not disable phasing or force them for cosmetic “zero updates.”
Audit package state:
```bash
sudo dpkg --audit
apt-mark showhold
test -f /run/reboot-required && cat /run/reboot-required || true
```
An empty dpkg audit is expected. Held packages need an owner/reason. If restart is required, use the correct procedure for native Ubuntu versus VM/WSL; preserve other users/workloads and verify afterward.
## Inspect Python before installing anything
Run:
```bash
command -v python3
type -a python3
readlink -f "$(command -v python3)"
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.version)"
```
Ubuntu 26.04 is expected to report Python 3.14 through `/usr/bin/python3`, but trust the output. Every `python3 -c` example is a complete physical line.
The bare `python` command may be absent. This is not a defect and does not justify custom aliases/symlinks. Use `python3` for the base; a project venv normally exposes `python` itself.
## Prove dpkg ownership and versions
Run:
```bash
dpkg -S "$(readlink -f "$(command -v python3)")"
apt-cache policy python3 python3.14 python3-full python3-venv python3-pip python3-pip-whl
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' python3 python3-minimal 2>/dev/null
```
The versioned binary can be owned by a versioned package while `/usr/bin/python3` is managed by Ubuntu’s default-Python package/link. Do not edit the link or use `update-alternatives` to substitute another version; system tools are tested against the distribution default.
## Install the supported developer base
Canonical’s current developer guide recommends `python3-full` for a complete runtime with venv support. Install the full runtime and pip/wheel seed through APT:
```bash
sudo apt install python3-full python3-pip python3-pip-whl
```
Review the package plan. Ubuntu package search shows `python3-pip` and `python3-pip-whl` for Resolute. Exact package versions can receive updates; do not copy a static version number from an article.
For a deliberately minimal server image, the smaller alternative is:
```bash
sudo apt install python3 python3-venv python3-pip
```
Choose one documented baseline. Do not blindly run both or install editors/compilers/scientific stacks without project need. `python3-full` may include components unnecessary on a headless host but gives the broad recommended development runtime.
## Verify Python 3.14 readiness
Run after installation:
```bash
python3 --version
python3 -c "import sys; print(sys.executable); print(sys.version_info)"
python3 -m venv --help
python3 -m pip --version
python3 -c "import sys; print(sys.prefix); print(sys.base_prefix)"
```
At the system base, prefix and base-prefix normally match. `python3 -m venv --help` proves the environment module is available; it does not create or alter a project.
Inspect Ubuntu-installed locations:
```bash
python3 -c "import site; print(site.getsitepackages()); print(site.getusersitepackages())"
dpkg -l 'python3*' | sed -n '1,120p'
```
The package listing can be large. Use it as local evidence, not a list to reinstall/purge.
## Respect the externally managed environment
Ubuntu protects its system Python from pip modifications. Project dependencies must go into a virtual environment.
Never use:
```text
sudo pip install PACKAGE
python3 -m pip install --user PACKAGE
python3 -m pip install --break-system-packages PACKAGE
```
The override’s name is literal: it breaks the package-manager boundary. It can shadow/overwrite APT files used by Ubuntu tools. Do not “test” the protection by attempting an install on a customer machine.
APT owns distribution/system packages; venv pip owns one project’s Python distributions; pipx may later isolate standalone Python applications. These are distinct lifecycles.
## Python 3.14 compatibility boundary
Python 3.14 is newer than the 3.12 base familiar from Ubuntu 24.04. Projects and binary-extension dependencies must explicitly support it. Before migrating existing code, verify declared Python requirements, wheel availability, C-extension/toolchain support, tests and CI.
Do not downgrade or replace Ubuntu’s default Python to satisfy an old project. Instead, use an approved separate-version manager/runtime or container, with the project interpreter explicitly selected and the system Python untouched.
Do not assume a package supports 3.14 because it is pure Python or installs from source. Check upstream metadata/releases and test the full workload.
## Standard-library smoke test
Run without network/customer data:
```bash
python3 -c "import asyncio, json, pathlib, sqlite3, ssl, tomllib; print('stdlib-ok')"
python3 -c "from pathlib import Path; print(Path.home())"
python3 -c "import sysconfig; print(sysconfig.get_platform())"
```
The home should match the normal user. The platform string records architecture/ABI context for future wheels; it is not a substitute for pip’s compatible-tag diagnostics.
## UTF-8, time and TLS prerequisites
Run:
```bash
locale
date --iso-8601=seconds
python3 -c "import locale, sys; print(sys.getfilesystemencoding()); print(locale.getpreferredencoding(False))"
python3 -c "import ssl; print(ssl.get_default_verify_paths())"
```
Modern Ubuntu should use UTF-8. Correct time/CA trust matter for signed/TLS package downloads. Do not rewrite global locale or disable certificate verification as a Python fix.
## Prepare only the project parent
Run as normal user:
```bash
mkdir -p ~/projects
stat -c 'owner=%U group=%G mode=%A path=%n' ~/projects
findmnt -T ~/projects
df -h ~/projects
```
Do not create project files with sudo. On WSL keep projects in `/home`; on native Ubuntu follow the home/storage/backup policy. Step 2 should create a unique project and `.venv`.
## Capture a safe baseline
Record only:
- `/etc/os-release` release/codename;
- environment type and architecture;
- `python3 --version`, executable and dpkg owner;
- installed Python APT package versions;
- apt/dpkg audit result;
- filesystem encoding and project-parent owner.
Do not publish usernames, full home paths, machine IDs, internal mirrors, proxy settings, CA material, tokens or complete environment/log dumps.
## Troubleshooting
**Machine is not 26.04/resolute.** Stop using this version-specific guide; follow the actual release documentation. Do not edit os-release/sources to relabel it.
**Python is not 3.14.** Inspect command resolution and dpkg/APT policy. A custom `/usr/local` or environment manager may precede `/usr/bin`. Do not delete it before identifying consumers.
**APT source says noble/questing/other suite.** Preserve the source files and investigate installation/upgrade state. Do not mass-replace strings.
**APT signature/TLS fails.** Verify clock, DNS, proxy, CA, URLs and Ubuntu keyring. Never trusted-host/insecure bypass.
**Package state is incomplete.** Follow dpkg’s exact diagnostic; do not delete lock/database files or continue Python installation.
**python3-pip unavailable.** Confirm successful update and approved `universe` component policy for Resolute. Do not add a random PPA or get-pip to system Python.
**Externally managed error.** Expected outside venv. Create a project venv in Step 2; never break the boundary.
**Existing app requires Python <=3.13.** Treat as compatibility/migration work. Keep Ubuntu 3.14 system Python intact and provide an isolated approved runtime.
**Low disk space.** Inspect exact filesystem consumers and get approval before cleanup. Do not remove WSL/native system directories broadly.
## What not to do in 26.04 Step 1
- Do not duplicate the generic `ubuntu python setup step1` route.
- Do not replace/repoint `/usr/bin/python3` or downgrade the system default.
- Do not run sudo/user/break-system pip.
- Do not mix Noble/interim/third-party repositories into Resolute.
- Do not disable TLS, signatures or phased updates.
- Do not assume every project/dependency supports Python 3.14.
- Do not create root-owned projects or store WSL Linux projects under `/mnt/c`.
- Do not run a release upgrade on an already installed 26.04 system.
| 26.04 Step 1 gate | Pass condition | If it fails |
|---|---|---|
| release | 26.04 Resolute verified | use actual-release guide |
| environment | native/VM/WSL known | identify owner/restart model |
| repositories | signed Resolute sources | repair suite/trust |
| package state | update/upgrade/audit healthy | fix APT/dpkg first |
| Python | actual 3.14 `/usr/bin/python3` | inspect PATH/dpkg policy |
| tooling | full runtime, venv and pip ready | install approved APT set |
| compatibility | project support assessed | isolate older runtime |
| boundary | no global pip/repointing | create project venv next |
## Ubuntu 26.04 LTS Python Setup Step 1 completion gate
Step 1 is complete only when the machine proves it is 26.04 Resolute; environment and architecture are recorded; approved signed Resolute repositories refresh; normal upgrades are reviewed and dpkg is healthy; `/usr/bin/python3` reports the actual Ubuntu default (expected 3.14) and has a verified dpkg owner; the chosen APT developer base supplies venv/pip; standard-library/UTF-8/TLS smoke checks pass; project Python 3.14 compatibility is acknowledged; and no interpreter replacement, mixed suite, global pip or release upgrade occurred.
Final evidence:
```bash
cat /etc/os-release
python3 --version
python3 -c "import sys; print(sys.executable); print(sys.version_info)"
dpkg -S "$(readlink -f "$(command -v python3)")"
python3 -m venv --help
python3 -m pip --version
sudo dpkg --audit
```
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 2**: create a unique user-owned project, build `.venv` from the verified 3.14 base, activate/prove prefix and pip isolation, and test clean recreation without changing system Python.
**Ubuntu 26.04 LTS Python Setup Step 1 succeeds when Resolute’s signed package system owns a healthy, verified Python 3.14 development base that is ready for project virtual environments and protected from global pip or compatibility shortcuts.**
**Ubuntu 26.04 LTS Python Setup Step 10 is to turn the Step 9 Python 3.14 lab into inspected local distribution artifacts without publishing: declare exact package/build metadata, review and lock the build toolchain, build an sdist and its wheel in a controlled environment, verify names/metadata/contents/RECORD, compare independent builds under a fixed source epoch, install the exact wheel into a fresh venv, and retain hashes tied to the source commit.**
The output is evidence, not a release to a registry. This step adds no PyPI/TestPyPI account, token, `.pypirc`, upload action, signing identity or public namespace claim. Publication requires a separate customer decision about repository ownership, package name, visibility, credentials, provenance, retention and rollback.
| Area | Contract | Proof |
|---|---|---|
| metadata | PEP 517/621 | name, version, Python, deps |
| tools | exact reviewed versions | plan, lock, clean replay |
| source | clean tracked commit | reviewed manifest |
| sdist | source archive first | wheel rebuild succeeds |
| wheel | pure Python tag | members, metadata, RECORD |
| README | strict Twine check | no warnings |
| repeat | fixed epoch and inputs | matching bytes or delta |
| install | fresh non-editable venv | import/runtime proof |
## Reconfirm the Step 9 baseline
Run locally as the normal Ubuntu user:
```bash
cd ~/projects/resolute-python-lab
git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
git status --short --branch
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python quality_gate.py
.venv/bin/python verify_sbom.py
.venv/bin/python security_scan.py
git fsck --full
```
Require clean reviewed `main`, Python 3.14, isolated venv, all deterministic gates green and the current advisory result handled under Step 9. Every `python -c`/`python3 -c` command below occupies one physical line.
Building archives from a dirty or unreviewed tree makes commit attribution unreliable. Repair the owning step before packaging.
## Approve package identity and boundary
The customer approves internal distribution `resolute-python-lab` version `0.1.0`, Python range, `editor_probe` runtime module, README, dependencies and recipients. Normalized names can collide; a local build reserves nothing. Diagnostics, tests, tools, venvs and evidence are not runtime content. Use a reviewed `src/` migration for a real multi-module application.
## Review current packaging candidates
As of August 2, 2026, review:
```text
build==1.5.0
setuptools==83.0.0
twine==7.0.0
check-wheel-contents==0.6.3
```
PyPA build 1.5.0 is the current non-yanked frontend and supports Python 3.14; 1.5.1 was yanked. Setuptools is the backend. Twine is used only for `check --strict`, never upload. `check-wheel-contents` provides structural checks. Review direct/transitive identity, owners, release notes, licenses, wheels, hashes, provenance and Python 3.14 support.
Plan without modifying the venv:
```bash
.venv/bin/python -m pip install --dry-run --ignore-installed --only-binary=:all: --report package-install-plan.json 'build==1.5.0' 'setuptools==83.0.0' 'twine==7.0.0' 'check-wheel-contents==0.6.3'
.venv/bin/python -c "import json; p=json.load(open('package-install-plan.json', encoding='utf-8')); print('\n'.join(f\"{x['metadata']['name']}=={x['metadata']['version']} | {x['download_info']['url']}\" for x in p['install']))"
```
Do not use `setup.py install`, `setup.py upload`, global tools, sudo pip, an unreviewed backend plugin or a floating build requirement.
## Create the package branch
```bash
git switch -c package/python-3.14-local-artifacts
```
If it exists locally/remotely, inspect ownership/history. Do not overwrite another branch.
## Extend `pyproject.toml` carefully
Preserve the Step 8 Ruff/mypy/Coverage configuration and add these top-level sections:
```toml
[build-system]
requires = ["setuptools==83.0.0"]
build-backend = "setuptools.build_meta"
[project]
name = "resolute-python-lab"
version = "0.1.0"
description = "A controlled Python 3.14 environment evidence probe"
readme = "README.md"
requires-python = ">=3.14,<3.15"
dynamic = ["dependencies"]
classifiers = [
"Private :: Do Not Upload",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.14",
"Operating System :: POSIX :: Linux",
]
[tool.setuptools]
py-modules = ["editor_probe"]
[tool.setuptools.dynamic]
dependencies = {file = ["requirements.in"]}
```
Dynamic metadata reads reviewed direct intent; every non-comment line must be a PEP 508 runtime requirement, never an index option, dev lock or credential. Add no personal email, URL, license or entry point without approval. `Private :: Do Not Upload` is a marker, not access control.
## Verify metadata input before building
```bash
sed -n '1,260p' pyproject.toml
sed -n '1,80p' requirements.in
sed -n '1,240p' README.md
.venv/bin/python -c "import pathlib, tomllib; p=tomllib.loads(pathlib.Path('pyproject.toml').read_text()); print(p['project']['name'], p['project']['version'], p['project']['requires-python']); print(p['build-system'])"
.venv/bin/python -c "from packaging.requirements import Requirement; from pathlib import Path; print([str(Requirement(x)) for x in Path('requirements.in').read_text().splitlines() if x.strip() and not x.lstrip().startswith('#')])"
```
Require approved identity/backend/dependencies and a README without secrets, private URLs, personal paths or unsupported claims.
## Create and replay the exact package toolchain
Install reviewed candidates into `.venv`, then create `requirements-package.in`:
```text
-r requirements-security.in
build==1.5.0
setuptools==83.0.0
twine==7.0.0
check-wheel-contents==0.6.3
```
Capture/replay the complete environment:
```bash
.venv/bin/python -m pip install --only-binary=:all: 'build==1.5.0' 'setuptools==83.0.0' 'twine==7.0.0' 'check-wheel-contents==0.6.3'
.venv/bin/python -m pip check
.venv/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-package-lock.txt
python3.14 -m venv .venv-package-check
.venv-package-check/bin/python -m pip install --only-binary=:all: --requirement requirements-package-lock.txt
.venv-package-check/bin/python -m pip check
.venv-package-check/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-package-replay.txt
diff -u requirements-package-lock.txt requirements-package-replay.txt
```
Require empty diff and Python 3.14 isolation. The exact backend is in both `pyproject.toml` and the tool lock; `--no-isolation` below prevents build from resolving another copy over the network.
## Ignore only generated local packaging state
Add missing narrow rules to `.gitignore`:
```gitignore
.venv-package-check/
.venv-artifact-wheel/
build/
dist-a/
dist-b/
dist-from-sdist/
*.egg-info/
package-install-plan.json
requirements-package-replay.txt
build-report-a.json
build-report-b.json
artifact-hashes.txt
```
Do not ignore `pyproject.toml`, README, runtime module, package input/lock or inspection script. Avoid a broad `dist/` rule if the customer plans to retain reviewed artifacts elsewhere; this tutorial uses uniquely named disposable directories.
## Freeze the source boundary and epoch
Run every prior gate, then compute a reproducible timestamp from the commit:
```bash
git status --short
git ls-files -z | xargs -0 -n1 printf '%s\n'
git diff --check
.venv/bin/python quality_gate.py
.venv/bin/python verify_sbom.py
export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
export TZ=UTC
export LC_ALL=C.UTF-8
export PYTHONHASHSEED=0
printf 'SOURCE_DATE_EPOCH=%s\n' "$SOURCE_DATE_EPOCH"
```
Review tracked source/symlinks. The epoch is stable evidence; normalization reduces but cannot guarantee reproducibility. Final qualification uses the reviewed packaging commit, never dirty metadata.
## Build sdist then wheel from the sdist
Use a clean output directory rather than deleting ambiguous paths:
```bash
mkdir dist-a
.venv-package-check/bin/python -m build --no-isolation --outdir dist-a --report build-report-a.json
find dist-a -maxdepth 1 -type f -printf '%f\n' | LC_ALL=C sort
```
The default build frontend creates the sdist, extracts it, then builds the wheel from that sdist. This verifies that the source archive contains what the wheel build requires. Expect exactly:
```text
resolute_python_lab-0.1.0-py3-none-any.whl
resolute_python_lab-0.1.0.tar.gz
```
Stop on extra/stale files, wrong name/version/tag or a platform-specific wheel. A pure single-file Python module should not produce native binaries or OS/CPU tags.
Review report paths, kinds, sizes and hashes. `--no-isolation` relies on the just-recreated complete tool lock.
## Validate metadata rendering and wheel structure
```bash
.venv-package-check/bin/python -m twine check --strict dist-a/*
.venv-package-check/bin/python -m check_wheel_contents dist-a/*.whl
.venv-package-check/bin/python -m build --metadata dist-a/*.whl
```
Twine strict mode treats README rendering warnings as failure; it is not a full content/security validator. Wheel-contents checks catch common misplaced, duplicate, bytecode and empty-library errors. Metadata extraction must show the approved normalized distribution, version, Python range, dependencies and private classifier.
Never run Twine upload, add `.pypirc`, set Twine credential variables, or test credentials during this step.
## Inspect both archives directly
Create `inspect_artifacts.py`:
```python
from __future__ import annotations
import base64
import csv
import email.parser
import hashlib
import io
import pathlib
import tarfile
import zipfile
ROOT = pathlib.Path("dist-a")
wheel, = ROOT.glob("*.whl")
sdist, = ROOT.glob("*.tar.gz")
def safe(name: str) -> bool:
path = pathlib.PurePosixPath(name)
return not path.is_absolute() and ".." not in path.parts and "\\" not in name
with zipfile.ZipFile(wheel) as archive:
names = archive.namelist()
assert names and all(safe(name) for name in names)
assert "editor_probe.py" in names
assert not any(name.endswith((".pyc", ".pyo")) or "__pycache__" in name for name in names)
metadata_name, = [name for name in names if name.endswith(".dist-info/METADATA")]
record_name, = [name for name in names if name.endswith(".dist-info/RECORD")]
metadata = email.parser.BytesParser().parsebytes(archive.read(metadata_name))
assert metadata["Name"] == "resolute-python-lab"
assert metadata["Version"] == "0.1.0"
assert metadata["Requires-Python"] == ">=3.14,<3.15"
rows = list(csv.reader(io.TextIOWrapper(archive.open(record_name), encoding="utf-8", newline="")))
recorded = {row[0]: row[1:] for row in rows}
assert set(recorded) == set(names)
for name in names:
digest, size = recorded[name]
if name == record_name:
assert digest == size == ""
continue
algorithm, encoded = digest.split("=", 1)
assert algorithm == "sha256"
actual = base64.urlsafe_b64encode(hashlib.sha256(archive.read(name)).digest()).rstrip(b"=").decode()
assert encoded == actual and int(size) == len(archive.read(name))
with tarfile.open(sdist, "r:gz") as archive:
members = archive.getmembers()
assert members and all(safe(member.name) for member in members)
assert not any(member.issym() or member.islnk() for member in members)
names = {member.name for member in members}
prefix = "resolute_python_lab-0.1.0/"
for required in ("PKG-INFO", "README.md", "pyproject.toml", "requirements.in", "editor_probe.py"):
assert prefix + required in names
print(f"validated wheel={wheel.name} sdist={sdist.name}")
```
Run with both accepted venvs:
```bash
.venv/bin/python inspect_artifacts.py
.venv-package-check/bin/python inspect_artifacts.py
```
The script rejects archive traversal paths, sdist links, bytecode/caches, missing package files, wrong core metadata and invalid/missing wheel RECORD hashes. Review full member lists too:
```bash
.venv-package-check/bin/python -m zipfile -l dist-a/*.whl
tar -tzf dist-a/*.tar.gz
```
Do not extract unreviewed archives over the repository or home directory.
## Compare an independent second build
Keep the same clean commit, Python/tool lock and exported environment:
```bash
mkdir dist-b
.venv-package-check/bin/python -m build --no-isolation --outdir dist-b --report build-report-b.json
sha256sum dist-a/* dist-b/*
cmp -s dist-a/resolute_python_lab-0.1.0-py3-none-any.whl dist-b/resolute_python_lab-0.1.0-py3-none-any.whl
cmp -s dist-a/resolute_python_lab-0.1.0.tar.gz dist-b/resolute_python_lab-0.1.0.tar.gz
```
Matching comparisons prove only this commit, architecture, Python patch and lock. If different, compare ZIP order/timestamps/permissions and tar/gzip headers/generated metadata; fix and rebuild or document the limitation. Never rewrite an artifact to force a match.
## Rebuild the wheel explicitly from the sdist
Although default build already does this, make the evidence visible:
```bash
mkdir dist-from-sdist
.venv-package-check/bin/python -m build --no-isolation --wheel --outdir dist-from-sdist dist-a/resolute_python_lab-0.1.0.tar.gz
sha256sum dist-a/*.whl dist-from-sdist/*.whl
cmp -s dist-a/resolute_python_lab-0.1.0-py3-none-any.whl dist-from-sdist/resolute_python_lab-0.1.0-py3-none-any.whl
```
A matching wheel proves the reviewed sdist can independently reproduce that wheel under the same environment. A mismatch requires archive-level analysis, not hand replacement.
## Install and smoke-test the exact wheel
Create a fresh non-editable consumer environment:
```bash
python3.14 -m venv .venv-artifact-wheel
.venv-artifact-wheel/bin/python -m pip install --only-binary=:all: --requirement requirements-lock.txt
.venv-artifact-wheel/bin/python -m pip install --no-index --no-deps dist-a/resolute_python_lab-0.1.0-py3-none-any.whl
.venv-artifact-wheel/bin/python -m pip check
.venv-artifact-wheel/bin/python -c "import editor_probe, importlib.metadata as m, pathlib; print(m.version('resolute-python-lab')); print(pathlib.Path(editor_probe.__file__).resolve()); print(editor_probe.snapshot('artifact-wheel'))"
```
Require version `0.1.0`, module location under `.venv-artifact-wheel`, expected snapshot evidence and `pip check` success. The second install is `--no-index --no-deps`, proving pip consumes the exact local wheel rather than substituting a registry artifact. Runtime dependencies were installed first from the reviewed runtime lock.
Do not test via editable install or with the source root on `PYTHONPATH`; those can mask missing wheel content. For the strongest proof, run the final import from a temporary directory outside the repository.
## Record a local artifact manifest
```bash
sha256sum dist-a/* | LC_ALL=C sort > artifact-hashes.txt
git rev-parse HEAD
.venv-package-check/bin/python --version
.venv-package-check/bin/python -m build --version
.venv-package-check/bin/python -m twine --version
cat artifact-hashes.txt
```
Retain artifacts, hash manifest, build reports, commit SHA, `SOURCE_DATE_EPOCH`, OS/architecture, Python version, package-tool lock, validation logs, clean-install evidence and any reproducibility limitation in customer-approved storage. Artifact files and build reports remain uncommitted in this tutorial; the source/lock/inspection policy is committed.
Hashes detect change; they do not identify the builder. Signing and provenance attestation require customer-controlled identities, keys/OIDC, trusted build infrastructure and verification policy in a later step.
## Add deterministic package checks to CI
Update `.github/workflows/python-ci.yml` to install `requirements-package-lock.txt`, then add after the Step 9 SBOM check:
```yaml
export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
export TZ=UTC
export LC_ALL=C.UTF-8
export PYTHONHASHSEED=0
mkdir dist-a dist-b
.venv-ci/bin/python -m build --no-isolation --outdir dist-a
.venv-ci/bin/python -m twine check --strict dist-a/*
.venv-ci/bin/python -m check_wheel_contents dist-a/*.whl
.venv-ci/bin/python inspect_artifacts.py
.venv-ci/bin/python -m build --no-isolation --outdir dist-b
cmp -s dist-a/resolute_python_lab-0.1.0-py3-none-any.whl dist-b/resolute_python_lab-0.1.0-py3-none-any.whl
cmp -s dist-a/resolute_python_lab-0.1.0.tar.gz dist-b/resolute_python_lab-0.1.0.tar.gz
```
Because ignored build outputs appear in the working tree, retain the final `git diff --exit-code` tracked-file check. Keep the stable/Resolute matrix, full action SHAs, read-only permission, no secrets/cache/upload and the required stable job name unchanged.
If local qualification proves the backend cannot reproduce an archive byte-for-byte for a documented reason, do not insert a knowingly failing `cmp` into CI. First fix the source/backend configuration or explicitly scope the CI check to deterministic wheel contents/metadata while tracking the sdist limitation. Policy must match evidence.
## Qualify failure and recovery
Without committing deliberate damage:
1. Change the project version locally and require the inspector to reject the artifact; restore metadata.
2. Add an unexpected file through package configuration and require wheel-contents/member review to catch it; restore.
3. Corrupt a copied wheel byte and require ZIP/RECORD or install validation to fail; discard the copy.
4. Run the wheel smoke test from outside the repository with the source module temporarily unavailable through the working directory.
5. Rebuild cleanly and require every package/Step 8/Step 9 gate green.
Never modify the only retained artifact, introduce a secret as a test fixture, run an upload or delete broad directories to clean state.
## Stage an exact source change
Audit disclosure and packaging commands:
```bash
git status --short
git diff --check
grep -RInE '(twine upload|TWINE_(USERNAME|PASSWORD)|\.pypirc|setup\.py upload)' . --exclude-dir=.git --exclude-dir=.venv || true
grep -RInE 'python3? -c `$' . --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.venv-package-check || true
```
Stage only:
```bash
git add --dry-run -- .gitignore pyproject.toml requirements-package.in requirements-package-lock.txt inspect_artifacts.py .github/workflows/python-ci.yml
git add -- .gitignore pyproject.toml requirements-package.in requirements-package-lock.txt inspect_artifacts.py .github/workflows/python-ci.yml
git status --short
git diff --cached --name-status
git diff --cached --check
git diff --cached -- .
```
Reject build outputs, reports, replay files, venvs, credentials, unrelated source and generated metadata. Search staged data for credentials/private keys and confirm `Private :: Do Not Upload` is present.
## Commit, PR and merged-commit rebuild
Verify branch and approved identity; commit as `build: add reproducible Python 3.14 package artifacts`. Dry-run and push only `package/python-3.14-local-artifacts`, then open a reviewed pull request to protected `main`.
Require both CI lanes to build/inspect artifacts and the stable required check to pass at the current head. Review exact metadata, runtime dependency mapping, artifact members, tool lock and absence of upload capability.
After merge, fast-forward local `main`, create new output directories, export the merged commit epoch, rebuild from the merged tree, re-run all validators and fresh-wheel install, and record final hashes. Pull-request artifacts are not final if squash/merge changes source or epoch.
## Troubleshooting
**Build tries the network.** Confirm `--no-isolation`, exact backend in the recreated package venv and satisfied build-system requirements. Do not skip dependency checks.
**Build says unmet setuptools.** The venv does not match the package lock or `pyproject.toml`; recreate it rather than relaxing the backend pin.
**Wrong package appears in wheel.** Review `tool.setuptools.py-modules`, stale `build/`/egg-info state and tracked source. Use fresh output/build state.
**Wheel is empty.** A single-file project must use `py-modules`, not packages discovery.
**README check warns.** Treat strict warning as failure and correct README markup/content; do not drop `--strict`.
**Dependency metadata is missing/wrong.** Validate `requirements.in` and dynamic configuration. Do not use a full transitive lock as public `Requires-Dist` intent.
**Wheel installs but import comes from source.** Run outside repository and inspect `editor_probe.__file__`; remove `PYTHONPATH`/editable contamination.
**Wheel tags are platform-specific.** Investigate native/compiled content and target matrix. Do not relabel filenames manually.
**Builds differ.** Compare ZIP/tar metadata/member order/generated files with identical epoch, commit, locale, Python and lock. Report unresolved nondeterminism honestly.
**Sdist misses a file.** Default wheel-from-sdist failure is doing its job. Correct package/manifest configuration, rebuild cleanly and inspect members.
## Step 10 prohibitions
Do not publish/reserve a name; add registry credentials; run Twine upload; build from a dirty tree; float frontend/backend; bypass isolation proof; package venvs/tests/secrets/caches; use editable install as artifact proof; hand-edit/rename completed archives; claim cross-platform reproducibility from one host; or equate a hash with signed provenance.
| Gate | Pass | Fix |
|---|---|---|
| identity | approved private metadata | correct project intent |
| tools | exact clean replay | repair lock |
| sdist | wheel builds from archive | fix manifest |
| wheel | tag, members, RECORD pass | rebuild from source |
| validation | strict checks pass | fix source/metadata |
| repeat | bytes match or delta recorded | find nondeterminism |
| consumer | exact wheel imports in fresh venv | fix artifact |
| boundary | no upload or credentials | remove capability |
## Ubuntu 26.04 LTS Python Setup Step 10 completion gate
Step 10 is complete only when Steps 8–9 remain green; package identity/boundary/version/Python support/runtime intent are approved; PEP 517/621 metadata preserves quality policy and declares exact Setuptools backend plus the single intended module; current non-yanked build, backend and validation tools are reviewed, exact-locked and wheel-only replayed in Python 3.14; source is clean and attributable; a commit-derived epoch and normalized environment are recorded; default build creates exactly one sdist and one pure-Python wheel from that sdist without surprise resolution; reports, filenames, archive paths/members, metadata, dependencies, private classifier and wheel RECORD hashes pass direct inspection; Twine strict and wheel-content checks pass; a second independent build is byte-identical or any limitation is precisely investigated/recorded; explicit sdist-to-wheel recreation is checked; the exact wheel installs with no registry substitution into a fresh non-editable consumer venv and imports from its site-packages; CI repeats deterministic build/inspection without new permissions or renamed checks; merged-source artifacts/hashes are rebuilt and retained safely; and no registry upload, credential, public claim or improvised signature occurred.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git rev-parse HEAD
.venv/bin/python quality_gate.py
.venv/bin/python verify_sbom.py
.venv-package-check/bin/python -m pip check
.venv-package-check/bin/python inspect_artifacts.py
.venv-package-check/bin/python -m twine check --strict dist-a/*
sha256sum dist-a/* dist-b/* dist-from-sdist/*
.venv-artifact-wheel/bin/python -c "import editor_probe, importlib.metadata as m; print(m.version('resolute-python-lab')); print(editor_probe.__file__)"
```
Retain the merged commit, source epoch, OS/architecture, Python/tool versions, exact lock, validation output, artifact hashes and consumer proof in approved storage. Never retain tokens or publish private artifacts inadvertently.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 11**: create customer-controlled build provenance and artifact signing/verification policy, bind attestations to the merged commit and exact hashes, test verification in a clean trust store, and still avoid public publication until repository authorization is complete.
**Ubuntu 26.04 LTS Python Setup Step 10 succeeds when a clean reviewed Python 3.14 source commit deterministically produces inspectable local artifacts whose exact wheel—not the source tree—passes metadata, integrity and fresh-consumer behavior checks, with publication technically and procedurally out of scope.**
**Ubuntu 26.04 LTS Python Setup Step 11 is to bind the Step 10 local Python 3.14 artifacts to an approved customer signing identity and a machine-checkable build statement: qualify the signing policy and key custody, rebuild the merged commit, create portable hashes plus in-toto/SLSA-style provenance, make detached OpenPGP signatures, and verify every byte in a clean trust store anchored to an independently confirmed fingerprint—without placing private keys in GitHub or publishing artifacts.**
This local ceremony makes no automatic SLSA claim. A good signature proves key possession over bytes; trust still depends on approved fingerprint/custody, builder integrity, key validity and truthful provenance.
| Area | Policy | Proof |
|---|---|---|
| bytes | SHA-256 and signatures | recompute and verify |
| statement | in-toto v1 | exact subjects |
| predicate | SLSA provenance v1 | source, lock, builder, run |
| identity | approved fingerprint | independent record |
| private key | customer custody | never in Git or CI |
| public key | reviewed export | exact clean import |
| verifier | isolated keyring | `VALIDSIG` and policy |
| boundary | no publication | no upload/token/log |
## Reconfirm the final Step 10 source
Run as the normal Ubuntu user:
```bash
cd ~/projects/resolute-python-lab
git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
git status --short --branch
.venv/bin/python quality_gate.py
.venv/bin/python verify_sbom.py
.venv/bin/python security_scan.py
.venv-package-check/bin/python -m pip check
git fsck --full
```
Require clean reviewed `main`, all prior gates green and current advisory policy satisfied. Record `git rev-parse HEAD`, `git rev-parse HEAD^{tree}` and the approved repository identity. Every `python -c`/`python3 -c` command below is one physical line.
Never sign pull-request artifacts, a dirty tree, an unmerged commit assumed to be final, or archives whose Step 10 inspection/install proof is missing.
## Approve the signing policy before touching keys
The customer security owner defines artifact/source identity, authorized primary/subkey fingerprints, owner/custody, algorithm/expiry/rotation/backup/revocation, builder-signer-verifier separation, provenance materials, recipients/retention/release rules and whether transparency is allowed. Prefer a hardware-backed signing subkey. Never improvise a production key, reuse a personal encryption identity, share/export secrets, disable expiry or colocate revocation recovery with artifacts.
For a disposable training rehearsal, use an explicitly labeled temporary key in a temporary GnuPG home and destroy it under customer policy afterward. It must never be represented as the production identity.
## Verify Ubuntu owns GnuPG
Ubuntu 26.04 LTS publishes GnuPG 2.4.8. Inspect repository/package ownership:
```bash
apt-cache policy gnupg gpg gpgv
dpkg-query -W -f='${binary:Package}\t${Version}\t${Status}\n' gnupg gpg gpgv 2>/dev/null || true
command -v gpg gpgv
dpkg-query -S "$(command -v gpg)" "$(command -v gpgv)"
gpg --version
gpgv --version
```
If approved packages are absent, update/install through the normal Step 1 APT process:
```bash
sudo apt update
sudo apt install gnupg gpgv
```
Require approved Resolute mirrors; never curl an installer or substitute a wrapper for package ownership proof.
## Inspect key state without exposing secrets
Record GnuPG directory ownership and public metadata:
```bash
gpgconf --list-dirs
stat -c '%U %G %a %n' "$GNUPGHOME" 2>/dev/null || true
gpg --batch --with-colons --list-secret-keys --with-fingerprint --with-subkey-fingerprint --with-keygrip
gpg --batch --with-colons --list-keys --with-fingerprint --with-subkey-fingerprint
```
If `GNUPGHOME` is unset, GnuPG normally uses the user's `.gnupg`; do not redefine `HOME`. Require normal-user ownership and mode 700 for a private GnuPG directory. Metadata output includes identity strings and keygrips; classify it before retention.
Select only the exact customer-approved signing-capable fingerprint from an independently sourced policy record, not from the same public-key file being verified:
```bash
read -r -p 'Approved full signing fingerprint: ' SIGNING_FPR
case "$SIGNING_FPR" in (*[!0-9A-Fa-f]*|'') echo 'invalid fingerprint' >&2; exit 1;; esac
case "${#SIGNING_FPR}" in (40|64) :;; (*) echo 'unexpected fingerprint length' >&2; exit 1;; esac
SIGNING_FPR="$(printf '%s' "$SIGNING_FPR" | tr '[:lower:]' '[:upper:]')"
gpg --batch --list-options show-usage,show-expire --fingerprint "$SIGNING_FPR"
```
Confirm full primary/signing-subkey fingerprints, `[S]`, expiry, revocation, owner/token and authorization. Never accept a short key ID.
## Create a dedicated provenance branch
```bash
git switch -c provenance/python-3.14-local-signing
```
This branch adds verifier/policy source only. Private keys, signatures and release artifacts remain outside Git. If the customer approves committing the public key, its expected fingerprint must also be committed and reviewed.
## Create the signing policy file
Create `release-signing-policy.json` with customer-approved values:
```json
{
"schema_version": 1,
"distribution": "resolute-python-lab",
"version": "0.1.0",
"artifact_names": [
"resolute_python_lab-0.1.0-py3-none-any.whl",
"resolute_python_lab-0.1.0.tar.gz"
],
"digest_algorithm": "sha256",
"statement_type": "https://in-toto.io/Statement/v1",
"predicate_type": "https://slsa.dev/provenance/v1",
"builder_id": "urn:customer:builder:ubuntu-26.04-python-3.14-local",
"source_uri": "git+ssh://approved-customer-source/resolute-python-lab",
"signing_fingerprint": "REPLACE_WITH_APPROVED_FULL_FINGERPRINT"
}
```
Replace the three organization-specific values with approved stable identifiers/fingerprint. The source URI need not expose a private hostname; it must be unambiguous to intended verifiers. Do not commit the literal placeholder.
Validate syntax and exact fingerprint agreement:
```bash
.venv/bin/python -m json.tool release-signing-policy.json >/dev/null
.venv/bin/python -c "import json; p=json.load(open('release-signing-policy.json')); print(p['builder_id']); print(p['source_uri']); print(p['signing_fingerprint'])"
test "$(.venv/bin/python -c "import json; print(json.load(open('release-signing-policy.json'))['signing_fingerprint'])")" = "$SIGNING_FPR"
```
## Rebuild the candidate during the ceremony
Use the merged source and exact Step 10 package environment. Create a new unambiguous output directory; stop if it exists rather than deleting it:
```bash
test ! -e release-candidate
mkdir release-candidate
export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
export TZ=UTC
export LC_ALL=C.UTF-8
export PYTHONHASHSEED=0
export BUILD_STARTED_ON="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILD_INVOCATION_ID="$(.venv-package-check/bin/python -c "import uuid; print(uuid.uuid4())")"
.venv-package-check/bin/python -m build --no-isolation --outdir release-candidate --report release-build-report.json
export BUILD_FINISHED_ON="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
.venv-package-check/bin/python -m twine check --strict release-candidate/*
.venv-package-check/bin/python -m check_wheel_contents release-candidate/*.whl
```
Adapt the Step 10 inspector to accept an explicit directory argument or make a reviewed temporary copy pointing at `release-candidate`; never hand-edit the output archives. Repeat the fresh external wheel installation proof on these exact bytes.
Require exactly the two policy artifact names. Capture start/finish around the real build, not invented timestamps copied from the commit. The source epoch controls archive timestamps; invocation times describe this ceremony.
## Create a portable artifact hash manifest
Hash basenames from inside the candidate directory so the manifest contains no workstation path:
```bash
(cd release-candidate && sha256sum resolute_python_lab-0.1.0-py3-none-any.whl resolute_python_lab-0.1.0.tar.gz | LC_ALL=C sort) > artifact-hashes.txt
sed -n '1,20p' artifact-hashes.txt
sha256sum artifact-hashes.txt release-build-report.json requirements-package-lock.txt sbom.cdx.json
```
Reject absolute paths, unexpected files, duplicate names and algorithms other than SHA-256. The manifest is meaningful only if verification recomputes each digest against supplied artifacts.
## Generate an in-toto/SLSA-style statement
Create `create_provenance.py`:
```python
from __future__ import annotations
import hashlib
import json
import os
import pathlib
import subprocess
policy = json.loads(pathlib.Path("release-signing-policy.json").read_text(encoding="utf-8"))
root = pathlib.Path("release-candidate")
def sha256(path: pathlib.Path) -> str:
return hashlib.sha256(path.read_bytes()).hexdigest()
subjects = []
for name in policy["artifact_names"]:
path = root / name
if not path.is_file() or path.name != name:
raise SystemExit(f"missing/unsafe artifact: {name}")
subjects.append({"name": name, "digest": {"sha256": sha256(path)}})
commit = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
tree = subprocess.check_output(["git", "rev-parse", "HEAD^{tree}"], text=True).strip()
statement = {
"_type": policy["statement_type"],
"subject": subjects,
"predicateType": policy["predicate_type"],
"predicate": {
"buildDefinition": {
"buildType": "https://www.python.org/psf-landing/packaging-local-build/v1",
"externalParameters": {
"command": ["python", "-m", "build", "--no-isolation"],
"python": "3.14",
"sourceDateEpoch": os.environ["SOURCE_DATE_EPOCH"],
},
"internalParameters": {},
"resolvedDependencies": [
{"uri": policy["source_uri"], "digest": {"gitCommit": commit, "gitTree": tree}},
{"name": "requirements-package-lock.txt", "digest": {"sha256": sha256(pathlib.Path("requirements-package-lock.txt"))}},
{"name": "sbom.cdx.json", "digest": {"sha256": sha256(pathlib.Path("sbom.cdx.json"))}},
],
},
"runDetails": {
"builder": {"id": policy["builder_id"]},
"metadata": {
"invocationId": os.environ["BUILD_INVOCATION_ID"],
"startedOn": os.environ["BUILD_STARTED_ON"],
"finishedOn": os.environ["BUILD_FINISHED_ON"],
},
"byproducts": [
{"name": "release-build-report.json", "digest": {"sha256": sha256(pathlib.Path("release-build-report.json"))}}
],
},
},
}
pathlib.Path("provenance.intoto.json").write_text(json.dumps(statement, indent=2, sort_keys=True) + "\n", encoding="utf-8")
```
The Statement binds subjects by digest and identifies SLSA provenance v1. Local identifiers are policy, not certification. Claim no SLSA level without an independently assessed builder.
Run and review:
```bash
.venv-package-check/bin/python create_provenance.py
.venv-package-check/bin/python -m json.tool provenance.intoto.json >/dev/null
sed -n '1,280p' provenance.intoto.json
sha256sum provenance.intoto.json
```
Reject unknown URLs, usernames, paths, environment secrets, omitted subjects/materials, wrong commit/tree, inaccurate command/times or an unapproved builder ID.
## Verify provenance semantics before signing
Create `verify_release.py`:
```python
from __future__ import annotations
import hashlib
import json
import pathlib
import re
import subprocess
policy = json.loads(pathlib.Path("release-signing-policy.json").read_text(encoding="utf-8"))
statement = json.loads(pathlib.Path("provenance.intoto.json").read_text(encoding="utf-8"))
root = pathlib.Path("release-candidate")
line = re.compile(r"^([0-9a-f]{64}) ([A-Za-z0-9][A-Za-z0-9_.-]*)$")
manifest: dict[str, str] = {}
for raw in pathlib.Path("artifact-hashes.txt").read_text(encoding="utf-8").splitlines():
match = line.fullmatch(raw)
if not match or match.group(2) in manifest:
raise SystemExit("invalid manifest")
manifest[match.group(2)] = match.group(1)
if list(sorted(manifest)) != list(sorted(policy["artifact_names"])):
raise SystemExit("artifact set differs from policy")
for name, expected in manifest.items():
if hashlib.sha256((root / name).read_bytes()).hexdigest() != expected:
raise SystemExit(f"artifact digest mismatch: {name}")
if statement.get("_type") != policy["statement_type"] or statement.get("predicateType") != policy["predicate_type"]:
raise SystemExit("statement type mismatch")
subjects = {item["name"]: item["digest"]["sha256"] for item in statement["subject"]}
if subjects != manifest:
raise SystemExit("provenance subjects differ from manifest")
predicate = statement["predicate"]
if predicate["runDetails"]["builder"]["id"] != policy["builder_id"]:
raise SystemExit("builder mismatch")
materials = predicate["buildDefinition"]["resolvedDependencies"]
source, = [item for item in materials if item.get("uri") == policy["source_uri"]]
if source["digest"]["gitCommit"] != subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip():
raise SystemExit("commit mismatch")
print(f"release policy verified: subjects={len(subjects)} builder={policy['builder_id']}")
```
Run it before and after signing. Extend it to verify the lock/SBOM/tree/byproduct digests if the customer's policy engine does not already do so; the compact lab check focuses on the critical artifact/commit/builder binding.
## Export only the approved public key
```bash
gpg --batch --armor --export "$SIGNING_FPR" > signing-public-key.asc
test -s signing-public-key.asc
gpg --batch --show-keys --with-colons --fingerprint signing-public-key.asc
grep -q 'PRIVATE KEY' signing-public-key.asc && { echo 'secret material marker found' >&2; exit 1; } || true
sha256sum signing-public-key.asc
```
Confirm fingerprints/no secret packets. Transfer the expected fingerprint through a separate trusted channel.
## Sign artifacts, manifest and provenance
First run `verify_release.py`, then require interactive token/touch/passphrase handling through GnuPG—not a command argument or environment variable:
```bash
.venv-package-check/bin/python verify_release.py
gpg --batch --local-user "$SIGNING_FPR" --armor --detach-sign --output artifact-hashes.txt.asc artifact-hashes.txt
gpg --batch --local-user "$SIGNING_FPR" --armor --detach-sign --output provenance.intoto.json.asc provenance.intoto.json
gpg --batch --local-user "$SIGNING_FPR" --armor --detach-sign --output release-candidate/resolute_python_lab-0.1.0-py3-none-any.whl.asc release-candidate/resolute_python_lab-0.1.0-py3-none-any.whl
gpg --batch --local-user "$SIGNING_FPR" --armor --detach-sign --output release-candidate/resolute_python_lab-0.1.0.tar.gz.asc release-candidate/resolute_python_lab-0.1.0.tar.gz
```
Do not use `--pinentry-mode loopback` with an inline/passphrase-file secret, `--default-key`, a short ID, `--yes` over preexisting signatures, or GitHub Actions secrets. Stop if any output path already exists; never overwrite an ambiguous signature.
## Verify in a clean trust store
Create a new empty directory with strict permissions:
```bash
VERIFY_KEYRING="$(mktemp -d)"
chmod 700 "$VERIFY_KEYRING"
gpg --homedir "$VERIFY_KEYRING" --batch --import-options import-show --import signing-public-key.asc
gpg --homedir "$VERIFY_KEYRING" --batch --with-colons --fingerprint
```
Compare the imported full fingerprint to the independently approved policy value before signatures. Do not mark it ultimately trusted merely to remove warnings: cryptographic validity and identity authorization are separate decisions.
Verify machine-readably and visibly:
```bash
gpg --homedir "$VERIFY_KEYRING" --batch --status-fd 1 --verify artifact-hashes.txt.asc artifact-hashes.txt | tee verify-manifest.status
gpg --homedir "$VERIFY_KEYRING" --batch --status-fd 1 --verify provenance.intoto.json.asc provenance.intoto.json | tee verify-provenance.status
gpg --homedir "$VERIFY_KEYRING" --batch --status-fd 1 --verify release-candidate/resolute_python_lab-0.1.0-py3-none-any.whl.asc release-candidate/resolute_python_lab-0.1.0-py3-none-any.whl | tee verify-wheel.status
gpg --homedir "$VERIFY_KEYRING" --batch --status-fd 1 --verify release-candidate/resolute_python_lab-0.1.0.tar.gz.asc release-candidate/resolute_python_lab-0.1.0.tar.gz | tee verify-sdist.status
grep -F "[GNUPG:] VALIDSIG $SIGNING_FPR" verify-*.status
.venv-package-check/bin/python verify_release.py
```
Require exactly the approved full signing fingerprint in each `VALIDSIG`, no `BADSIG`, `ERRSIG`, revoked/expired-at-policy failure, and successful artifact/provenance semantic verification. Human “Good signature” text alone is insufficient and “not certified with a trusted signature” is expected in an empty local trust model unless identity policy says otherwise.
Repeat Step 10's fresh-wheel install only after verification. Retain the temporary keyring for review or safely remove that exact confirmed path; never broadly delete through an unset variable.
## Prove negative cases and recovery
Use copies in a separate qualification directory:
1. Flip one byte in a copied wheel; require direct signature and hash-manifest verification to fail.
2. Change one provenance subject digest; require its detached signature and semantic check to fail.
3. Import a different public key into another empty keyring; require signer-fingerprint policy failure.
4. Remove an artifact line from a copied manifest; require exact-set validation to fail.
5. Restore untouched signed files and require all four `VALIDSIG` records, semantic checks and fresh installation to pass.
Never corrupt the sole retained candidate, revoke a production key as a test, weaken trust policy, ignore GnuPG status codes or execute an unverified artifact.
## Git and CI boundary
Stage only policy/verifier source and the customer-approved public key:
```bash
git add --dry-run -- release-signing-policy.json signing-public-key.asc create_provenance.py verify_release.py .gitignore
git add -- release-signing-policy.json signing-public-key.asc create_provenance.py verify_release.py .gitignore
git status --short
git diff --cached --check
git diff --cached -- .
```
Add local ceremony outputs to `.gitignore`: `release-candidate/`, `release-build-report.json`, `artifact-hashes.txt*`, `provenance.intoto.json*`, `verify-*.status`. Reject any secret-key block, passphrase, token, private path/URL or signature generated over uncommitted policy.
CI may validate JSON/Python syntax, public-key fingerprint/policy agreement and rebuild unsigned artifacts. It must not receive the private key or sign pull-request code. A signing job requires a separately authorized protected release environment, non-exportable customer identity, exact-ref approval and audit design; this local step does not create one.
Commit as `security: add local artifact provenance verification`, push only the explicit provenance branch after dry-run, and use the protected pull-request flow. After merge, rebuild and re-sign the actual merged commit because policy/verifier source and commit/tree hashes changed.
## Retain and distribute the verification bundle
The customer-held bundle contains the two artifacts/signatures, portable hash manifest/signature, provenance/signature, public key, approved fingerprint/policy, build report, package/SBOM locks or their hashes, commit/tree IDs, tool/OS evidence, verification logs and instructions. Transfer through an approved integrity/confidentiality channel.
Public keys/signatures are not secrets, but identity/provenance can disclose architecture. Do not upload anywhere without recipient/retention approval.
## Rotation, revocation and time
Document how consumers obtain key updates/revocations independently. On rotation, overlap trusted public keys for a bounded period, identify which versions each may sign, and requalify clean-store verification. If a key is compromised, stop signing, publish the customer-approved revocation through established channels, identify affected signatures by creation time/key fingerprint, rebuild with a new authorized key, and notify recipients.
OpenPGP signature creation time is signer-supplied and not a public timestamp authority. Offline signatures do not prove when they existed. If trusted timestamping/transparency is required, authorize and design it separately with privacy/network implications.
## Troubleshooting
No signing key: invoke customer provisioning, never improvise. `NO_PUBKEY`: import only the approved export and confirm its fingerprint. `BADSIG`/hash mismatch: quarantine and rebuild/reacquire; never re-sign unknown bytes. Good signature/wrong fingerprint: reject. Expired/revoked: follow lifecycle policy, never change system time. Pinentry failure: inspect agent/token interactively, never expose passphrases. Commit/claim mismatch: rebuild/regenerate/re-sign, never patch signed JSON. An artifact-only pass is insufficient if provenance fails. Unexpected trusted keys mean the verifier was not clean. CI requesting the private key violates this design.
## Step 11 prohibitions
Do not invent a production key; use short IDs; export/commit private material; put passphrases in commands; sign dirty/unmerged artifacts; overwrite signatures; trust a key from the same unverified bundle without an independent fingerprint; accept human-readable “Good signature” alone; claim a SLSA level; patch signed provenance; sign in PR CI; or publish artifacts/keys/provenance without authorization.
| Step 11 gate | Pass | Corrective direction |
|---|---|---|
| source/build | clean merged commit and Step 10 proof | rebuild before signing |
| key policy | approved full fingerprint/custody/lifecycle | provision or reauthorize |
| manifest | exact portable names and SHA-256 | regenerate from artifacts |
| provenance | subjects/materials/builder/invocation match | regenerate, never patch |
| signatures | all detached signatures from approved key | reject/re-sign trusted bytes |
| clean verifier | isolated keyring and exact `VALIDSIG` | repair key distribution/policy |
| consumer | verify before fresh install/import | stop execution on any failure |
| boundary | no private key in CI and no publication | remove exposure/capability |
## Ubuntu 26.04 LTS Python Setup Step 11 completion gate
Step 11 is complete only when Steps 8–10 remain green; the customer approves signing identity, custody, lifecycle, builder/source identifiers, recipients and publication boundary; Ubuntu owns the GnuPG executable; the selected full primary/signing-subkey fingerprints, capability, expiry and revocation state match independent policy; private material remains non-exportable/outside Git and PR CI; the actual clean merged commit is rebuilt with exact package tools and inspected/installed; artifact names and portable SHA-256 manifest are exact; an in-toto Statement v1 with SLSA provenance v1 predicate binds both artifacts to commit/tree, package lock, SBOM, builder, invocation and build report; semantic verification passes before signing; only the approved public key is exported; detached signatures cover each artifact, manifest and provenance; an empty mode-700 verifier keyring imports that public key and independently confirms its fingerprint; every signature emits the expected full `VALIDSIG`; hashes, provenance semantics and fresh consumer installation pass after signature verification; negative byte/claim/key/set trials fail and clean recovery passes; the verification bundle is retained/transferred under policy; revocation/rotation/time limitations are documented; no SLSA level is claimed; and no key, artifact, attestation or identity is published without authorization.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git rev-parse HEAD HEAD^{tree}
sha256sum release-candidate/* artifact-hashes.txt provenance.intoto.json signing-public-key.asc
.venv-package-check/bin/python verify_release.py
grep -F "[GNUPG:] VALIDSIG $SIGNING_FPR" verify-*.status
gpg --homedir "$VERIFY_KEYRING" --batch --with-colons --fingerprint
.venv-artifact-wheel/bin/python -c "import editor_probe, importlib.metadata as m; print(m.version('resolute-python-lab')); print(editor_probe.__file__)"
```
Retain approved fingerprints/policy, public key, signed artifacts/manifest/provenance, build and verification evidence, exact commit/tree and key-status decisions. Store revocation/private recovery material separately.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 12**: authorize a private package repository and trusted release workflow, define OIDC/token-free publication or narrowly scoped credentials, test an isolated staging namespace, verify server-side hashes/attestations and consumer install, then prove rollback/revocation without exposing the package publicly.
**Ubuntu 26.04 LTS Python Setup Step 11 succeeds when an independently anchored customer identity signs the exact tested wheel, source archive, portable hashes and truthful build statement, and a clean verifier rejects every byte, identity or provenance mismatch before installation—without confusing local signing with public trust or SLSA certification.**
**Ubuntu 26.04 LTS Python Setup Step 2 is to create a user-owned Resolute project, build its `.venv` from Ubuntu's verified Python 3.14 base, and prove interpreter, prefix, pip, filesystem, activation and recreation isolation.** This step does not replace `/usr/bin/python3`, install project packages, or modify Ubuntu's externally managed system environment.
Step 1 established the machine baseline. Step 2 uses a new project named `~/projects/resolute-python-lab`, distinct from the generic Ubuntu and WSL tutorials. Commands read the actual machine state: although Ubuntu 26.04 LTS defaults to Python 3.14, the local version and executable remain acceptance evidence rather than assumptions.
| Boundary | Owner | Step 2 evidence |
|---|---|---|
| Ubuntu base | APT/dpkg | `/usr/bin/python3`, expected 3.14 |
| project directory | normal user | home filesystem and `stat` |
| virtual environment | project | `.venv/bin/python` |
| interpreter isolation | venv | prefix differs from base-prefix |
| package installer | venv | pip path remains under `.venv` |
| source program | project | Python 3.14 standard-library probe |
| generated files | disposable | root `.gitignore` plus venv metadata |
| reproducibility | documented command | independent `.venv-check` passes |
## Start in the Ubuntu shell as the normal user
Run:
```bash
whoami
id
printf 'home=%s cwd=%s\n' "$HOME" "$PWD"
```
Do not continue as `root`. A project created with sudo becomes root-owned and later encourages unsafe permission workarounds. Sudo is for approved system administration, not project directories, venv creation, source editing, pip, or program execution.
If this Ubuntu installation runs under WSL, the same commands apply inside Ubuntu, but the project must stay under `/home`, not `/mnt/c`. If it is native, virtualized, cloud-hosted, or containerized, retain the corresponding backup, restart and storage policy identified in Step 1.
## Reconfirm the 26.04 Resolute baseline
Run before creating anything:
```bash
cat /etc/os-release
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
python3 --version
command -v python3
readlink -f "$(command -v python3)"
python3 -c "import sys; print(sys.executable); print(sys.version_info)"
sudo dpkg --audit
```
The release must report `26.04` and `resolute`. The Ubuntu base should resolve to `/usr/bin/python3` and is expected to report Python 3.14. An empty dpkg audit is healthy.
Stop if the machine is a different release, if a custom interpreter precedes `/usr/bin`, or if dpkg is inconsistent. Do not edit `/etc/os-release`, repoint `python3`, or delete a custom runtime to make the output resemble this guide.
## Prove the base is ready for venv
Run:
```bash
dpkg -S "$(readlink -f "$(command -v python3)")"
python3 -m venv --help
python3 -m pip --version
python3 -c "import sys; print(sys.prefix); print(sys.base_prefix)"
```
Before isolation, prefix and base-prefix normally match. The versioned executable should have a dpkg owner. The venv module must load.
If Step 1 was not completed and venv is missing, return to that step. The approved full developer base is installed through APT:
```bash
sudo apt update
sudo apt install python3-full python3-pip python3-pip-whl
```
Review the package plan. Do not use `get-pip.py`, sudo pip, `--user`, `--break-system-packages`, a PPA, or an alternate-release repository to repair system Python.
## Choose a Linux-native project parent
Inspect and prepare the parent as the normal user:
```bash
mkdir -p ~/projects
findmnt -T ~/projects
stat -c 'owner=%U group=%G mode=%A path=%n' ~/projects
df -h ~/projects
```
The owner should be the current user. On WSL, `findmnt` should confirm the Linux distribution filesystem rather than a Windows-mounted path. Virtual environments contain platform-specific launchers, links and installed artifacts; they do not belong in OneDrive, a Windows profile, a network share, or a directory shared between operating systems.
Do not loosen permissions with `chmod 777`. Correct the ownership cause only after identifying why it is wrong.
## Create the unique Resolute project
Run without sudo:
```bash
test ! -e ~/projects/resolute-python-lab
mkdir ~/projects/resolute-python-lab
cd ~/projects/resolute-python-lab
pwd
stat -c 'owner=%U group=%G mode=%A path=%n' .
ls -la
```
The initial `test` must succeed silently. If the path exists, stop and inspect it; do not merge with unknown source or delete it. Select another reviewed name if this lab was already performed.
The expected project path is `/home//projects/resolute-python-lab`, owned by the normal user.
## Record the Python 3.14 base facts
From the project root:
```bash
python3 -c "import sys; print('executable=', sys.executable); print('version=', sys.version); print('prefix=', sys.prefix); print('base_prefix=', sys.base_prefix)"
python3 -c "import sysconfig; print(sysconfig.get_platform())"
python3 -c "import site; print(site.getsitepackages())"
```
Every `python3 -c` and later `python -c` example in this page is one physical shell line. Do not copy a PowerShell backtick/newline form into Bash.
Confirm the version tuple begins with 3.14. If it does not, stop: do not label another interpreter as the Ubuntu 26.04 Python 3.14 baseline. Record architecture/platform because binary wheels must match the interpreter ABI and system platform.
## Create the project `.venv`
Run:
```bash
python3 -m venv .venv
```
The command should finish without error or sudo. It creates a distinct Python prefix with launchers in `.venv/bin`, project site-packages, activation scripts and `pyvenv.cfg`. It uses Ubuntu's actual `python3`; no global configuration changes.
Do not add `--system-site-packages`. That option weakens isolation by exposing Ubuntu-managed packages. Do not add `--upgrade-deps` here: it performs network-dependent package changes without the Step 3 index, trust, proxy and pinning decisions.
Python 3.14's venv behavior creates a `.gitignore` within the environment by default. That is useful generated metadata, but the project will also have a root ignore rule for compatibility with teams, tools and older creators.
## Inspect generated metadata without editing it
Run:
```bash
ls -la .venv
ls -la .venv/bin | sed -n '1,100p'
sed -n '1,100p' .venv/pyvenv.cfg
test -f .venv/.gitignore && sed -n '1,20p' .venv/.gitignore
stat -c 'owner=%U group=%G mode=%A path=%n' .venv .venv/bin .venv/bin/python
```
All generated files must be accessible to and owned by the normal user. `pyvenv.cfg` records the creator/base relationship. Do not hand-edit it, repair launchers, copy the directory, or move it to another path. Python documents venvs as disposable and not movable; recreation is the portability method.
The internal `.gitignore` is not an invitation to initialize or publish a repository. Source-control ownership and remotes remain customer decisions.
## Prove isolation without activation
Direct invocation avoids PATH ambiguity:
```bash
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info)"
.venv/bin/python -c "import sys; print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip --version
.venv/bin/python -m pip check
```
Pass conditions:
- Python reports version 3.14 from this project's `.venv/bin/python`.
- `sys.prefix` points inside `resolute-python-lab/.venv`.
- `sys.base_prefix` identifies the Ubuntu base and differs from prefix.
- The comparison prints `True`.
- pip reports a location under this `.venv`.
- `pip check` reports no broken requirements.
Activation is optional. Services, CI and scheduled work often use the full `.venv/bin/python` path because it is explicit and does not depend on shell state.
## Activate the venv in Bash
Run:
```bash
source .venv/bin/activate
```
`source` applies the activation script to the current shell. It prepends `.venv/bin` to PATH, sets `VIRTUAL_ENV`, and defines `deactivate`; it does not change the operating system interpreter.
Prove active resolution:
```bash
printf 'VIRTUAL_ENV=%s\n' "$VIRTUAL_ENV"
command -v python
command -v python3
command -v pip
python --version
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
python -m pip --version
```
All command paths should resolve inside the project venv; the prefix comparison must be true. The prompt decoration `(.venv)` is only a convenience. A theme can hide or imitate it, while executable and prefix output provide evidence.
Do not put unconditional activation in `~/.bashrc`. It can leak this project's environment into unrelated shells, automation and maintenance work.
## Inspect import isolation and packaging state
While active:
```bash
python -c "import site; print(site.getsitepackages()); print(site.ENABLE_USER_SITE)"
python -c "import sys; print('\n'.join(sys.path))"
python -m pip list
python -m pip check
env | grep '^PYTHON' || true
```
The packaging-tool versions depend on Ubuntu's venv seed and later updates; do not use a copied version number as the gate. The important facts are environment location and consistency.
Investigate unexpected `PYTHONPATH`, `PYTHONHOME`, pip configuration or injected site directories before changing them. Global `PYTHONPATH` can undermine venv isolation. Never print all environment variables into a ticket because they can contain tokens, endpoints and credentials.
## Add the Python 3.14 standard-library probe
Create `resolute_probe.py` with a Linux-aware editor and this content:
```python
from __future__ import annotations
import json
import platform
import sqlite3
import ssl
import sys
import sysconfig
from pathlib import Path
def main() -> None:
with sqlite3.connect(":memory:") as database:
sqlite_version = database.execute("select sqlite_version()").fetchone()[0]
evidence = {
"base_prefix": sys.base_prefix,
"cwd": str(Path.cwd()),
"executable": sys.executable,
"isolated": sys.prefix != sys.base_prefix,
"platform": platform.system(),
"python": platform.python_version(),
"python_platform": sysconfig.get_platform(),
"sqlite": sqlite_version,
"tls": ssl.OPENSSL_VERSION,
}
print(json.dumps(evidence, indent=2, sort_keys=True))
if __name__ == "__main__":
main()
```
This test uses only the Python 3.14 standard library, no network, customer data, third-party import or write outside the project.
Run it through both active resolution and the explicit interpreter:
```bash
python resolute_probe.py
.venv/bin/python resolute_probe.py
python -m compileall -q resolute_probe.py
```
Both runs must report Linux, a 3.14 version, the `.venv` executable, `isolated: true`, the project working directory, and local SQLite/OpenSSL versions. Exact library patch versions can change with Ubuntu security updates.
If `compileall` succeeds, it creates `__pycache__`. That is disposable generated output, not source.
## Add project-root ignore rules
Create `.gitignore` at the project root containing:
```gitignore
.venv/
.venv-check/
__pycache__/
*.py[cod]
```
The root rule makes environment exclusion explicit even though Python 3.14 created an internal venv ignore file. Do not ignore every dotfile; legitimate project configuration often begins with a dot.
If this directory is already intentionally under Git control, verify:
```bash
git check-ignore -v .venv/bin/python
git status --short
```
Do not initialize Git, add a remote, commit, push, or expose customer paths without authorization. Step 2 only prepares correct local source/generated-state boundaries.
## Deactivate and prove the shell returns to Ubuntu
Run:
```bash
deactivate
printf 'VIRTUAL_ENV=%s\n' "${VIRTUAL_ENV-}"
command -v python || true
command -v python3
python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
```
`VIRTUAL_ENV` should be empty. `python3` should again resolve to Ubuntu's base with matching prefix/base-prefix. A bare `python` command can be absent outside the environment; that is normal and does not require an alias or symlink.
Reactivate from the project root:
```bash
cd ~/projects/resolute-python-lab
source .venv/bin/activate
python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
python resolute_probe.py
```
Closing a terminal naturally discards activation. Each new interactive shell activates explicitly, or commands call `.venv/bin/python` directly.
## Demonstrate clean, independent recreation
Do not destroy the working `.venv` merely for proof. Create a second disposable environment from the verified base:
```bash
deactivate
python3 -m venv .venv-check
.venv-check/bin/python --version
.venv-check/bin/python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
.venv-check/bin/python -m pip check
.venv-check/bin/python resolute_probe.py
```
The check environment must independently report Python 3.14, its own `.venv-check` executable/prefix, true isolation, healthy pip metadata, and a successful probe. This demonstrates that project runtime state is reproducible from the Ubuntu base rather than dependent on manual repairs.
Keep `.venv-check` until evidence is reviewed. Removal is optional and should target exactly that disposable directory only. Never use a broad recursive deletion command or an unresolved variable as the target.
Reactivate the working environment after the check:
```bash
source .venv/bin/activate
python resolute_probe.py
```
## Python 3.14 dependency readiness
Step 2 deliberately installs no third-party distributions. Python 3.14 is newer than the Python 3.12 baseline used by Ubuntu 24.04, so an existing project's declared Python range, wheels, native extensions and test suite must explicitly support it.
Do not infer compatibility from a package name or from a successful source download. In Step 3, inspect project metadata and approved indexes, prefer compatible wheels where policy requires them, pin or lock deliberately, and test the real application.
If an application requires an older Python, keep Ubuntu's `/usr/bin/python3` intact. Provision an approved isolated interpreter/container with a documented owner and lifecycle. Never downgrade, replace, divert or repoint Resolute's system Python for one project.
## Operational use without activation
For scripts, CI or service definitions, prefer an explicit interpreter path:
```bash
~/projects/resolute-python-lab/.venv/bin/python ~/projects/resolute-python-lab/resolute_probe.py
```
This is deterministic for the current machine and location. It does not make the environment movable. If the project path, machine, architecture or base interpreter changes, recreate `.venv` from documented inputs.
Avoid a source-file shebang that hard-codes one employee's home path if the project will move between accounts. The service/launcher can specify the environment interpreter, while interactive work activates it.
## Evidence to retain safely
Record only the release/codename, Python version tuple, base and venv executables, prefix/base-prefix distinction, project owner/mode, venv pip location, platform tag, probe result and recreation result.
Redact usernames/home paths when publishing. Do not capture full `env`, tokens, SSH keys, internal repository credentials, customer source, proxy URLs with secrets, machine IDs or broad directory listings.
## Troubleshooting
**Release is not 26.04/resolute.** Stop using this version-specific keyword and follow the actual release guide. Do not relabel files or mix APT suites.
**`python3` is not `/usr/bin/python3` or not 3.14.** Inspect `type -a python3`, PATH, symlinks and dpkg ownership. Identify consumers before changing a custom runtime. Do not force an alias.
**`ensurepip` or venv creation is unavailable.** Complete Step 1 through approved Resolute APT packages. Do not bootstrap system pip from the web.
**Permission denied during creation.** Check `whoami` and `stat` for the project parent. Do not rerun with sudo or recursively chmod the home tree.
**`.venv` already exists.** Inspect its creator/version and project documentation. Do not layer a new environment over unknown files. A reviewed rename/recreation is safer.
**Prefix equals base-prefix inside the supposed venv.** The wrong interpreter is running. Use `.venv/bin/python` directly and inspect command resolution.
**pip points outside `.venv`.** Stop before installs. Use `python -m pip`, confirm `sys.executable`, review PATH and environment variables, and recreate if generated state is suspect.
**Activation does not persist.** Use `source .venv/bin/activate` in the current Bash shell. Executing the activation file in a child process cannot change the parent shell.
**Probe reports another working directory.** Change to the project root or use paths deliberately. Do not use a successful import from an accidental directory as proof.
**Existing dependency rejects Python 3.14.** Treat this as project compatibility work. Do not replace system Python or force unsupported installation flags.
**TLS or SQLite version differs from a screenshot.** Patch versions can change. Require successful imports/operations and current Ubuntu security maintenance, not copied strings.
## What not to do in 26.04 Step 2
- Do not overwrite the generic Ubuntu Step 2 or the earlier 26.04 Step 1.
- Do not create the project or venv with sudo.
- Do not install third-party packages before Step 3's trust and dependency decisions.
- Do not use sudo pip, `--user`, `--break-system-packages`, or system-site-packages.
- Do not change `/usr/bin/python3`, alternatives, symlinks or APT-owned files.
- Do not copy, move, commit, share or repair `.venv`; recreate it.
- Do not keep WSL Linux environments under `/mnt/c` or reuse a Windows venv.
- Do not add unconditional activation to shell startup files.
- Do not expose secrets through logs or initialize/push a customer repository without approval.
| Ubuntu 26.04 Step 2 gate | Pass condition | Corrective direction |
|---|---|---|
| identity | 26.04 Resolute confirmed | use actual-release guide |
| base | dpkg-owned `/usr/bin/python3`, version 3.14 | repair Step 1 first |
| ownership | project and venv belong to normal user | correct parent workflow |
| direct proof | `.venv/bin/python`, isolated prefix | inspect/recreate venv |
| active proof | PATH, executable and pip all in `.venv` | activate current Bash shell |
| standard library | probe reports Linux, 3.14 and isolation | inspect exact failure |
| source boundary | venv/caches ignored, source retained | fix project ignore rules |
| recreation | independent `.venv-check` passes | repair base or instructions |
## Ubuntu 26.04 LTS Python Setup Step 2 completion gate
Step 2 is complete only when the actual machine proves 26.04 Resolute and Python 3.14; the normal user owns `~/projects/resolute-python-lab`; `.venv` was created from `/usr/bin/python3` without sudo; direct and activated execution both show a project executable, distinct prefix and venv-local pip; the standard-library probe passes; generated state is ignored; deactivation restores the Ubuntu base; and `.venv-check` proves clean independent recreation.
Final compact evidence, run from the project root:
```bash
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
python3 --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip --version
.venv/bin/python -m pip check
.venv/bin/python resolute_probe.py
.venv-check/bin/python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
.venv-check/bin/python resolute_probe.py
stat -c 'owner=%U mode=%A path=%n' . .venv .venv-check
```
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 3**: establish trusted package-index/proxy/CA policy, evaluate Python 3.14 compatibility and wheel availability, define project metadata and constraints, install only approved dependencies into `.venv`, lock reproducibly, audit, test and capture a redacted dependency baseline.
**Ubuntu 26.04 LTS Python Setup Step 2 succeeds when a normal-user-owned project can repeatedly produce an isolated Python 3.14 environment from Resolute's untouched APT-managed base, with executable, prefix, pip, source and recreation evidence proving the boundary.**
**Ubuntu 26.04 LTS Python Setup Step 3 is to qualify and install a Python 3.14-compatible third-party dependency only inside the Step 2 `.venv`, prove its source, wheel, metadata, import and graph, record reviewed requirements, and reproduce the result in a clean environment.** Resolute's APT-managed `/usr/bin/python3` remains unchanged.
This lab continues `~/projects/resolute-python-lab` and uses the PyPA `packaging` library. Its live project metadata declares Python 3.14 support and it can inspect version constraints and wheel compatibility tags without making application network requests. Do not treat the package choice as blanket approval: the customer must approve package identity, source, version, license and use.
| Decision surface | Step 3 policy | Acceptance evidence |
|---|---|---|
| interpreter | Step 2 `.venv` only | executable and unequal prefixes |
| index and TLS | approved organization/PyPI route | effective pip configuration |
| compatibility | Python 3.14 plus local platform | metadata and compatible tags |
| artifact | wheel required for this lab | dry-run report; no source build |
| installation | interpreter-bound pip | distribution under `.venv` |
| intent | reviewed top-level requirement | `requirements.in` |
| resolved state | exact tested versions | `requirements-lock.txt` |
| reproduction | new `.venv-replay` | install, check and probe pass |
## Re-enter the Step 2 project
Start in Ubuntu as the normal user:
```bash
whoami
cd ~/projects/resolute-python-lab
pwd
test -f resolute_probe.py
test -x .venv/bin/python
stat -c 'owner=%U group=%G mode=%A path=%n' . .venv .venv/bin/python
```
Do not continue as root or from a different project. If the project, probe or venv is absent, complete Ubuntu 26.04 LTS Python Setup Step 2 rather than creating partial state here.
If this installation is WSL, remain under the Ubuntu home filesystem. Do not move the project or reuse a Windows `.venv`; environments contain OS-, architecture- and absolute-path-specific artifacts.
## Reconfirm Resolute and Python 3.14
Run:
```bash
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
/usr/bin/python3 --version
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
```
Require Ubuntu 26.04 `resolute`, Python 3.14 for the base and venv, the project `.venv/bin/python` executable, and `True` isolation. Every `python -c` and `python3 -c` command in this guide occupies one physical shell line.
If the venv was made by another Python minor version or moved from another path, recreate it from the verified base according to Step 2. Do not edit `pyvenv.cfg`, repoint launchers or alter `/usr/bin/python3`.
## Activate and prove pip ownership
Run:
```bash
source .venv/bin/activate
command -v python
command -v pip
python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
python -m pip --version
python -m pip check
```
Python, pip and pip's reported library path must be inside `resolute-python-lab/.venv`. Use `python -m pip` for every operation so the selected interpreter owns the installer.
Do not proceed if pip points to `/usr`, `/usr/local`, another project or a user-site directory. Never compensate with sudo, `--user` or `--break-system-packages`.
## Inspect pip configuration and environment
Pip behavior can be changed by global, user, site and environment settings. Inspect before network access:
```bash
python -m pip config debug
python -m pip config list
env | grep -E '^(PIP|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|REQUESTS_CA_BUNDLE|SSL_CERT_FILE)=' || true
python -c "import ssl; print(ssl.get_default_verify_paths())"
date --iso-8601=seconds
```
Review output locally. An organization can require a private index, outbound proxy or managed CA. Use its documented hostname and credential mechanism. Do not paste tokens, passwords, authenticated URLs, complete proxy values or CA material into tickets, shell history, requirements files or source control.
The default public-index path may be appropriate for an authorized lab, but it is not an automatic customer policy. Mixing an internal index with a public extra index can permit dependency confusion if naming and precedence controls are weak. Prefer one approved source of truth or a controlled proxy that owns namespace policy.
Do not use `--trusted-host`, plain HTTP, disabled certificate verification or an unreviewed certificate bundle. TLS errors are evidence to diagnose, not obstacles to bypass.
## Record the local compatibility target
Run:
```bash
python -c "import platform, sys, sysconfig; print(platform.python_version()); print(sys.implementation.name); print(sysconfig.get_platform())"
python -m pip debug --verbose
```
The verbose command lists interpreter details and compatible wheel tags. It can be long; retain only the Python version, architecture/platform and first relevant tags after redaction. A wheel filename is installable only when its Python/ABI/platform tags intersect this interpreter's supported tags.
Python 3.14 support must be explicit in project metadata such as `Requires-Python`, classifiers, release notes or upstream tests. Classifiers are supporting evidence; the actual release metadata, artifacts and tests remain authoritative.
Do not install a wheel built for Windows, macOS, another CPU, another libc policy or an incompatible CPython ABI merely because the project name matches.
## Review package identity before installation
The intended distribution is exactly `packaging`, maintained in the Python Packaging Authority ecosystem. Before approving it, review the current project page, verified source/maintainers, release history, `Requires-Python`, Python 3.14 declaration, license, release files, hashes and security process through the organization's approved workflow.
Guard against typosquatting and dependency confusion. Distribution names are normalized for matching, so punctuation/case variations are not separate proof of identity. Do not copy a near-name from a blog, advertisement, issue comment or unsolicited command.
This tutorial deliberately avoids a hard-coded “latest” version because available releases can change. The machine will resolve a candidate at execution time, preserve the dry-run plan, and then record the exact version actually tested.
## Ask pip to plan a wheel-only install
Remove no existing packages yet. First ensure `packaging` is not already present in this new lab:
```bash
python -m pip show packaging || true
```
If it is already installed, stop and identify when, why and from which declaration it arrived. Do not uninstall unknown project state just to match the tutorial.
Create a machine-readable plan without installation:
```bash
python -m pip install --dry-run --ignore-installed --only-binary=:all: --report packaging-install-plan.json packaging
```
The command can contact the configured index and download metadata/artifacts, but it must not install. `--only-binary=:all:` refuses source distributions, avoiding an unreviewed source build in this bounded lab. A source distribution is not inherently malicious; it simply adds build backend, compiler, header and code-execution surfaces that require a separate review.
Inspect the report without dumping authenticated configuration:
```bash
python -c "import json; p=json.load(open('packaging-install-plan.json', encoding='utf-8')); print([(x['metadata']['name'], x['metadata']['version'], x['download_info']['url'].split('/')[2], x['download_info']['archive_info'].get('hash')) for x in p['install']])"
```
Confirm the normalized name is `packaging`, the version is approved, the host matches the approved source, the URL is HTTPS, and a SHA-256 artifact hash is present. The report may contain source URLs and environment details; review it before retaining or sharing.
If no compatible binary distribution is found, stop. Do not remove `--only-binary`, force an incompatible file, or install compilers until the customer approves a source-build path.
## Install only into `.venv`
After approval, run:
```bash
python -m pip install --only-binary=:all: packaging
```
Do not add `--upgrade`, because this step is an initial reviewed install and broad upgrades can change unrelated packages. Do not invoke bare pip, sudo, system Python pip, `--user`, `--no-deps`, `--force-reinstall` or `--break-system-packages`.
The package currently has a small graph, but never assume a distribution has no dependencies. Pip's resolver output and installed metadata are the evidence.
## Prove installed identity and location
Run:
```bash
python -m pip show packaging
python -c "import importlib.metadata as m; d=m.distribution('packaging'); print(d.metadata['Name']); print(d.version); print(d.locate_file('')); print(d.metadata.get('Requires-Python')); print(list(d.requires or []))"
python -c "import packaging; print(packaging.__version__); print(packaging.__file__)"
python -m pip check
```
Pass conditions:
- distribution name is exactly `packaging`;
- the installed version equals the approved plan;
- distribution and import paths reside under this `.venv`;
- `Requires-Python` accepts 3.14;
- declared requirements match the reviewed graph;
- `pip check` reports no broken requirements.
The distribution name and import name happen to match here. That is not universal: always use distribution metadata for ownership and import paths for runtime resolution.
## Detect local shadowing and path leakage
Run:
```bash
find . -maxdepth 2 -type f -name 'packaging.py' -o -type d -name 'packaging'
python -c "import sys; print('\n'.join(sys.path))"
env | grep '^PYTHON' || true
```
An unexpected local `packaging.py` or `packaging/` can shadow the installed distribution. A global `PYTHONPATH` can inject unrelated code despite venv activation. Investigate ownership and intent before renaming or changing environment variables.
Do not print all environment variables. Broad dumps can expose cloud credentials, tokens and internal endpoints.
## Create an offline compatibility probe
Create `dependency_probe.py` with this content:
```python
from __future__ import annotations
import json
import platform
import sys
from importlib.metadata import distribution
from packaging.specifiers import SpecifierSet
from packaging.tags import sys_tags
from packaging.version import Version
def main() -> None:
installed = distribution("packaging")
current = Version(platform.python_version())
required = installed.metadata.get("Requires-Python") or ""
compatible = not required or current in SpecifierSet(required)
first_tags = [str(tag) for tag in list(sys_tags())[:5]]
evidence = {
"base_prefix": sys.base_prefix,
"compatible": compatible,
"distribution": installed.metadata["Name"],
"isolated": sys.prefix != sys.base_prefix,
"python": str(current),
"requires_python": required,
"tags": first_tags,
"version": installed.version,
}
print(json.dumps(evidence, indent=2, sort_keys=True))
if __name__ == "__main__":
main()
```
Run:
```bash
python dependency_probe.py
.venv/bin/python dependency_probe.py
python -m compileall -q dependency_probe.py
```
Both executions must report distribution `packaging`, Python 3.14, `compatible: true`, `isolated: true`, the installed version and local compatible tags. The probe performs no external request and reads no customer data.
Do not mistake this small proof for application validation. Real dependencies need their actual imports, APIs, integration tests and failure paths exercised under 3.14.
## Separate direct intent from resolved state
Create an exact top-level declaration from installed metadata rather than typing a stale version:
```bash
python -c "from importlib.metadata import version; print(f'packaging=={version(\"packaging\")}')" > requirements.in
```
Inspect it:
```bash
sed -n '1,40p' requirements.in
```
`requirements.in` records the dependency the project intentionally chose. This lab pins the approved tested version exactly. In a larger project, direct intent can use a reviewed compatible range, while a generated lock/snapshot captures the exact resolution.
Capture the complete installed distribution snapshot:
```bash
python -m pip freeze > requirements-lock.txt
sed -n '1,120p' requirements-lock.txt
```
Review every line. The lock must contain pinned versions and no local employee paths, editable surprises, authenticated URLs, unapproved indexes or unexpected packages. `pip freeze` reports installed state; it does not prove why packages are present, artifact integrity, source trust or cross-platform portability.
Do not generate a lock from a long-lived contaminated environment and call it intent. Here the Step 2 venv began clean and the before/after state is explicit.
## Compare declarations with metadata
Run:
```bash
python -m pip list
python -m pip check
python -c "from importlib.metadata import distributions; print(sorted((d.metadata['Name'], d.version) for d in distributions()))"
```
Account for venv bootstrap tooling such as pip separately from application dependencies. Exact bootstrap versions do not belong in the project declaration unless the build process explicitly manages them.
For larger graphs, adopt an approved resolver/lock workflow instead of manually editing transitive pins. Environment markers and platform-specific dependencies can legitimately differ across operating systems and Python versions, so define the lock's target scope.
## Add generated-state exclusions
Ensure the project-root `.gitignore` includes:
```gitignore
.venv/
.venv-check/
.venv-replay/
wheelhouse/
__pycache__/
*.py[cod]
```
Decide whether `packaging-install-plan.json` is retained as reviewed evidence or excluded because it exposes internal topology. Requirements and source normally belong in source control after security review; environments, caches and wheelhouses do not.
Do not initialize a repository, add a remote, commit or push customer files without authorization.
## Reproduce in a clean Python 3.14 environment
Deactivate before creating the replay environment:
```bash
deactivate
test ! -e .venv-replay
/usr/bin/python3 -m venv .venv-replay
.venv-replay/bin/python --version
.venv-replay/bin/python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
```
The `test` prevents accidental reuse. If `.venv-replay` exists, inspect it and choose a reviewed new target; do not overlay unknown state.
Inspect replay pip configuration because site/environment/global settings can differ:
```bash
.venv-replay/bin/python -m pip config debug
.venv-replay/bin/python -m pip --version
```
Install the reviewed exact snapshot with the same wheel-only rule:
```bash
.venv-replay/bin/python -m pip install --only-binary=:all: -r requirements-lock.txt
.venv-replay/bin/python -m pip check
.venv-replay/bin/python dependency_probe.py
```
The replay must report Python 3.14, true isolation, the same approved distribution version and compatible tags. Compare snapshots:
```bash
.venv-replay/bin/python -m pip freeze > requirements-replay.txt
diff -u requirements-lock.txt requirements-replay.txt
```
An empty diff is expected for this same-platform replay. Review marker, bootstrap, index and platform differences before declaring a mismatch harmless.
Do not copy `.venv` into `.venv-replay`; the purpose is independent resolution and installation from declarations.
## Optional artifact and hash hardening
Exact versions improve repeatability but do not fully bind artifact bytes. Pip's secure-install guidance supports hash-checking mode, where every requirement and dependency is pinned and carries an approved hash. Organizations can also provide a controlled wheelhouse or private index.
For a reviewed same-platform wheel bundle, use an exact temporary directory and approved retention process:
```bash
mkdir wheelhouse
.venv/bin/python -m pip download --only-binary=:all: --dest wheelhouse -r requirements-lock.txt
.venv/bin/python -m pip hash wheelhouse/*
```
Review hashes against the approved index/release evidence before constructing a hash-locked file. Do not automatically paste output into production policy: multiple platforms may require multiple wheel hashes, and all transitive requirements must be hashed. Hash-checking is all-or-nothing.
Wheelhouses are platform-specific build artifacts. Do not commit them by default, assume they work on another architecture, or distribute them without provenance, license and malware policies.
## Upgrade and rollback policy
Never use an unbounded `pip install --upgrade` as routine maintenance. For an upgrade:
1. review the new release, Python 3.14 metadata, artifacts and advisories;
2. plan in a disposable environment;
3. update the direct declaration deliberately;
4. resolve and capture a new exact snapshot;
5. run unit, integration and application tests;
6. retain the previous declaration/snapshot for rollback;
7. promote through the customer's normal review process.
Rollback means recreating from the previously reviewed snapshot, not mutating a damaged venv until it resembles an old screenshot.
Do not downgrade Ubuntu's Python to satisfy a dependency. Use a separately managed, approved interpreter/container if the project cannot yet support 3.14.
## APT, pip and application boundaries
APT owns Ubuntu's default Python and system packages. Project venv pip owns Python distributions needed by this project. A standalone Python CLI may later use pipx. These lifecycles must not be mixed casually.
If a Python dependency needs a native system library, review its upstream build/runtime documentation and install the smallest approved Resolute APT packages. Do not infer package names from another Ubuntu release or paste arbitrary compiler commands from an error message.
Installation/build hooks execute third-party code with the current user's access. Never build unreviewed packages as root. Sandboxing, CI isolation and artifact scanning may be required for higher-risk customers.
## Evidence to retain safely
Retain the redacted Python/platform target, effective approved index hostname, package name/version/source, wheel filename/hash, `Requires-Python`, dependency metadata, import location, `pip check`, probe output, reviewed declarations and replay diff.
Exclude credentials, full proxy URLs, internal topology, home usernames, tokens, cookies, CA private material, complete environment dumps and unrelated installed software inventories.
## Troubleshooting
**Externally managed environment.** The wrong interpreter owns pip. Use `.venv/bin/python -m pip`; never bypass PEP 668 protection.
**Package already installed before the plan.** Identify the declaration or action that introduced it. Preserve evidence; do not uninstall unknown state reflexively.
**TLS or proxy failure.** Check time, DNS, approved proxy, CA deployment and index URL. Do not use trusted-host, HTTP or disabled verification.
**Authentication failure.** Use the organization's credential provider and least privilege. Do not place tokens in requirements, URLs, shell history or screenshots.
**No matching wheel.** Inspect `Requires-Python`, release files and `pip debug` tags. The package/release may not support Python 3.14 or this platform. Do not force a foreign wheel.
**Resolver reports no matching distribution.** Verify normalized spelling, index contents, yanked releases, version policy and platform tags. Do not add random extra indexes.
**Source build is requested.** The wheel-only gate correctly stopped it. Begin a separately approved source-build assessment instead of removing the guard.
**Import comes from the project directory.** A local module shadows the distribution. Review and rename the project module deliberately; do not alter site-packages.
**`pip check` fails.** Resolve declared version conflicts and rebuild. Do not ignore the graph or use `--no-deps` to conceal it.
**Replay differs.** Compare Python patch/minor, platform, effective pip configuration, index state, markers, snapshot contents and whether the target was truly empty.
**Requirements contain URLs or local paths.** Stop before commit. Determine their origin, remove unauthorized sources, rebuild cleanly and regenerate.
**Python 3.14 is rejected.** Treat it as an application compatibility decision. Keep Resolute's system Python intact and use an approved isolated runtime strategy.
## What not to do in 26.04 Step 3
- Do not overwrite generic Ubuntu Step 3 or the 26.04 Steps 1–2.
- Do not use system pip, sudo pip, user installs or `--break-system-packages`.
- Do not disable TLS or mix public/private indexes without namespace controls.
- Do not install a package before reviewing identity, metadata and artifacts.
- Do not remove the wheel-only gate merely to make an unsupported release install.
- Do not trust an import without proving distribution metadata and import location.
- Do not confuse direct intent, resolved state, artifact hashes and source trust.
- Do not copy environments; reproduce them from reviewed declarations.
- Do not commit credentials, `.venv`, caches, wheelhouses or unreviewed reports.
- Do not change Ubuntu's Python to solve project compatibility.
| Ubuntu 26.04 Step 3 gate | Pass condition | Corrective direction |
|---|---|---|
| interpreter | Python/pip belong to Step 2 `.venv` | return to Step 2 |
| trust | approved HTTPS index/proxy/CA | repair configuration |
| Python 3.14 | metadata and wheel tags compatible | choose supported release |
| install | approved wheel only under `.venv` | inspect plan/artifact |
| runtime | metadata, import, probe and check pass | fix shadow/graph |
| declarations | intent and exact snapshot reviewed | regenerate cleanly |
| reproduction | `.venv-replay` matches and passes | find hidden state |
| security | no sudo, bypass, secrets or system change | stop and remediate |
## Ubuntu 26.04 LTS Python Setup Step 3 completion gate
Step 3 is complete only when the project `.venv` owns Python and pip; effective source/TLS/proxy/CA policy is reviewed; local Python 3.14 and wheel tags are recorded; the `packaging` candidate's identity, `Requires-Python`, wheel and hash are approved; installation remains inside `.venv`; metadata, import location, consistency and the offline probe pass; direct intent and exact resolved state are reviewed; and `.venv-replay` independently installs and produces the same tested result without modifying Ubuntu's Python.
Final compact evidence from the project root:
```bash
source .venv/bin/activate
python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
python -m pip config debug
python -m pip show packaging
python -c "import packaging; print(packaging.__version__); print(packaging.__file__)"
python -m pip check
python dependency_probe.py
sed -n '1,40p' requirements.in
sed -n '1,120p' requirements-lock.txt
.venv-replay/bin/python -m pip check
.venv-replay/bin/python dependency_probe.py
diff -u requirements-lock.txt requirements-replay.txt
```
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 4**: configure an Ubuntu-native editor to use this exact `.venv/bin/python`, then prove terminal, Run, Debug, language analysis and tests all share the same Python 3.14 project environment without granting an editor authority over system Python or package trust.
**Ubuntu 26.04 LTS Python Setup Step 3 succeeds when an approved Python 3.14-compatible wheel is installed only in the project venv, its trust and runtime evidence are explicit, and reviewed declarations reproduce the same graph in a second clean Resolute environment.**
**Ubuntu 26.04 LTS Python Setup Step 4 is to connect an approved native Ubuntu VS Code installation to the existing `resolute-python-lab/.venv`, then prove that the integrated terminal, Run command, debugger, language analysis and Test Explorer all use the same isolated Python 3.14 environment.** The editor does not create another environment, install project dependencies, or gain authority over Resolute's system Python.
This page targets Ubuntu Desktop running VS Code locally. It is intentionally separate from the Windows WSL remote-development series. A headless server, SSH target, container or WSL installation needs a host/client ownership design before following GUI instructions.
| Surface | Required owner | Parity evidence |
|---|---|---|
| Ubuntu runtime | APT/dpkg | `/usr/bin/python3`, expected 3.14 |
| project runtime | Step 2 venv | `.venv/bin/python` and isolated prefix |
| editor application | approved VS Code package | package owner, version and update channel |
| Python tooling | trusted Microsoft publisher | exact extension IDs and versions |
| terminal and Run | selected workspace environment | matching executable/prefix/probe |
| debugger | selected environment via `debugpy` | breakpoint plus matching runtime |
| analysis | Pylance/workspace import graph | `packaging` resolves in `.venv` |
| tests | standard-library unittest | terminal and Test Explorer agree |
## Qualify the machine before installing a GUI editor
Run as the normal Ubuntu user:
```bash
whoami
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
printf 'desktop=%s session=%s\n' "${XDG_CURRENT_DESKTOP-}" "${XDG_SESSION_TYPE-}"
systemd-detect-virt 2>/dev/null || true
uname -m
```
Require Ubuntu 26.04 `resolute` and a supported interactive desktop session. If the desktop/session variables are empty because this is a server, SSH session, container or minimal image, stop. Do not add an entire GUI stack to a customer server merely to satisfy this keyword.
For WSL, follow the Windows-host/Ubuntu-server VS Code Remote workflow instead. For SSH/cloud, decide whether a trusted client plus Remote-SSH is approved. Those architectures install extensions and execute code in different places.
## Reconfirm the Step 3 project
Run:
```bash
cd ~/projects/resolute-python-lab
test -x .venv/bin/python
test -f dependency_probe.py
test -f requirements-lock.txt
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip show packaging
.venv/bin/python -m pip check
.venv/bin/python dependency_probe.py
```
Require Python 3.14, an executable inside this project's `.venv`, true isolation, the reviewed `packaging` distribution, a consistent graph and successful offline probe. Every `python -c`/`python3 -c` example here is one physical line.
Do not use editor setup to repair Step 2 or Step 3. If the venv or declarations are missing or inconsistent, return to the owning step.
## Decide the VS Code package owner
First inspect existing commands and packages:
```bash
command -v code || true
type -a code 2>/dev/null || true
snap list code 2>/dev/null || true
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' code 2>/dev/null || true
```
If VS Code already exists, identify whether it is the Microsoft `.deb` repository package, the verified classic Snap, another organizational package, a community build, or a manually unpacked binary. Do not install a second copy over it. Multiple `code` owners create mismatched extensions, settings, PATH entries and update channels.
Official VS Code documentation offers Debian/Ubuntu `.deb` and Snap packages. Choose one approved update lifecycle. The commands below use the verified Snap channel because it is simple for a fresh Ubuntu Desktop, but classic confinement grants broad host access and must be accepted by customer policy.
## Inspect and install the verified Snap option
Inspect before mutation:
```bash
snap info code
```
Review publisher verification, confinement, tracking channel and current release. The package should be the official Visual Studio Code Snap, not a similarly named project.
If approved and not already installed:
```bash
sudo snap install code --classic
```
Review the command and any policy prompts. `--classic` is required by this packaging model because an editor/toolchain needs broad access to user projects, shells, interpreters, Git and debuggers. It is not the same isolation boundary as a strict snap.
Do not install the Snap and `.deb` simultaneously. Do not pipe a downloaded installation script into a root shell, add an unsigned repository, or use a random mirror.
Organizations that standardize on the Microsoft `.deb` must follow the official repository/key and update policy instead; do not improvise repository configuration from an old article.
## Verify the editor installation
Close/reopen the terminal if command discovery is stale, then run:
```bash
command -v code
readlink -f "$(command -v code)"
code --version
snap list code
snap info code | sed -n '1,80p'
```
Record the VS Code version, architecture, Snap revision/channel and verified publisher without exposing the username/home path. Snap revisions change as updates ship; do not use a screenshot's revision as the acceptance target.
If the customer uses the `.deb`, replace Snap evidence with `dpkg-query`, `apt-cache policy code`, the signed source/key owner and the official update channel.
## Review editor trust, updates and telemetry
VS Code and extensions execute with the user's access to source, shell, credentials and network. Before opening customer code, establish:
- who approves editor and extension publishers;
- automatic versus staged update policy;
- Marketplace/network access policy;
- telemetry/privacy setting and organizational management;
- Settings Sync ownership and whether customer settings may leave the device;
- Workspace Trust expectations;
- prohibited extension categories and credential access.
Do not sign in with a personal Microsoft/GitHub account or enable Settings Sync on a customer machine without authorization. Do not disable updates indefinitely; use an owned patching process.
## Install only the reviewed Python extension
List current extensions first:
```bash
code --list-extensions --show-versions | sort
```
If `ms-python.python` is absent and Marketplace access is approved:
```bash
code --install-extension ms-python.python
```
The exact ID matters. Verify afterward:
```bash
code --list-extensions --show-versions | grep -E '^ms-python\.(python|debugpy|vscode-pylance|vscode-python-envs)@'
```
Microsoft's Python extension can install optional companion extensions for Pylance, Python Debugger and Python Environments. Review the actual list and versions. Optional dependencies and rollout/enablement can evolve; missing components should be installed only from their exact trusted publisher IDs when the needed feature is approved.
Do not install an extension pack or a generic “Code Runner” to make a button appear. Third-party runners frequently own a separate command template and can bypass the selected Python environment.
Offline or allowlisted customers should use an organization-controlled VSIX acquisition, integrity and update process. Do not download VSIX files from reposting sites.
## Open exactly the project folder
From the Ubuntu shell:
```bash
cd ~/projects/resolute-python-lab
code .
```
The workspace root in Explorer must be `resolute-python-lab`, not `~/projects`, the home directory, `/`, or a parent containing unrelated customer data. A narrow root improves interpreter discovery, search, trust review and accidental-disclosure boundaries.
If Workspace Trust appears, inspect the folder and its files before trusting. Trust only customer-owned reviewed source. A workspace can contain tasks, debug configurations and extensions that execute code.
Do not use “Open Recent” blindly; confirm the exact folder in the title/Explorer and integrated terminal.
## Discover and select the existing `.venv`
Open a Python file. In VS Code:
1. Open the Command Palette with `Ctrl+Shift+P`.
2. Run **Python: Select Interpreter**.
3. Choose the interpreter whose path ends in `resolute-python-lab/.venv/bin/python` and whose version is Python 3.14.
4. Confirm the status bar/environment control shows the project `.venv`.
Workspace-local `.venv` folders are normally discovered automatically. If missing, run **Python Environments: Refresh All Environment Managers**. If still absent, enter the exact existing interpreter path through the selection workflow; do not create another environment from the editor.
The extension's environment-management UI can create/delete venvs and manage packages. Those actions are intentionally out of scope because Steps 2–3 already own creation, trust, declarations and reproduction. Do not click Quick Create, Delete Environment or Manage Packages for this project.
## Avoid personal absolute interpreter paths in shared settings
Modern Python Environments project mappings are designed to associate a workspace project with an environment manager without committing one employee's absolute home path. Make the explicit UI selection and review any `.vscode/settings.json` change before source control.
Do not add a shared setting such as:
```text
"python.defaultInterpreterPath": "/home/alice/projects/resolute-python-lab/.venv/bin/python"
```
That path leaks a username, breaks on teammates' machines and can survive after environment recreation in confusing ways. A relative legacy setting may work in some configurations, but the current selected-environment/project mechanism is preferred; record the expected `.venv` convention in project documentation.
## Prove a fresh integrated terminal
Kill terminals created before interpreter selection. Open **Terminal: Create New Terminal**, then run:
```bash
pwd
printf 'VIRTUAL_ENV=%s\n' "${VIRTUAL_ENV-}"
command -v python
command -v pip
python --version
python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
python -m pip --version
python -m pip check
python dependency_probe.py
```
The working directory must be the project, commands must resolve under `.venv`, Python must report 3.14, isolation must be true, and the Step 3 probe must pass.
Terminal auto-activation affects newly created terminals. Selecting an interpreter does not retroactively change an old terminal's PATH. Prompt text is not proof; compare executable and prefix.
If organization policy disables auto-activation, use `source .venv/bin/activate` explicitly or `.venv/bin/python`. Do not alter global shell startup files for one project.
## Create one cross-surface editor probe
Create `editor_probe.py`:
```python
from __future__ import annotations
import json
import os
import sys
from importlib.metadata import version
from pathlib import Path
def snapshot(surface: str) -> dict[str, object]:
return {
"base_prefix": sys.base_prefix,
"cwd": str(Path.cwd()),
"executable": sys.executable,
"isolated": sys.prefix != sys.base_prefix,
"packaging": version("packaging"),
"python": f"{sys.version_info.major}.{sys.version_info.minor}",
"surface": surface,
"virtual_env": os.environ.get("VIRTUAL_ENV", ""),
}
def main() -> None:
evidence = snapshot("editor")
print(json.dumps(evidence, indent=2, sort_keys=True))
if __name__ == "__main__":
main()
```
Run in the integrated terminal:
```bash
python editor_probe.py
```
Expected evidence includes Python `3.14`, the project `.venv/bin/python`, true isolation, the Step 3 `packaging` version and project working directory. `VIRTUAL_ENV` can prove activation state, but executable/prefix prove interpreter ownership even when activation is not used.
## Prove the Run surface
Open `editor_probe.py`, then use **Python: Run Python File in Terminal** from the Command Palette or the Python run button. Do not use a third-party runner.
Compare its JSON with the explicit terminal run:
- executable must identify the same project `.venv`;
- Python must be 3.14;
- isolated must be true;
- dependency version and working directory must agree.
The Run command can create/reuse a terminal. Read the actual invoked command and output. A green triangle by itself is not evidence.
## Add a portable debug configuration
Create `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Python 3.14: Editor probe",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/editor_probe.py",
"console": "integratedTerminal",
"cwd": "${workspaceFolder}",
"justMyCode": true
}
]
}
```
The configuration intentionally omits a `python` property, so VS Code's selected workspace environment remains authoritative. It uses portable workspace variables rather than a personal absolute path.
Do not use legacy debugger type `python`; current Python debugging uses `debugpy`. Do not add `sudo`, shell wrappers, secrets, tokens, production hosts or an alternate interpreter to make debugging pass.
## Qualify the debugger
Set a breakpoint on the line assigning `evidence` in `main()`. Select **Python 3.14: Editor probe** and press F5.
At the breakpoint, inspect in Debug Console:
```python
sys.executable
sys.version_info
sys.prefix
sys.base_prefix
version("packaging")
str(Path.cwd())
```
Require the same `.venv` executable, Python 3.14, unequal prefixes, approved dependency version and project directory. Continue and require the same final JSON as Run/terminal.
Debug Console expressions are Python, not Bash. Do not paste shell commands or secrets there. Screenshots can expose paths and source; redact before sharing.
If a breakpoint stays hollow/unbound, confirm the open file equals the configured program, the debugger extension is enabled, the selected configuration is correct and the process has reached the line.
## Prove language-analysis parity
Open `editor_probe.py` and verify:
- no unresolved-import diagnostic for `packaging` metadata use;
- hover/navigation resolves standard-library symbols for Python 3.14;
- completion on `sys.version_info` and `Path` behaves normally;
- Problems contains no false missing-import error caused by another interpreter.
Pylance provides language analysis; it does not execute application code or prove runtime behavior. Terminal/Run/Debug evidence remains necessary.
Do not silence a missing import with broad `python.analysis.extraPaths`, a global `PYTHONPATH`, or workspace-wide diagnostic suppression. Select the correct environment and fix the actual package/declaration boundary.
If type checking is enabled, choose its level deliberately. Do not turn strict analysis on for an unprepared customer codebase and then mass-suppress the findings.
## Add a standard-library parity test
Create `tests/test_editor_probe.py`:
```python
from __future__ import annotations
import sys
import unittest
from editor_probe import snapshot
class EditorProbeTests(unittest.TestCase):
def test_selected_environment(self) -> None:
evidence = snapshot("test")
self.assertEqual(evidence["python"], "3.14")
self.assertTrue(evidence["isolated"])
self.assertIn(".venv", str(evidence["executable"]))
self.assertTrue(str(evidence["packaging"]))
self.assertNotEqual(sys.prefix, sys.base_prefix)
if __name__ == "__main__":
unittest.main()
```
Run the terminal authority first:
```bash
python -m unittest discover -v -s tests -p 'test_*.py'
```
This adds no dependency because `unittest` is in Python's standard library. A passing result proves the process sees Python 3.14, isolation and the reviewed Step 3 distribution.
## Configure Test Explorer without changing dependencies
Create or merge `.vscode/settings.json` carefully:
```json
{
"python.testing.pytestEnabled": false,
"python.testing.unittestEnabled": true,
"python.testing.unittestArgs": [
"-v",
"-s",
"./tests",
"-p",
"test_*.py"
]
}
```
Do not overwrite existing customer settings. Parse/merge valid JSON and review the diff. The file contains test policy only—no username, interpreter path, secret, package-install command or personal preference.
Open Testing, refresh discovery, and run `test_selected_environment`. Require one discovered passing test. Debug the test and confirm `sys.executable` is again the project `.venv` if test-debug parity is in scope.
If pytest is the real project standard, install and declare it through the Step 3 trust/lock workflow before enabling pytest. Do not let a UI prompt install undeclared tooling.
## Compare all five surfaces
Retain redacted evidence for:
1. integrated terminal `python editor_probe.py`;
2. **Python: Run Python File in Terminal**;
3. F5 debug at the breakpoint and completion output;
4. Pylance import/hover/navigation state;
5. Test Explorer plus terminal unittest result.
Terminal, Run, Debug and tests must agree on executable, Python 3.14, isolation, dependency version and project cwd. Analysis must resolve against the selected project environment.
A surface that merely “works” with `/usr/bin/python3` fails parity because it bypasses Step 3's dependency graph.
## Review workspace files and source-control boundaries
Inspect:
```bash
find .vscode tests -maxdepth 2 -type f -print 2>/dev/null
sed -n '1,200p' .vscode/launch.json
sed -n '1,200p' .vscode/settings.json
git status --short 2>/dev/null || true
```
Review `.vscode/launch.json`, settings, test and source files before commit. Portable team policy can be shared; personal paths, machine IDs, credentials and private endpoints cannot.
Keep `.venv/`, `.venv-check/`, `.venv-replay/`, caches and local secret files ignored. Do not ignore the entire `.vscode` directory automatically: decide which settings/configurations are team-owned.
Do not initialize Git, connect a remote, commit or push without customer authorization.
## Secrets and environment files
Do not create a real `.env` merely to test editor injection. VS Code can load environment files into some Python surfaces, and current terminal injection behavior depends on settings. That can intentionally make environments differ.
When the application later needs secrets, define one approved secret source, ignore local secret files, use placeholders/examples, document which surfaces load them, and test that terminal/Run/Debug/test behavior is intentional. Never place secrets in `settings.json`, `launch.json`, tasks, source or screenshots.
## Extension and workspace security
An extension can read files, execute processes and communicate over the network with the user's authority. A trusted publisher is one input, not a guarantee that every update is automatically approved for every customer.
Review extension versions, changelogs, permissions/behavior, telemetry and update cadence. Use allowlists/managed policies where required. Remove unowned extensions rather than disabling security controls to accommodate them.
Workspace Trust reduces risk from untrusted folders but is not a sandbox for trusted ones. Inspect tasks, launch configurations, settings, notebooks and scripts before execution.
## Upgrade and recreation behavior
After a VS Code/Python-extension update, repeat the compact parity gate. Environment discovery, terminal activation and debugger behavior can evolve.
If `.venv` is recreated at the same project convention, refresh environment discovery and select it again if necessary. Do not repair editor caches by copying an old environment or hard-coding its obsolete absolute interpreter.
Record editor/extension versions with test evidence, not as eternal pins. Customer patch/security policy owns updates.
## Troubleshooting
**No desktop session.** Stop the native-GUI workflow. Choose an approved remote client architecture instead of installing a desktop on a server.
**`code` has multiple owners.** Identify command resolution, Snap/dpkg/manual installs, profiles and update channels. Do not delete one until settings/extensions/data ownership is understood.
**Snap install is blocked.** Follow organizational packaging policy or the official signed `.deb` path. Do not bypass device management.
**Project files are inaccessible to the editor.** Confirm the project is under the normal user's Linux home and inspect Snap interfaces/policy. Do not chmod 777 or run VS Code as root.
**`.venv` is not discovered.** Verify `.venv/bin/python` and `pyvenv.cfg`, refresh environment managers, reopen the exact project root, then select the exact interpreter path. Do not Quick Create another venv.
**Status bar shows `/usr/bin/python3`.** Select the Step 2 `.venv`; reopen fresh terminals and rerun executable/prefix proof.
**Terminal uses the old interpreter.** Kill and recreate it after selection, or activate explicitly. Selection does not rewrite a running shell's PATH.
**Run output differs from terminal.** Confirm the command is **Python: Run Python File in Terminal**, not Code Runner or a task with a hard-coded binary.
**Debugger differs from Run.** Inspect the active `launch.json`, selected configuration and any `python` override. Use `debugpy` and the selected environment.
**Pylance reports missing `packaging`.** Confirm selected environment, import location and extension state. Do not add extra paths or install globally.
**Test Explorer finds no tests.** Compare the saved settings, discovery output, project root, filename pattern and terminal discovery command. Do not install pytest unless declared.
**Test Explorer uses a different Python.** Reselect the environment, refresh tests and inspect logs. Prove with `sys.executable` inside the test.
**Extension install fails.** Check Marketplace allowlist, proxy, CA, DNS, clock and publisher ID. Do not disable TLS or use an unofficial VSIX mirror.
**Python 3.14 analysis/debugging issue.** Record exact editor/extension/Python versions and a minimal reproduction. Do not downgrade Ubuntu's system Python; use an approved isolated project strategy if required.
## What not to do in 26.04 Step 4
- Do not overwrite generic Ubuntu Step 4 or the WSL remote-editor page.
- Do not install a native GUI editor on an unqualified headless server.
- Do not install multiple VS Code package variants/update channels.
- Do not run VS Code, extensions, project creation or pip as root.
- Do not let editor UI recreate `.venv` or install undeclared dependencies.
- Do not select `/usr/bin/python3` for this dependency-owning project.
- Do not use Code Runner, personal absolute paths or broad analysis extra paths.
- Do not hard-code a different debugger interpreter to conceal selection errors.
- Do not place secrets in workspace settings, launch files, terminals or screenshots.
- Do not trust extension packs or workspaces without reviewing their execution authority.
| Ubuntu 26.04 Step 4 gate | Pass condition | Corrective direction |
|---|---|---|
| host | qualified Ubuntu Desktop 26.04 | choose correct remote/native path |
| editor | one approved VS Code owner/channel | reconcile installations |
| extensions | reviewed Microsoft IDs/versions | repair trust/allowlist |
| selection | project `.venv`, Python 3.14 | refresh and reselect |
| execution | terminal, Run and Debug agree | inspect surface owner |
| analysis | imports resolve from selected venv | fix selection, not paths |
| tests | terminal and Test Explorer pass | repair discovery/runtime |
| security | portable settings, no secrets/root | stop and remediate |
## Ubuntu 26.04 LTS Python Setup Step 4 completion gate
Step 4 is complete only when the machine is a qualified Ubuntu 26.04 Desktop; one approved VS Code package/update channel is proven; the exact Microsoft Python tooling IDs and versions are reviewed; the existing `.venv/bin/python` is selected; fresh terminal, Python Run, `debugpy` breakpoint, Pylance analysis and unittest/Test Explorer all agree on Python 3.14, isolated project ownership, dependency version and working directory; workspace configuration is portable and reviewed; and no root editor, system pip, duplicate venv, secret, untrusted extension or personal interpreter path was introduced.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
code --version
code --list-extensions --show-versions | grep -E '^ms-python\.(python|debugpy|vscode-pylance|vscode-python-envs)@'
source .venv/bin/activate
python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
python editor_probe.py
python -m unittest discover -v -s tests -p 'test_*.py'
python -m pip check
```
Also retain the matching Run output, debugger breakpoint values, clean analysis state and Test Explorer pass result.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 5**: establish Git identity and repository ownership, create a privacy-reviewed initial commit containing source, requirements, tests and portable editor policy while proving venvs, caches, reports, credentials and customer-specific paths remain excluded.
**Ubuntu 26.04 LTS Python Setup Step 4 succeeds when an approved native editor consistently uses the same isolated Python 3.14 environment across terminal, Run, Debug, analysis and tests, with portable configuration and explicit extension/workspace trust boundaries.**
**Ubuntu 26.04 LTS Python Setup Step 5 is to create a privacy-reviewed local Git history for `resolute-python-lab`: verify Ubuntu's Git owner, prevent accidental nested-repository scope, configure an approved repository-specific commit identity, prove generated and sensitive files are excluded, stage only an explicit allowlist, run the Python 3.14 gate, create one reviewed commit, and verify integrity with no remote configured.**
This step does not recover an email password, authenticate to a mail service, create a hosting account, add a remote, generate/upload keys, or push customer data. A Git commit email is historical authorship metadata—not an email-login credential—and can become public later.
| Control surface | Step 5 decision | Acceptance evidence |
|---|---|---|
| Git binary | Resolute APT package | executable, version and dpkg owner |
| repository boundary | exact project root | no parent/nested repository |
| commit identity | customer-approved, repo-local | origin/scope and commit headers |
| tracked content | explicit source/config allowlist | staged name/status and diff |
| generated state | ignored, still security-reviewed | `check-ignore` plus inventory |
| credentials/secrets | never tracked | targeted scans and human review |
| quality | same Python 3.14 `.venv` | probes, unittest and pip check |
| publication | none in Step 5 | empty `git remote -v` |
## Re-enter the exact project as the normal user
Run:
```bash
whoami
cd ~/projects/resolute-python-lab
pwd
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
stat -c 'owner=%U group=%G mode=%A path=%n' .
```
Require the expected project path, Ubuntu 26.04 `resolute`, and normal-user ownership. Do not initialize Git as root or use sudo for repository operations.
On WSL, this project must still be under the Ubuntu filesystem. On native Ubuntu, follow the customer's home/storage/backup policy. A repository does not correct unsafe filesystem ownership.
## Prove the Python 3.14 project is complete
Run before adding version control:
```bash
test -x .venv/bin/python
test -f requirements.in
test -f requirements-lock.txt
test -f resolute_probe.py
test -f dependency_probe.py
test -f editor_probe.py
test -f tests/test_editor_probe.py
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip check
.venv/bin/python dependency_probe.py
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
Require Python 3.14, the project `.venv` executable, true isolation, a consistent dependency graph, successful dependency probe and passing tests. Every `python -c`/`python3 -c` example is one physical line.
Do not create a baseline commit for a broken or unexplained environment. Fix the owning setup step first.
## Detect an existing or parent repository
Before `git init`, run:
```bash
git -C . rev-parse --show-toplevel 2>/dev/null || true
git -C .. rev-parse --show-toplevel 2>/dev/null || true
find .. -maxdepth 2 -type d -name .git -print 2>/dev/null
```
If any command identifies an existing repository containing this project, stop. Initializing a nested repository can hide files from the parent, confuse IDE source control, and create accidental submodule/gitlink behavior.
If `resolute-python-lab/.git` already exists, treat Step 5 as an audit of that repository instead of rerunning initialization or replacing metadata. Identify the owner, history, branch, remotes, hooks, worktrees and purpose before mutation.
Do not delete or rename an existing `.git` directory merely to make this tutorial start clean. Git history and configuration may be the only local recovery path.
## Verify or install Ubuntu's Git package
Inspect first:
```bash
command -v git || true
type -a git 2>/dev/null || true
git --version 2>/dev/null || true
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' git 2>/dev/null || true
```
If Git is absent, install from approved Resolute APT sources:
```bash
sudo apt update
sudo apt install git
```
Review the package plan; the page omits `-y`. Verify:
```bash
command -v git
readlink -f "$(command -v git)"
git --version
dpkg -S "$(readlink -f "$(command -v git)")"
```
Do not add a PPA, random binary, unsigned repository or unrelated Git snap just for a newer version. If organizational policy mandates another owner, document and qualify it rather than mixing installations.
## Inspect effective Git configuration before use
Run read-only checks:
```bash
git config --list --show-origin --show-scope
git config --global --get user.name || true
git config --global --get user.email || true
git config --global --get credential.helper || true
git config --system --list --show-origin 2>/dev/null || true
```
Configuration can be system, global, local, worktree, included or command-scoped. Review aliases, hooks paths, signing, credential helpers, URL rewrites, filters, proxies and conditional includes. A malicious or stale config can change what a familiar command executes or where it connects.
Do not publish the complete output if it contains internal URLs, usernames, paths or helper configuration. Do not unset a global setting until its other repositories and owner are understood.
## Understand identity versus authentication
`user.name` and `user.email` are written into author/committer fields of commit objects. They do not authenticate to GitHub, GitLab, Launchpad, a mail server or any remote. Git credentials, SSH keys and email passwords are separate secrets.
Never enter an email password into `git config`, a remote URL, commit message, `.netrc`, source file, VS Code setting or credential-store command. If a customer forgot a mailbox password, use the mail provider's authorized recovery flow; do not search servers for it.
Obtain the exact approved display name and commit address from the customer/repository owner. The address may be an organizational or provider-issued no-reply address. Explain that it remains in history even if configuration changes later.
## Inventory files, symlinks and sizes before initialization
Run:
```bash
find . -maxdepth 3 -mindepth 1 -printf '%y %s %p\n' | sort | sed -n '1,240p'
find . -type l -printf '%p -> %l\n'
du -sh . .venv .venv-check .venv-replay wheelhouse 2>/dev/null || true
```
Review every symlink. Git records a symlink target string, which can expose an internal path or point outside the project when checked out. Do not stage unexplained symlinks.
Large/generated directories should remain excluded. Check unexpected archives, databases, logs, editor backups, certificates, keys, screenshots and install reports. Do not assume ignored means safe: ignored files can still contain secrets requiring secure storage/removal.
## Build the project `.gitignore`
Create or merge a project-root `.gitignore` with these reviewed rules:
```gitignore
# Python environments and replays
.venv/
.venv-check/
.venv-replay/
# Python-generated state
__pycache__/
*.py[cod]
*.egg-info/
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
htmlcov/
build/
dist/
# Dependency artifacts and local evidence
wheelhouse/
packaging-install-plan.json
requirements-replay.txt
# Local secrets and credentials
.env
.env.*
!.env.example
*.pem
*.key
*.p12
*.pfx
# Local editor/OS debris
*.swp
*.swo
*~
.DS_Store
Thumbs.db
```
Merge rather than overwrite the Step 2–4 rules. Do not ignore `requirements.in`, `requirements-lock.txt`, source, tests, README or reviewed portable `.vscode` policy.
Ignore patterns do not affect files already tracked and are not an access control. They reduce accidental staging; ownership, filesystem permissions, secret storage and scans remain necessary.
## Add a narrow `.gitattributes`
Create `.gitattributes`:
```gitattributes
* text=auto
*.py text eol=lf
*.md text eol=lf
*.json text eol=lf
*.txt text eol=lf
```
This makes text normalization policy explicit for a Linux Python project. Do not apply `text` blindly to known binary formats. If the real project adds images, archives, models or fixtures, declare appropriate binary handling after review.
Do not set broad global line-ending behavior solely for this repository; project attributes travel with the source and are auditable.
## Create a privacy-safe README
Create `README.md` with project facts rather than customer secrets:
````markdown
# Resolute Python Lab
Verified Python 3.14 development baseline for Ubuntu 26.04 LTS.
## Recreate
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --only-binary=:all: -r requirements-lock.txt
```
## Verify
```bash
python -m pip check
python dependency_probe.py
python -m unittest discover -v -s tests -p 'test_*.py'
```
The virtual environment is generated locally and is not committed.
````
Do not include customer names, email addresses, hosts, tickets, tokens, private repository URLs, absolute home paths or production endpoints in this baseline README.
## Run a pre-initialization secret review
Search likely text files, including ignored ones, without printing actual secret values into shared logs:
```bash
find . -path './.venv' -prune -o -path './.venv-check' -prune -o -path './.venv-replay' -prune -o -type f -size -2M -print
```
Review the listed files manually. Then run targeted pattern searches locally:
```bash
grep -RInE --exclude-dir=.venv --exclude-dir=.venv-check --exclude-dir=.venv-replay --exclude-dir=.git '(password|passwd|secret|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' . || true
grep -RInE --exclude-dir=.venv --exclude-dir=.venv-check --exclude-dir=.venv-replay --exclude-dir=.git 'https?://[^/[:space:]]+:[^/@[:space:]]+@' . || true
```
Matches require human review and can be benign documentation. Absence of matches does not prove absence of secrets. Use an organization-approved secret scanner if available; do not upload source to an unapproved scanning service.
If a real credential appears, stop. Revoke/rotate it through the owning service, remove it from the file, and rescan before Git history exists. Merely adding the file to `.gitignore` does not remediate exposure.
## Initialize one local repository with an explicit branch
After parent-repository checks pass:
```bash
git init --initial-branch=main
git rev-parse --show-toplevel
git symbolic-ref --short HEAD
stat -c 'owner=%U group=%G mode=%A path=%n' .git
```
Require the exact project root, initial branch `main`, and normal-user-owned `.git`. The explicit branch avoids relying on machine defaults.
Do not use `--shared`, `--bare`, `--separate-git-dir`, alternate object directories or custom templates without a documented repository design.
## Configure approved repository-local identity
Use interactive prompts so the approved values are not embedded in copied documentation or shell history:
```bash
read -r -p 'Approved Git display name: ' GIT_DISPLAY_NAME
read -r -p 'Approved commit email/address: ' GIT_COMMIT_ADDRESS
test -n "$GIT_DISPLAY_NAME" && test -n "$GIT_COMMIT_ADDRESS"
git config --local user.name "$GIT_DISPLAY_NAME"
git config --local user.email "$GIT_COMMIT_ADDRESS"
git config --local user.useConfigOnly true
unset GIT_DISPLAY_NAME GIT_COMMIT_ADDRESS
```
The input is visible at the terminal; email is not a password, but shoulder-surfing and screen recording still matter. If privacy policy forbids display, use an approved configuration method.
Verify scope/origin:
```bash
git config --local --get user.name
git config --local --get user.email
git config --local --get user.useConfigOnly
git config --get --show-origin user.name
git config --get --show-origin user.email
```
Require the repository `.git/config` as effective owner. Repository-local identity prevents a personal/global address from leaking into this customer commit.
Do not set fake authorship, the customer's mailbox password, an unapproved personal address or someone else's identity. If signed commits are mandatory, configure approved signing keys and verification policy before the first commit; do not bypass signing to continue.
## Inspect ignore behavior before staging
Run:
```bash
git status --short --untracked-files=all
git check-ignore -v --no-index .venv/bin/python .venv-check/bin/python .venv-replay/bin/python packaging-install-plan.json requirements-replay.txt 2>/dev/null || true
git status --ignored --short | sed -n '1,200p'
```
Require environments, replay state and local reports to be ignored. Review every untracked and ignored path. `git check-ignore -v` shows the exact pattern/source responsible.
Do not add a broad `*` rule and selectively unignore a few files; it can conceal new source and make review fragile. Do not use `.git/info/exclude` for team policy that must be shared.
## Define the initial tracked allowlist
The intended initial set is:
- `.gitignore` and `.gitattributes`;
- `README.md`;
- `requirements.in` and `requirements-lock.txt`;
- `resolute_probe.py`, `dependency_probe.py`, `editor_probe.py`;
- `tests/test_editor_probe.py`;
- reviewed `.vscode/settings.json` and `.vscode/launch.json`.
If a listed file is absent, stop and reconcile the earlier step. If additional source is legitimate, add it to the reviewed allowlist explicitly; do not let it hitchhike through a recursive add.
Preview staging without changing the index:
```bash
git add --dry-run -- .gitignore .gitattributes README.md requirements.in requirements-lock.txt resolute_probe.py dependency_probe.py editor_probe.py tests/test_editor_probe.py .vscode/settings.json .vscode/launch.json
```
Do not use `git add .`, `git add -A`, VS Code “Stage All Changes,” or wildcard staging for the first customer commit.
## Stage only the reviewed files
After the dry-run matches the allowlist:
```bash
git add -- .gitignore .gitattributes README.md requirements.in requirements-lock.txt resolute_probe.py dependency_probe.py editor_probe.py tests/test_editor_probe.py .vscode/settings.json .vscode/launch.json
```
Inspect names and status:
```bash
git status --short
git diff --cached --name-status
git diff --cached --stat
git ls-files
```
Every staged path must belong to the allowlist. No environment, cache, wheel, report, credential, key, log, database, archive or absolute-path file may appear.
If anything is wrong, unstage the exact path with `git restore --staged -- path` and inspect it. Do not reset the whole repository or delete the file blindly.
## Review staged content, not only the working tree
Run:
```bash
git diff --cached --check
git diff --cached -- .
git grep --cached -nI -E '(password|passwd|secret|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' || true
git grep --cached -nI -E 'https?://[^/[:space:]]+:[^/@[:space:]]+@' || true
```
Review the complete staged diff. `--check` catches whitespace errors, not secrets or correctness. Pattern matches can be intentional warnings/documentation, but every match needs a decision.
Check staged JSON and Python syntax using the venv:
```bash
.venv/bin/python -m json.tool .vscode/settings.json >/dev/null
.venv/bin/python -m json.tool .vscode/launch.json >/dev/null
.venv/bin/python -m compileall -q resolute_probe.py dependency_probe.py editor_probe.py tests
```
Generated `__pycache__` remains ignored. Validate that no staged file contains a personal `/home/` interpreter path, private host, token or recovered credential.
## Rerun the exact pre-commit quality gate
Run from the staged working tree:
```bash
.venv/bin/python -m pip check
.venv/bin/python resolute_probe.py
.venv/bin/python dependency_probe.py
.venv/bin/python editor_probe.py
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
git diff --cached --check
```
All commands must pass under the same isolated Python 3.14 environment qualified in Steps 2–4. Do not commit with a failing gate or change tests merely to remove a failure without understanding it.
For a production repository, automate this gate later in CI/hooks using reviewed scripts. Step 5 does not install a hook framework or download more packages.
## Preview the commit identity and message
Run:
```bash
git var GIT_AUTHOR_IDENT
git var GIT_COMMITTER_IDENT
git config --get user.name
git config --get user.email
```
Confirm the customer-approved identity and reasonable local timestamp/time zone. The identity and timestamp will be written to the commit.
Use a concise message describing the staged change, for example:
```text
chore: establish Python 3.14 project baseline
```
Do not include customer tickets, credentials, email-login details, internal URLs or sensitive incident descriptions in a commit message.
## Create the reviewed local commit
Only after content, gate, identity and signing policy pass:
```bash
git commit -m "chore: establish Python 3.14 project baseline"
```
Do not use `--no-verify`, `--no-gpg-sign`, `--author`, environment overrides or `--amend` to bypass owned policy. If Git requests signing that the customer requires, stop and complete approved key setup.
The commit is local. It has not authenticated to or sent data to any remote service.
## Verify the commit object and repository integrity
Run:
```bash
git status --short
git log -1 --oneline --decorate
git show --no-patch --format=fuller HEAD
git show --stat --summary HEAD
git diff HEAD --
git fsck --full
```
Require:
- clean intended working tree (ignored generated state does not appear);
- branch `main` at one reviewed commit;
- approved author/committer identity;
- expected file/stat summary;
- no tracked-versus-working content difference;
- no integrity errors.
Review the commit tree directly:
```bash
git ls-tree -r --name-only HEAD
git show --format= --name-status HEAD
```
The tree must exactly match the allowlist. A successful commit message is not proof of safe content.
## Prove nothing was published
Run:
```bash
git remote -v
git branch -vv
git config --local --get-regexp '^remote\.' || true
```
`git remote -v` must be empty. The branch should have no upstream. This is an intentional Step 5 gate: creating a local commit does not authorize creating a repository or transmitting customer data.
Do not add an email address/password HTTPS URL, personal GitHub remote, unapproved SSH destination or placeholder remote for convenience.
## Repository ownership and `safe.directory`
If Git reports dubious ownership, inspect:
```bash
stat -c 'owner=%U group=%G mode=%A path=%n' . .git
id
findmnt -T .
```
The normal user should own this project/repository. Fix the provisioning/ownership cause through the approved process.
Do not add `safe.directory=*`, mark broad home/project parents safe, run Git with sudo, or suppress the warning. The check protects against repositories controlled by another account.
## Backups and recovery
A single local `.git` directory is history, not a backup. Before later remote work, include the project and repository in an approved encrypted backup with restore testing, or use the customer's authorized hosting/backup workflow.
Do not copy only `.venv`; environments are disposable. Preserve source, declarations, repository objects/refs/config as allowed, and recovery documentation.
If the first commit contains a secret, removing it in a second commit does not erase it from history. Revoke/rotate first, then follow an approved history-remediation procedure before any publication.
## Git credentials belong to a later step
Do not configure `credential.helper store` for customer passwords; it can write credentials in plaintext. Do not embed tokens in URLs or use an email password for Git hosting. Later remote authentication should use the provider's supported SSH key, token, workload identity or organizational SSO flow with least privilege and rotation.
## Evidence to retain safely
Retain redacted Git/dpkg versions, repository root/owner, config origins (not secrets), approved author address policy, ignore proof, staged allowlist, test output, commit ID, commit tree, `git fsck` result and empty remote list.
Do not publish complete home paths, unrelated global config, credential-helper contents, tokens, keys, customer source/diffs, internal endpoints or mail account recovery information.
## Troubleshooting
**A parent repository exists.** Stop and determine whether this project should be part of it, a submodule, a subtree or independent. Do not nest accidentally.
**Git is not dpkg-owned.** Identify the binary owner/update channel and customer policy. Do not delete it before assessing other repositories.
**Global identity is personal or wrong.** Configure the approved repository-local identity and verify origin. Do not rewrite other repositories' global configuration casually.
**Customer has no approved commit address.** Pause before commit. Do not invent one or use a mailbox password; obtain repository-owner guidance.
**Ignored file still appears staged.** Ignore rules do not affect already tracked/indexed paths. Unstage the exact path and inspect index/history before any cached removal.
**`.venv` is not ignored.** Review `.gitignore` location/pattern precedence with `git check-ignore -v --no-index`. Do not stage it.
**Secret scan matches documentation.** Review context manually. Keep security warnings if intentional; remove actual values. Do not blanket-exclude the word “password.”
**A secret was staged but not committed.** Unstage the exact file, remove/rotate the secret as necessary, rescan and review. The object may exist locally after staging; avoid sharing the repository and follow cleanup policy if required.
**Test fails after staging.** Compare staged/working content, interpreter and dependency lock. Fix the cause; do not commit a failing baseline.
**Commit reports unknown identity.** The local approved values are missing/invalid or `user.useConfigOnly` is enforcing the boundary. Configure the approved identity; do not disable the safeguard.
**Signing fails.** Verify required key, agent, trust and policy. Do not bypass mandatory signing.
**Dubious ownership error.** Correct ownership/provisioning; never add a wildcard safe-directory exception.
**Remote unexpectedly exists.** Stop and identify who configured it and whether it exposes credentials. Do not fetch, push or delete evidence before review.
## What not to do in 26.04 Step 5
- Do not retrieve, reveal, reuse or store an email password.
- Do not initialize inside an existing parent repository without a design decision.
- Do not run Git as root or suppress ownership protections broadly.
- Do not use a personal/global identity for a customer commit without approval.
- Do not stage everything recursively or rely only on `.gitignore`.
- Do not commit environments, caches, reports, secrets, keys or personal paths.
- Do not bypass tests, hooks or mandatory signing.
- Do not treat a local Git repository as a backup.
- Do not add a remote, hosting account, credential, upstream or push in Step 5.
- Do not assume a later deletion removes a secret from commit history.
| Ubuntu 26.04 Step 5 gate | Pass condition | Corrective direction |
|---|---|---|
| Git owner | approved Resolute package | repair package provenance |
| boundary | exact project; no parent repo | decide repository architecture |
| identity | approved repo-local name/address | obtain owner approval |
| exclusions | environments/secrets remain untracked | fix ignore and storage |
| staged tree | explicit reviewed allowlist only | unstage exact path |
| Python gate | 3.14 probes/tests/check pass | repair owning step |
| commit | tree, identity and fsck verified | inspect local history |
| publication | no remote/upstream/push | remove unauthorized action |
## Ubuntu 26.04 LTS Python Setup Step 5 completion gate
Step 5 is complete only when Git has an approved package owner; no parent or pre-existing repository is accidentally displaced; the project is a normal-user-owned `main` repository; customer-approved authorship is configured locally with explicit origin; `.gitignore` and inventory prove generated/sensitive state is excluded but reviewed; only the documented source, declarations, tests and portable editor policy are staged; the full staged diff and secret review pass; the isolated Python 3.14 quality gate passes; one local commit has the expected tree/identity and a clean integrity check; and remote/upstream lists remain empty.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git --version
git rev-parse --show-toplevel
git config --get --show-origin user.name
git config --get --show-origin user.email
git status --short
git log -1 --oneline --decorate
git show --no-patch --format=fuller HEAD
git ls-tree -r --name-only HEAD
git fsck --full
git remote -v
.venv/bin/python -m pip check
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 6**: select the customer-owned Git hosting target, classify repository visibility/data residency, create or enroll least-privilege SSH/SSO credentials, verify host identity, add the exact approved remote, perform a dry publication review, push `main`, and prove remote branch protection without ever using an email password.
**Ubuntu 26.04 LTS Python Setup Step 5 succeeds when an exact, privacy-reviewed Python 3.14 project tree is committed locally under approved repository-specific authorship, passes integrity and quality gates, and remains completely unconnected to remote services.**
**Ubuntu 26.04 LTS Python Setup Step 6 is to publish the Step 5 local `main` commit to one explicitly authorized, customer-owned Git repository over verified SSH: classify the data and hosting target, enroll a least-privilege key, authenticate the host and account, add a credential-free remote, prove the destination is correct and empty, repeat the disclosure gate, dry-run the exact refspec, push once, and verify local/remote object identity and branch policy.**
This step causes an external state change. Do not create a repository, enroll a key, add a remote or push until the customer has approved the provider, organization/namespace, repository name, visibility, region/data residency, retention, collaborators and publication contents. An email password is never used.
| Publication surface | Required decision | Acceptance evidence |
|---|---|---|
| hosting owner | customer organization/account | approved namespace and administrators |
| repository policy | visibility, residency, retention | provider settings recorded |
| authentication | dedicated SSH/SSO identity | key fingerprint and expected account |
| server identity | independently verified host key | official/admin fingerprint match |
| remote URL | exact SSH destination, no secret | local config and read-only query |
| disclosure | reviewed commit tree/history | tests, scans and archive manifest |
| first push | explicit `main:main` refspec | dry-run then authorized push |
| post-push | object equality and protections | remote SHA, upstream and rules |
## Reconfirm Step 5 before external work
Run as the normal Ubuntu user:
```bash
cd ~/projects/resolute-python-lab
grep -E '^(VERSION_ID|VERSION_CODENAME)=' /etc/os-release
git rev-parse --show-toplevel
git symbolic-ref --short HEAD
git status --short
git log -1 --oneline --decorate
git fsck --full
git remote -v
```
Require Ubuntu 26.04 `resolute`, the exact project root, branch `main`, a clean intended working tree, one reviewed local commit, no integrity errors and no remotes. If a remote already exists, stop and audit who added it, its URLs, credentials, fetched refs and authorization before continuing.
Recheck the Python 3.14 gate:
```bash
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip check
.venv/bin/python dependency_probe.py
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
Require Python 3.14, the project `.venv`, true isolation, consistent dependencies and passing tests. Every `python -c`/`python3 -c` example is one physical line.
## Obtain explicit publication authorization
Record an approved change/request containing:
- legal/customer repository owner and accountable administrators;
- provider and exact organization/group/namespace;
- exact repository name and description;
- private/internal/public visibility classification;
- data residency, backup, retention and deletion requirements;
- allowed users/teams/bots and least-privilege roles;
- SSO/MFA and key/token lifecycle policy;
- default branch and protection/ruleset requirements;
- secret, dependency and code-scanning requirements;
- approval of the exact Step 5 commit tree and history;
- named operator and change window for the first push.
“The customer has an email account” is not authorization. Do not use a personal hosting namespace as a temporary target, because transfers/forks/caches/audit history can persist.
## Classify content before choosing visibility
Treat private as the safe initial default unless the customer has approved broader visibility. Private does not mean exempt from review: provider staff/processors, organization administrators, integrations, backups and future policy changes can affect access.
Review licenses and third-party rights as well as secrets. The repository contains source, dependency declarations, tests and editor configuration; confirm no customer identifiers, internal endpoints, proprietary data, regulated data, export-controlled material or unlicensed content is present.
Public visibility requires a separate legal/security/communications decision. Never make a repository public to simplify cloning or avoid access setup.
## Create the remote repository through the approved control plane
An authorized customer administrator creates an empty repository in the approved namespace using the provider UI/API/IaC process. Configure the approved visibility and ownership.
For this first push, leave the remote repository truly empty:
- do not initialize a README;
- do not add a license or `.gitignore` template;
- do not create a sample commit or default branch;
- do not import another repository.
An auto-created remote commit makes histories diverge and requires an integration decision. Do not force-push over it.
Copy the provider's exact SSH clone URL from the authenticated repository page. It should resemble `git@HOST:OWNER/REPOSITORY.git` or `ssh://git@HOST/OWNER/REPOSITORY.git`; the actual host, namespace and path must be approved.
## Verify the OpenSSH client owner
Run:
```bash
command -v ssh
ssh -V
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' openssh-client 2>/dev/null || true
dpkg -S "$(readlink -f "$(command -v ssh)")"
```
If missing:
```bash
sudo apt update
sudo apt install openssh-client
```
Review the APT plan. A Git client needs the outbound OpenSSH client, not `openssh-server`; do not expose an inbound SSH service for this workflow.
## Inspect existing SSH state without exposing keys
Run metadata-only checks:
```bash
find ~/.ssh -maxdepth 1 -type f -printf '%M %u %g %f\n' 2>/dev/null | sort
ssh-add -l 2>/dev/null || true
ssh -G example.invalid 2>/dev/null | grep -E '^(identityfile|identitiesonly|proxycommand|proxyjump|userknownhostsfile) '
```
Do not print private-key contents. Existing keys can belong to personal accounts, servers or other customers. Reuse only when its owner, scope, passphrase/hardware protection, rotation and provider enrollment explicitly match this repository policy.
Review `~/.ssh/config`, included config, agents, proxy/jump settings and global known-host files locally. A host alias or wildcard can silently choose another identity/proxy.
## Choose the least-privilege authentication model
Prefer an organization-managed/hardware identity or repository-scoped deploy key; otherwise use a dedicated customer account key authorized through required SSO. A personal account key may reach every repository that account can access, while deploy-key ownership differs by provider. Document principal, scope and revocation owner.
Do not use a shared unencrypted private key, copy a coworker's key, email a private key, or use an email/mailbox password.
## Generate a dedicated encrypted key only if approved
Skip generation if an approved hardware/managed key already exists. For the software-key fallback, first ensure the exact filenames are unused:
```bash
test ! -e ~/.ssh/id_ed25519_resolute_git
test ! -e ~/.ssh/id_ed25519_resolute_git.pub
```
Prepare permissions and generate interactively:
```bash
umask 077
mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -a 100 -f ~/.ssh/id_ed25519_resolute_git -C 'resolute-python-lab'
```
Enter a strong unique passphrase when prompted and store/recover it only through the customer's approved secret process. Do not pass it on the command line, leave it blank for convenience, or send it to support/chat.
Verify ownership, modes and fingerprint without displaying the private key:
```bash
stat -c 'owner=%U group=%G mode=%A path=%n' ~/.ssh ~/.ssh/id_ed25519_resolute_git ~/.ssh/id_ed25519_resolute_git.pub
ssh-keygen -lf ~/.ssh/id_ed25519_resolute_git.pub
ssh-keygen -y -f ~/.ssh/id_ed25519_resolute_git | diff -u - <(awk '{print $1, $2}' ~/.ssh/id_ed25519_resolute_git.pub)
```
The private file should be user-only; the public file can be readable. The final comparison proves the public key belongs to the private key and prompts for its passphrase.
## Enroll only the public key
Display the public half for local copy into the authenticated provider/admin control plane:
```bash
cat ~/.ssh/id_ed25519_resolute_git.pub
```
Verify its displayed fingerprint again after enrollment. Label it with device/customer/purpose and an owner/review date. Apply repository-only write scope when supported; otherwise confirm account/organization scope and SSO authorization.
Never upload `id_ed25519_resolute_git` without `.pub`. Never paste the private key, passphrase, recovery code, session cookie or email password into the provider.
## Obtain the authoritative SSH host fingerprint
Before the first connection, obtain the provider's current SSH host-key fingerprints through an authenticated official documentation page or the customer's Git-server administrator using an independent trusted channel.
Record host, algorithm and fingerprint in the change evidence. For a self-hosted service, DNS name alone is insufficient; administrators must provide the deployed key fingerprint and rotation process.
`ssh-keyscan` can observe what the network presents but does not authenticate it. Do not accept a fingerprint merely because `ssh-keyscan` and the first connection agree—they may share the same interception path.
## Test host identity and account authentication
Use the exact provider SSH user/host. A common hosted pattern is `git@HOST`, but trust the provider's instructions:
```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519_resolute_git -T git@APPROVED_HOST
```
On first connection, compare the presented algorithm/fingerprint character-for-character with the authoritative independent source before typing `yes`. If it differs or an unexpected key-change warning appears, answer no and investigate. Do not delete `known_hosts`, use `StrictHostKeyChecking=no`, or use `accept-new` as a substitute for verification.
Some Git hosts intentionally provide no interactive shell and return a nonzero status even after successful authentication. Judge the provider-specific message: it must name the expected account/principal and confirm authentication. GitHub, for example, documents that its successful SSH test normally exits with status 1.
Replace `APPROVED_HOST` before running; never execute a placeholder. For nonstandard ports or aliases, follow the provider-admin exact SSH configuration and verify the corresponding endpoint fingerprint.
## Bind the dedicated identity without committing a path
For a dedicated key, create a narrow entry in the user's `~/.ssh/config` through the approved editor:
```sshconfig
Host resolute-customer-git
HostName APPROVED_HOST
User git
IdentityFile ~/.ssh/id_ed25519_resolute_git
IdentitiesOnly yes
```
Replace and verify `APPROVED_HOST`; do not leave the placeholder. The alias is local and should not be committed. Avoid wildcard host blocks and broad proxy/agent-forwarding directives.
Check the effective configuration:
```bash
chmod 600 ~/.ssh/config
ssh -G resolute-customer-git | grep -E '^(hostname|user|identityfile|identitiesonly|proxycommand|proxyjump) '
ssh -T resolute-customer-git
```
Confirm the approved hostname, SSH user, dedicated identity and expected authenticated account. If the organization uses a managed SSH config, do not overwrite it; merge through its owner.
## Capture and validate the exact remote URL
Use the local alias with the approved namespace/repository, for example:
```text
resolute-customer-git:APPROVED_OWNER/APPROVED_REPOSITORY.git
```
Compare `APPROVED_OWNER` and `APPROVED_REPOSITORY` with the authenticated provider page and change approval. Case sensitivity and subgroup paths can matter.
Reject URLs containing a password/token, HTTP, an IP address not explicitly approved, a personal namespace, look-alike Unicode, extra path components, whitespace or shell metacharacters.
Do not paste a remote URL directly from an email/chat without cross-checking the authenticated provider control plane.
## Read the destination before adding a remote
Query the exact candidate URL directly:
```bash
git ls-remote --symref resolute-customer-git:APPROVED_OWNER/APPROVED_REPOSITORY.git
```
An authorized truly empty repository normally returns no refs. Authentication failure, repository-not-found and an empty repository can have provider-specific messages—confirm the repository page and command exit status.
If any branch/tag/HEAD ref appears, stop. Determine whether the target is wrong or already initialized. Do not force-push, delete refs or merge unrelated history under this first-push procedure.
## Repeat the disclosure gate immediately before remote configuration
Run:
```bash
git status --short
git log --oneline --decorate --all
git ls-tree -r --name-only HEAD
git show --stat --summary HEAD
git fsck --full
git grep -nI -E '(password|passwd|secret|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' HEAD || true
git grep -nI -E 'https?://[^/[:space:]]+:[^/@[:space:]]+@' HEAD || true
```
Review all matches and the complete commit tree. Verify commit author/committer metadata:
```bash
git show --no-patch --format=fuller HEAD
git config --get --show-origin user.name
git config --get --show-origin user.email
```
Rerun quality:
```bash
.venv/bin/python -m pip check
.venv/bin/python dependency_probe.py
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
Publication review covers committed history, not only current files. Ignoring/removing a secret after an earlier commit does not remove it from the objects that push will transmit.
## Preview the exact publication manifest
List the archive names without writing an archive:
```bash
git archive --format=tar HEAD | tar -tf -
git count-objects -vH
git rev-list --objects --all
```
The manifest must match Step 5's reviewed allowlist and repository-object inventory. Git pushes commit/tree/blob objects, including reachable history; it does not push `.gitignore`-excluded working files unless they were committed.
Do not publish if an unexplained blob/path/object appears. Investigate before adding the remote.
## Add one credential-free remote
Only after the destination and disclosure gates pass:
```bash
git remote add origin resolute-customer-git:APPROVED_OWNER/APPROVED_REPOSITORY.git
```
Replace placeholders with the exact approved path. The command adds configuration but does not fetch or push.
Verify expanded and stored values:
```bash
git remote -v
git remote get-url --all origin
git remote get-url --push --all origin
git config --local --get-regexp '^remote\.origin\.'
```
Require exactly one fetch URL and one equivalent push destination, no embedded credential, and the expected refspec. Unexpected URL rewrite rules must be investigated with Git config origin output.
If wrong, remove or set the remote only after recording the error; never test an uncertain target with a push.
## Prove the configured remote remains empty
Run read-only queries through the named remote:
```bash
git ls-remote --symref origin
git ls-remote --heads origin
git ls-remote --tags origin
```
Require no refs for this empty-repository workflow. If something appeared between approval and push, stop—the state changed concurrently.
## Dry-run one explicit refspec
Run:
```bash
git push --dry-run --porcelain origin refs/heads/main:refs/heads/main
```
Review destination, branch and proposed new ref. A dry-run can authenticate and contact the server but should not update refs. Server/provider behavior and authorization are still involved; it is not an offline simulation.
Do not use `--all`, `--mirror`, `--tags`, `--force`, `+main`, wildcard refspecs or VS Code Publish Branch. The explicit full refspec limits intent to local `main` becoming remote `main`.
## Push only after the final authorization checkpoint
Confirm the named operator has approval for this exact repository, commit ID, refspec and time. Record local ID:
```bash
git rev-parse HEAD
```
Then perform the external write:
```bash
git push --set-upstream origin refs/heads/main:refs/heads/main
```
Read server messages, policy checks and the reported object/ref update. Do not retry with force if rejected. A rejection is a policy/state signal to investigate.
The upstream setting is appropriate only after the successful first push and means future abbreviated push/pull commands can target `origin/main`; organization policy should still prefer reviewed explicit operations.
## Prove remote object equality
Query the server and compare exact object IDs:
```bash
LOCAL_HEAD="$(git rev-parse HEAD)"
REMOTE_HEAD="$(git ls-remote --heads origin refs/heads/main | awk '{print $1}')"
printf 'local=%s\nremote=%s\n' "$LOCAL_HEAD" "$REMOTE_HEAD"
test -n "$REMOTE_HEAD" && test "$LOCAL_HEAD" = "$REMOTE_HEAD"
unset LOCAL_HEAD REMOTE_HEAD
```
The test must succeed. Then fetch and verify tracking state:
```bash
git fetch --prune origin
git branch -vv
git rev-parse origin/main
git status --short --branch
git log --oneline --decorate --all
```
Require local `main`, `origin/main` and the server-reported ref to identify the same commit; the worktree remains clean.
## Verify through the authenticated provider UI
Using the approved customer account/session, confirm:
- correct organization/group and repository name;
- approved visibility and data-region/retention settings;
- default branch is `main`;
- files and commit ID match local evidence;
- author attribution/privacy is acceptable;
- no unintended collaborators, teams, forks or integrations;
- audit log records the expected operator/key/action.
Do not rely only on the browser URL bar or only on Git output; both control-plane and data-plane evidence matter.
## Configure branch protection immediately
Apply the approved provider ruleset/branch policy for `main`, commonly including:
- pull requests rather than direct changes;
- required review count and code-owner review;
- required status checks/CI before merge;
- dismissal/reapproval for changed commits;
- restricted force pushes and branch deletion;
- conversation resolution and signed-commit policy where required;
- administrator/bypass restrictions and auditability.
An initial seed push may precede rules only when the approved workflow requires it; minimize the unprotected interval and capture settings evidence. Provider feature names and plan availability differ.
Step 6 does not invent CI checks. A rule requiring nonexistent checks can block all merges; Step 7 should create and qualify the Python 3.14 CI gate, then make it required.
## Protect the SSH identity after publication
Record the public-key fingerprint, provider key ID/label, scope, owner, creation/review/expiry dates and revocation procedure. Keep the private key and passphrase separate under approved backup/recovery policy.
Do not delete the private key until another approved access/recovery path is confirmed. When retiring the device/user, revoke provider enrollment first, terminate sessions/tokens, then dispose of key material according to policy.
Never put secrets into remote URLs, `credential.helper store`, `.git/config`, shell history, README, commits or screenshots. For HTTPS workflows, use the provider's supported token/credential manager—not an email password—but this page uses SSH to avoid mixing models.
## Evidence to retain safely
Retain approval/change ID, provider/namespace/repository/visibility, authoritative host-key source and matched fingerprint, public-key fingerprint/scope, authenticated account message, empty-remote proof, final local commit ID, disclosure/test gates, credential-free URL, dry-run output, push result, remote SHA equality, tracking state, protection settings and audit event.
Redact private key/passphrase, SSO/MFA/recovery details, session cookies, tokens, full personal paths, unrelated keys/config, internal network topology and customer source not required by the evidence record.
## Troubleshooting
**Provider/namespace is not approved.** Stop. Do not create a personal temporary repository or publish privately as a shortcut.
**Existing SSH key is found.** Identify owner/scope before reuse. Do not overwrite or assume it belongs to this customer.
**Key filename already exists.** Stop and inspect it. Choose an approved unique name; never use `-f` to overwrite key material.
**Host fingerprint differs.** Refuse the connection and validate through independent provider/admin channels. Do not delete known-host evidence or disable checking.
**SSH test says authenticated but exits 1.** Compare the exact provider-documented behavior and expected account. Some Git-only services intentionally deny shell access.
**Too many authentication failures.** The agent offered unrelated keys. Use `IdentitiesOnly yes` with the dedicated identity; do not remove other users' keys blindly.
**Permission denied (publickey).** Verify public-key enrollment, key fingerprint, agent/direct identity, provider account, SSO authorization, repository permission and SSH user/host.
**Repository not found.** Check exact namespace/name/case and authorization. Do not infer that it is empty or create another repository automatically.
**Remote contains refs.** Stop and inspect ownership/history. Do not force-push or delete remote content under the empty-first-push procedure.
**URL contains a token/password.** Do not add it. Rotate exposed credentials, obtain the official SSH URL and review shell/config history.
**Dry-run targets the wrong branch/repository.** Stop; remove/correct the remote after evidence review. Do not execute the real push.
**Push rejected by policy.** Read the server response and satisfy authorized rules. Never add force/bypass flags reflexively.
**Remote SHA differs after push.** Stop further work. Inspect server-side transformations, concurrent pushes, wrong remote/ref and audit logs. Do not overwrite evidence.
**Branch protection cannot be enabled.** Escalate provider plan/permissions/policy. Do not call the repository production-ready without compensating controls.
## What not to do in 26.04 Step 6
- Do not publish without explicit destination, visibility and content authorization.
- Do not use an email password, recovered credential or token-bearing URL.
- Do not accept an unverified SSH host fingerprint or disable host checking.
- Do not overwrite/reuse unknown SSH keys or expose the private half.
- Do not create a nonempty remote for this first-push workflow.
- Do not add an uncertain remote or use stage/publish buttons that hide refspecs.
- Do not force, mirror, push all branches/tags, or overwrite remote history.
- Do not assume private visibility removes legal/security review.
- Do not skip object-ID equality, UI ownership/visibility or branch-policy verification.
- Do not leave access keys, collaborators or unprotected branches without lifecycle owners.
| Ubuntu 26.04 Step 6 gate | Pass condition | Corrective direction |
|---|---|---|
| authorization | exact owner/repository/visibility approved | obtain customer decision |
| authentication | scoped SSH key maps to expected principal | fix enrollment/scope |
| server identity | independent fingerprint matches | refuse and investigate |
| destination | credential-free exact URL; empty refs | correct target/state |
| disclosure | tree/history/scans/tests approved | remediate before push |
| push | dry-run and explicit `main:main` succeed | honor server policy |
| verification | local, tracking and remote SHA equal | investigate divergence |
| governance | UI ownership/visibility/rules/audit pass | apply required controls |
## Ubuntu 26.04 LTS Python Setup Step 6 completion gate
Step 6 is complete only when the customer has approved the exact hosting owner, repository, visibility, residency and content; the OpenSSH client is trusted; a least-privilege SSH principal has an owned lifecycle; the server host key matches an independent authoritative fingerprint; authentication names the expected provider account; the credential-free remote URL resolves to the correct empty repository; the commit history, tree, secret/license review and Python 3.14 gate pass immediately before publication; an explicit `main:main` dry-run is reviewed; one authorized non-force push succeeds; local `HEAD`, `origin/main` and server `main` have the same object ID; and provider UI ownership, visibility, access, audit and branch protections are verified.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git show --no-patch --format=fuller HEAD
git ls-tree -r --name-only HEAD
git remote -v
git remote show origin
git branch -vv
git rev-parse HEAD
git rev-parse origin/main
git ls-remote --heads origin refs/heads/main
git fsck --full
.venv/bin/python -m pip check
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 7**: create a least-privilege CI workflow on an Ubuntu runner for Python 3.14, install only the reviewed lock, run dependency/probe/unittest gates, constrain triggers/permissions/actions/caches/secrets, qualify a deliberate failure, then make the verified check required on protected `main`.
**Ubuntu 26.04 LTS Python Setup Step 6 succeeds when one authorized customer-owned remote receives exactly the reviewed local `main` commit through independently verified, least-privilege SSH, and object equality plus provider governance prove the publication landed at the intended destination.**
ubuntu 2604 lts python setup step7, ubuntu 2604 lts python github actions, ubuntu 2604 lts python ci setup, python 314 ci ubuntu 2604 lts, ubuntu resolute python ci
**Ubuntu 26.04 LTS Python Setup Step 7 is to turn the Step 6 published repository into a least-privilege continuous-integration gate for Python 3.14: run the reviewed dependency lock, probes, compilation and unittests on a stable Ubuntu runner plus an exact Ubuntu 26.04 preview lane, prove clean isolated recreation, qualify both failure and recovery, then require only the stable uniquely named check on protected `main` until the 26.04 hosted image leaves preview.**
This implementation uses GitHub Actions because the workflow syntax, runner labels and action SHAs are provider-specific. If Step 6 selected GitLab, Launchpad, an enterprise CI system or another host, do not paste this file; translate the same permissions, runner, isolation, dependency, trigger, failure and protection contracts through that provider's approved pipeline model.
| CI surface | Step 7 policy | Acceptance evidence |
|---|---|---|
| trusted baseline | reviewed Step 6 `main` | clean tree and matching remote SHA |
| stable gate | `ubuntu-24.04`, Python 3.14 | required unique successful check |
| Resolute parity | `ubuntu-26.04` public preview | informational matrix result |
| actions | official repositories, full SHAs | reviewed source/tag/commit mapping |
| token/secrets | `contents: read`, no secrets | workflow permissions and logs |
| environment | fresh `.venv-ci` per job | executable/prefix/package proof |
| quality | lock, probes, compile, unittest | deterministic command results |
| enforcement | failure/recovery then ruleset | red/green evidence and blocked merge |
## Confirm GitHub is the approved Step 6 provider
Run locally as the normal Ubuntu user:
```bash
cd ~/projects/resolute-python-lab
git remote -v
git remote get-url origin
git branch -vv
git status --short --branch
```
The remote must be the exact customer-owned GitHub.com or GitHub Enterprise repository approved in Step 6, with no embedded credential. Local `main`, `origin/main` and provider `main` must identify the same reviewed commit.
GitHub Enterprise Server can have different runner images, Actions versions, policies and network access. Confirm support before using GitHub.com-hosted labels or marketplace actions. Do not enable external Actions against customer code merely because the syntax matches.
## Reprove the local Python 3.14 gate
Run:
```bash
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip check
.venv/bin/python resolute_probe.py
.venv/bin/python dependency_probe.py
.venv/bin/python editor_probe.py
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
git fsck --full
```
Require Python 3.14, true local venv isolation, all probes/tests passing and repository integrity. Every `python -c`/`python3 -c` command occupies one physical line.
CI is not a way to discover whether an already-broken local baseline works. Repair the owning step before workflow changes.
## Approve Actions policy, billing and data flow
Before adding a workflow, the customer administrator decides:
- whether GitHub Actions is allowed for this repository/organization;
- allowed action owners and whether full-SHA pinning is enforced;
- hosted runner regions/data handling and private-repository minutes/budget;
- fork pull-request policy and first-time contributor approval;
- log/artifact retention and who may rerun/cancel workflows;
- default `GITHUB_TOKEN` restrictions;
- whether public-preview runner images are permitted;
- branch ruleset owners and emergency-bypass audit.
Workflow execution sends source and metadata to runner infrastructure and can make outbound package requests. Private repository visibility does not eliminate processor, retention, billing or jurisdiction review.
Do not register the customer's Ubuntu workstation as a self-hosted runner for untrusted pull requests. Persistent runners can retain credentials, workspaces, services and network access after adversarial code executes.
## Understand the Ubuntu runner decision
As of August 2, 2026, GitHub documents `ubuntu-26.04` x64 hosted runners as **public preview**. Preview images are supplied as-is, excluded from normal SLA/warranty/support commitments, and can change.
Therefore this baseline uses:
- `ubuntu-24.04` as the stable, required Python 3.14 check;
- `ubuntu-26.04` as an exact-OS informational parity lane with `continue-on-error` while preview;
- an explicit `3.14` interpreter provisioned by `setup-python` in both lanes.
Do not assume `ubuntu-latest` means Ubuntu 26.04; GitHub states that “latest” means its latest stable image, not necessarily the vendor's newest OS. Pin explicit labels so migration is reviewed.
When `ubuntu-26.04` becomes stable and the customer qualifies it, remove experimental treatment and make its uniquely named check required. Until then, a preview outage must not silently erase the stable gate.
## Review third-party action supply-chain policy
This workflow uses only `actions/checkout` and `actions/setup-python` from GitHub's official `actions` organization. GitHub's secure-use guidance says a full-length commit SHA is the only immutable action reference.
The SHAs below were resolved from the official repositories' `v6` tags during this implementation:
```text
actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
```
Before committing, verify each SHA in the official repository and review its release/source. A SHA is immutable, not automatically safe; updates still require review.
Do not replace SHAs with `@main`, `@master`, a floating marketplace result or an action copied from an issue comment.
## Create a dedicated workflow branch
Do not edit protected `main` directly. Start from the verified remote state:
```bash
git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
git switch -c ci/python-3.14-ubuntu
```
If the branch already exists locally/remotely, stop and inspect its owner/history. Do not reset or overwrite it.
This branch will add the workflow and a `.gitignore` rule only; dependency versions and application behavior remain unchanged.
## Ignore only local CI recreation state
Add this project-root `.gitignore` rule if absent:
```gitignore
.venv-ci/
```
The hosted runner is ephemeral, but the rule protects local reproduction. Do not ignore `.github/`, workflow YAML or CI evidence scripts.
Review the complete `.gitignore` rather than appending duplicates or broad patterns.
## Create the Python 3.14 workflow
Create `.github/workflows/python-ci.yml`:
```yaml
name: Python 3.14 CI
on:
pull_request:
push:
branches:
- main
workflow_dispatch:
inputs:
prove_failure:
description: Intentionally fail to qualify required-check enforcement
required: true
type: boolean
default: false
permissions:
contents: read
concurrency:
group: python-ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality:
name: Python 3.14 / ${{ matrix.label }}
runs-on: ${{ matrix.runner }}
continue-on-error: ${{ matrix.experimental }}
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
include:
- runner: ubuntu-24.04
label: stable
experimental: false
- runner: ubuntu-26.04
label: resolute-preview
experimental: true
steps:
- name: Check out triggering revision
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
persist-credentials: false
fetch-depth: 1
- name: Set up CPython 3.14
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: "3.14"
- name: Record runner and interpreter evidence
shell: bash
run: |
set -euo pipefail
cat /etc/os-release
uname -a
python --version
python -c "import platform, sys; print(sys.executable); print(sys.version_info); print(platform.platform())"
python -c "import sys; raise SystemExit(0 if sys.version_info[:2] == (3, 14) else 1)"
- name: Recreate isolated environment
shell: bash
run: |
set -euo pipefail
python -m venv .venv-ci
.venv-ci/bin/python -m pip --version
.venv-ci/bin/python -m pip install --only-binary=:all: --requirement requirements-lock.txt
- name: Prove environment and dependencies
shell: bash
run: |
set -euo pipefail
.venv-ci/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix); print(sys.base_prefix); print(sys.prefix != sys.base_prefix)"
.venv-ci/bin/python -c "import sys; raise SystemExit(0 if sys.version_info[:2] == (3, 14) and sys.prefix != sys.base_prefix else 1)"
.venv-ci/bin/python -m pip check
.venv-ci/bin/python dependency_probe.py
- name: Compile, probe, and test
shell: bash
run: |
set -euo pipefail
.venv-ci/bin/python -m compileall -q resolute_probe.py dependency_probe.py editor_probe.py tests
.venv-ci/bin/python resolute_probe.py
.venv-ci/bin/python editor_probe.py
.venv-ci/bin/python -m unittest discover -v -s tests -p 'test_*.py'
git diff --exit-code
- name: Deliberate failure qualification
if: ${{ github.event_name == 'workflow_dispatch' && inputs.prove_failure }}
shell: bash
run: |
echo 'Intentional Step 7 failure: required-check enforcement qualification.'
exit 1
```
Do not wrap GitHub expressions in shell variables or insert pull-request titles/branch names into `run:` scripts. Those values can contain attacker-controlled shell syntax. This workflow uses expressions only in declarative fields and a boolean condition.
## Why the workflow creates `.venv-ci`
`setup-python` selects an explicit CPython 3.14 tool-cache interpreter; it does not reproduce the project's isolated prefix by itself. The workflow creates `.venv-ci`, then invokes its Python explicitly for every dependency and test command.
This mirrors Step 2's ownership proof while avoiding activation state. Tests expecting a path containing `.venv` accept `.venv-ci`, and prefix/base-prefix inequality proves isolation.
Do not install packages into the runner's global/tool-cache interpreter, use sudo pip, or rely on whatever Python happens to be preinstalled on the image.
## Why dependency caching is initially absent
The small wheel-only lock uses cold installs for clear evidence. GitHub documents that caches are unsigned and readable in defined pull-request scopes. Do not cache `.venv-ci`, secrets or executable state. If performance later justifies pip download caching, key it by OS, Python and exact lock hash, review fork/default-branch poisoning rules, and retain install verification.
## Review trigger and token boundaries
`pull_request` runs proposed code with a read-only `GITHUB_TOKEN` and no declared secrets. `push` validates `main`; `workflow_dispatch` supports controlled red/green qualification. No schedule, deployment, package publication or write permission exists.
Never change this validation workflow to `pull_request_target` while checking out/executing the pull request. GitHub warns that target-context workflows have elevated base-repository token/secrets and can be compromised by untrusted code.
`persist-credentials: false` prevents checkout from leaving the token for later Git commands. The job has no reason to push, comment, create checks manually or upload packages.
Repository/organization settings can grant broader defaults than YAML. Verify effective token permissions in workflow logs/settings and enforce restrictive organization policy.
## Review the preview-lane failure semantics
The unique checks are `Python 3.14 / stable` and `Python 3.14 / resolute-preview`. Only preview has `continue-on-error`; review its result even though it cannot fail the workflow. Require only stable until 26.04 leaves preview, and do not reuse either job name in another workflow.
## Validate locally before staging
Run the core CI path locally with a fresh disposable target:
```bash
test ! -e .venv-ci
python3 -m venv .venv-ci
.venv-ci/bin/python -m pip install --only-binary=:all: --requirement requirements-lock.txt
.venv-ci/bin/python -m pip check
.venv-ci/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv-ci/bin/python dependency_probe.py
.venv-ci/bin/python -m unittest discover -v -s tests -p 'test_*.py'
git diff --exit-code
```
The Ubuntu 26.04 workstation qualifies command parity, not GitHub YAML, hosted images, tokens or actions. Keep `.venv-ci` ignored and remove it later only by exact reviewed path.
## Review YAML and action pins
Inspect:
```bash
sed -n '1,260p' .github/workflows/python-ci.yml
git diff --check
grep -nE 'uses:|permissions:|runs-on:|continue-on-error:|pull_request_target|secrets\.' .github/workflows/python-ci.yml
```
Require exactly two `uses:` lines with full 40-character official SHAs, `contents: read`, explicit runner labels, preview-only experimental behavior, no secret reference and no `pull_request_target`.
If an approved `actionlint` or GitHub workflow validator already exists, run it. Do not install an unreviewed parser globally or claim that generic YAML parsing proves GitHub schema validity.
GitHub performs the authoritative workflow parse after push; inspect any annotation before enabling enforcement.
## Stage an exact workflow change
Run:
```bash
git add --dry-run -- .gitignore .github/workflows/python-ci.yml
git add -- .gitignore .github/workflows/python-ci.yml
git status --short
git diff --cached --name-status
git diff --cached --check
git diff --cached -- .
```
Only the ignore rule and workflow should be staged. Review the entire workflow as executable supply-chain configuration.
Search staged content:
```bash
git grep --cached -nI -E '(password|passwd|secret|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' || true
git grep --cached -nI -E 'uses: [^ ]+@(main|master|v[0-9]+)$' || true
```
The workflow intentionally discusses no credentials and must contain no token values, private URLs or floating action references.
## Commit under the approved identity
Verify author and branch:
```bash
git branch --show-current
git config --get --show-origin user.name
git config --get --show-origin user.email
git var GIT_AUTHOR_IDENT
```
Require `ci/python-3.14-ubuntu` and the approved repository-local identity. Then commit:
```bash
git commit -m "ci: add Python 3.14 Ubuntu quality gate"
```
Do not bypass hooks/signing, amend unrelated history or include generated `.venv-ci` state.
## Push only the workflow branch
Repeat disclosure and quality review, then push an explicit branch refspec:
```bash
git status --short --branch
git show --stat --summary HEAD
git ls-tree -r --name-only HEAD
git push --dry-run --porcelain origin refs/heads/ci/python-3.14-ubuntu:refs/heads/ci/python-3.14-ubuntu
git push --set-upstream origin refs/heads/ci/python-3.14-ubuntu:refs/heads/ci/python-3.14-ubuntu
```
Do not push directly to `main`, use force, or click a UI publish action that hides the destination.
## Open and inspect the pull request
Through the authenticated customer GitHub UI, open a pull request from `ci/python-3.14-ubuntu` to `main`. Confirm base/head repositories and branches, diff, commit, visibility and reviewers.
Do not grant secrets to the workflow. Review Actions logs for:
- expected triggering commit SHA;
- `ubuntu-24.04` stable and `ubuntu-26.04` preview image identity;
- CPython 3.14 executable/version;
- `.venv-ci` prefix isolation;
- wheel-only lock installation and package version;
- passing probes, compile, unittest and clean diff;
- no unexpected network, package, artifact or credential behavior.
The preview lane may be neutral/allowed failure, but record whether the actual code gate passed or infrastructure failed.
## Merge only after the stable gate is green
Obtain required review and merge through the provider's approved strategy. Do not bypass existing protections. After merge:
```bash
git switch main
git pull --ff-only origin main
git status --short --branch
git log -2 --oneline --decorate
```
Confirm the `push` event runs the same workflow on the merged `main` commit and `Python 3.14 / stable` succeeds.
If merge creates a new commit/squash SHA, verify the workflow run targets the actual final `main` SHA, not only the pull-request merge ref.
## Qualify deliberate failure and recovery
The workflow's manual boolean input avoids editing tests merely to produce red evidence. From the default branch in Actions, run **Python 3.14 CI** manually with `prove_failure=true`.
Expected:
- all real setup/quality steps pass first;
- the deliberate final step prints its explicit qualification message and exits 1;
- `Python 3.14 / stable` is red;
- the preview job can be marked allowed failure by design;
- logs contain no secret.
Then run it again with `prove_failure=false`. Both real lanes should execute without the deliberate failure; stable must be green. Retain run URLs/IDs and commit SHA for red and recovered green evidence.
Do not qualify by breaking application code, disabling dependencies, cancelling jobs or changing branch protections.
## Make the stable check required
In the approved ruleset/branch-protection control plane for `main`, require the uniquely named check:
```text
Python 3.14 / stable
```
Also retain the Step 6 review/force-push/deletion rules. Do not require `Python 3.14 / resolute-preview` while GitHub labels it preview unless customer policy explicitly accepts preview availability as a merge blocker.
Prove enforcement with a harmless new pull request or ruleset evaluation: an unrun/failing stable check must block merge, and a green current-head check must satisfy the rule. Administrator bypasses need named owners and audit review.
Required checks can become stale/ambiguous if job/workflow names change. Treat renames as governance migrations, not cosmetic edits.
## Fork and untrusted-code boundary
Pull-request imports/tests can execute arbitrary code. Use ephemeral hosted runners with no secrets, read-only token and nonpersistent credentials; never use the customer workstation, persistent/internal runner, cloud/signing/publish credentials or SSH agents. Require maintainer approval for untrusted contributors as policy dictates.
## Updating actions, runners and Python
Action SHA updates require official tag/source verification, release review and red/green qualification; bots may propose but must not auto-merge executable workflow changes without policy. Runner/Python patch drift remains visible in evidence. When 26.04 leaves preview, remove experimental treatment through a reviewed PR, requalify failure/recovery, and decide whether it replaces or joins the stable required check.
## Evidence to retain safely
Retain policy approval; workflow diff; action-repository/SHA provenance; runner labels/status; token permissions; branch/commit IDs; stable and preview logs; local parity output; pull-request review; merged-main green run; deliberate red/recovered green run IDs; required-check/ruleset configuration; and enforcement proof.
Do not retain tokens, complete event payloads, unrelated organization settings, customer secrets, personal paths or runner credentials.
## Troubleshooting
**Actions is disabled or restricted.** Obtain organization approval/allowlisting. Do not enable it personally or replace SHA pins with allowed-but-floating actions.
**Workflow does not appear.** Confirm file path `.github/workflows/*.yml`, committed branch, YAML/schema annotations and Actions policy. Manual dispatch normally requires the workflow on the default branch.
**`ubuntu-26.04` is unavailable/queued.** It is public preview. Preserve the stable gate, inspect GitHub status/availability and do not silently change labels to `latest`.
**setup-python cannot find 3.14.** Verify runner support, exact input, action logs/network and current action SHA. Do not use the image's ambient Python.
**Action requires newer runner.** v6 actions use Node 24 and document minimum runner versions. GitHub-hosted images are managed; GHES/self-hosted owners must qualify/update runner software.
**Wheel-only install fails.** Inspect lock, index, Python 3.14/platform compatibility and package availability. Do not remove `--only-binary` reflexively or install unreviewed build tools.
**Unit test expects `.venv`.** `.venv-ci` contains the project convention and should pass. If not, review brittle path assertions and isolation evidence rather than spoofing paths.
**Stable passes, preview fails.** Classify code/OS compatibility versus preview infrastructure. Track and remediate; allowed failure is temporary evidence, not acceptance.
**PR from fork cannot access secret.** Correct behavior: this workflow needs none. Do not switch to `pull_request_target` or expose secrets.
**Required check is missing/pending.** Verify trigger coverage, exact unique job name, current head SHA, skipped/cancelled concurrency behavior and ruleset mapping. Do not bypass protection.
**Deliberate failure does not make stable red.** Confirm manual input is boolean true, workflow runs from default branch and stable job reached the final step. Inspect conclusion versus matrix experimental settings.
**Workflow modifies tracked files.** `git diff --exit-code` correctly fails. Identify generated output or test mutation; ignore only genuine generated state and keep deterministic tests.
## What not to do in 26.04 Step 7
- Do not assume a non-GitHub provider supports this workflow syntax.
- Do not make the Ubuntu 26.04 public-preview lane the sole required gate.
- Do not use floating action tags in the committed workflow.
- Do not grant write token permissions, persist checkout credentials or add secrets.
- Do not use `pull_request_target` to execute untrusted pull-request code.
- Do not run untrusted code on the customer workstation or persistent internal runner.
- Do not cache venvs, secrets or executable state without a threat model.
- Do not install dependencies outside fresh `.venv-ci` or bypass the reviewed lock.
- Do not push workflow changes directly to protected `main` or hide the refspec.
- Do not require a check before proving red, recovered green and merge enforcement.
| Ubuntu 26.04 Step 7 gate | Pass condition | Corrective direction |
|---|---|---|
| provider/policy | GitHub Actions and billing approved | translate or obtain approval |
| workflow trust | full-SHA official actions; read-only token | fix supply-chain/permissions |
| runners | stable required; 26.04 preview visible | preserve dual-lane contract |
| isolation | fresh Python 3.14 `.venv-ci` | repair interpreter/install |
| quality | lock, checks, probes, compile, tests pass | fix project or runner drift |
| untrusted code | hosted ephemeral, no secrets/target | remove privileged exposure |
| qualification | intentional red then recovered green | prove behavior before rule |
| enforcement | unique stable check blocks protected main | repair ruleset/status mapping |
## Ubuntu 26.04 LTS Python Setup Step 7 completion gate
Step 7 is complete only when GitHub Actions use is approved; workflow changes travel through a reviewed branch/PR; official checkout/setup actions are pinned to verified full SHAs; token permission is only `contents: read`; checkout credentials, secrets, caches, target-context triggers and persistent runners are absent; explicit Python 3.14 creates a fresh `.venv-ci`; the reviewed wheel-only lock, prefix proof, dependency checks, probes, compile, unittest and clean-tree gates pass; stable Ubuntu 24.04 is a uniquely named required check; Ubuntu 26.04 preview produces visible exact-OS evidence without being the sole blocker; deliberate manual failure turns the stable check red and a normal rerun restores green; and protected `main` demonstrably requires the stable current-head result.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git log -2 --oneline --decorate
git show --stat --summary HEAD
sed -n '1,260p' .github/workflows/python-ci.yml
git ls-remote --heads origin refs/heads/main
.venv/bin/python --version
.venv/bin/python -m pip check
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
Retain the GitHub run IDs for stable/preview PR, merged-main, deliberate-red and recovered-green executions plus ruleset enforcement evidence.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 8**: add measured line/branch coverage and static quality checks under the same Python 3.14 trust model, set evidence-based thresholds, keep check-versus-fix behavior separate, reproduce locally and in CI, qualify failures, and extend the protected ruleset without introducing broad tokens or unpinned tooling.
**Ubuntu 26.04 LTS Python Setup Step 7 succeeds when a least-privilege, immutable-action CI workflow repeatedly rebuilds and tests Python 3.14 on a stable required Ubuntu lane plus visible Resolute preview parity, and proven red/green behavior is enforced on protected main.**
**Ubuntu 26.04 LTS Python Setup Step 8 is to add a reproducible Python 3.14 quality contract to the Step 7 repository: review and lock Ruff, mypy and Coverage.py; measure the existing baseline before setting policy; keep diagnostic checks separate from local fixes; run lint, format, typing, tests and branch coverage through one fail-fast entry point; reproduce it in a clean venv; then make the same aggregate gate run in both existing CI lanes.**
This step assumes Steps 1–7 are complete and the customer-owned GitHub repository is already protected by the uniquely named `Python 3.14 / stable` check. It does not replace unittest with a score, make the Ubuntu 26.04 preview runner required, or let a formatter rewrite pull-request code in CI.
| Quality surface | Step 8 contract | Evidence |
|---|---|---|
| tool supply chain | reviewed Python 3.14 wheels | dry-run report and approved metadata |
| reproducibility | exact full-environment lock | clean wheel-only replay and freeze diff |
| lint | Ruff selected rules | `ruff check` exits zero |
| formatting | observation only in CI | `ruff format --check` exits zero |
| typing | mypy targets Python 3.14 | explicit source/test scope passes |
| tests | existing unittest suite | behavior still passes |
| coverage | line plus branch measurement | evidence-based floor, missing lines shown |
| CI | one fail-fast `quality_gate.py` | stable and Resolute lanes run same command |
## Reconfirm the Step 7 baseline
Run as the normal user from the existing repository:
```bash
cd ~/projects/resolute-python-lab
git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
git status --short --branch
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python -m pip check
.venv/bin/python -m unittest discover -v -s tests -p 'test_*.py'
```
Require a clean tree, reviewed `main`, Python 3.14, true venv isolation and passing tests. Every `python -c` or `python3 -c` command in this guide is one physical line.
If the CI check, dependency lock, probes or tests are already red, return to the owning step. Adding quality tools to a broken baseline destroys useful attribution.
## Define what each tool can and cannot prove
Ruff detects the selected syntax, import and style defects and checks formatter conformance. mypy analyzes declared type contracts without executing every path. Coverage.py reports which executable lines and branch destinations the tests traversed. unittest still determines whether asserted behavior is correct.
None proves absence of defects or vulnerabilities. A high coverage number can come from weak assertions; mypy can contain `Any`; a clean linter does not validate requirements. Keep all four signals and investigate their findings rather than optimizing a dashboard number.
## Review current Python 3.14 candidates
As of August 2, 2026, the review candidates are Coverage.py 7.15.2, mypy 2.3.0 and Ruff 0.15.22. Upstream metadata advertises Python 3.14 support. Versions change, so use these only after the customer's package source, license, maintainer, release notes and wheel artifacts are approved.
Create an isolated review plan without changing the current venv:
```bash
.venv/bin/python -m pip install --dry-run --ignore-installed --only-binary=:all: --report quality-install-plan.json 'coverage==7.15.2' 'mypy==2.3.0' 'ruff==0.15.22'
.venv/bin/python -c "import json; p=json.load(open('quality-install-plan.json', encoding='utf-8')); print('\n'.join(f\"{x['metadata']['name']}=={x['metadata']['version']} | {x['download_info']['url']}\" for x in p['install']))"
```
Review every planned direct and transitive distribution, source host, filename, supported tag, SHA-256 and license against customer policy. A wheel-only plan avoids executing an unreviewed source build, but installation still places third-party executable code in the venv.
Do not use `sudo pip`, `pip install --user`, an IDE's global installer or an unqualified moving `latest`. Do not treat a package name as proof of publisher identity.
## Create a dedicated quality branch
Start only after candidate approval:
```bash
git switch -c quality/python-3.14
```
If that branch exists locally or remotely, stop and inspect it. Do not reset or overwrite another person's work.
## Install approved tools only into `.venv`
Install exact candidates through the venv interpreter:
```bash
.venv/bin/python -m pip install --only-binary=:all: 'coverage==7.15.2' 'mypy==2.3.0' 'ruff==0.15.22'
.venv/bin/python -m pip check
.venv/bin/python -m coverage --version
.venv/bin/python -m mypy --version
.venv/bin/python -m ruff --version
.venv/bin/python -c "from importlib.metadata import version; print(version('coverage')); print(version('mypy')); print(version('ruff'))"
```
The output must match the approved versions. Calling tools with `.venv/bin/python -m ...` binds them to the reviewed interpreter instead of an unrelated executable found on `PATH`.
## Create the direct quality input and exact lock
Create `requirements-quality.in`:
```text
-r requirements.in
coverage==7.15.2
mypy==2.3.0
ruff==0.15.22
```
Then capture the complete installed environment:
```bash
.venv/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-quality-lock.txt
sed -n '1,240p' requirements-quality-lock.txt
```
The lock intentionally includes application dependencies, tool dependencies, and packaging components present in the accepted environment. Inspect it line by line. Do not hand-edit resolver output merely to make a diff attractive.
For a larger production project, prefer the organization's approved hash-generating lock workflow and index policy. This compact lab preserves the Step 4 exact-freeze model; it does not claim a version-only lock provides artifact-hash integrity for every platform.
## Replay the lock before writing policy
Recreate a second environment from nothing:
```bash
python3.14 -m venv .venv-quality-check
.venv-quality-check/bin/python --version
.venv-quality-check/bin/python -m pip install --only-binary=:all: --requirement requirements-quality-lock.txt
.venv-quality-check/bin/python -m pip check
.venv-quality-check/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-quality-replay.txt
diff -u requirements-quality-lock.txt requirements-quality-replay.txt
.venv-quality-check/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
```
Require Python 3.14, true isolation, successful wheel-only installation, `pip check` success and an empty freeze diff. If replay fails, diagnose package availability, index selection, platform tag or lock state; do not relax wheel-only policy silently.
## Add precise local-state ignores
Review the existing `.gitignore`, then add only missing rules:
```gitignore
.venv-quality-check/
.coverage
htmlcov/
.ruff_cache/
.mypy_cache/
quality-install-plan.json
requirements-quality-replay.txt
```
Do not ignore `pyproject.toml`, the quality input/lock, source files, tests, workflow or `quality_gate.py`. Generated local caches are disposable; policy is reviewable source.
## Measure before selecting a threshold
First run discovery without auto-fix and without an invented coverage floor:
```bash
.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format --check .
.venv/bin/python -m mypy resolute_probe.py dependency_probe.py editor_probe.py tests
.venv/bin/python -m coverage erase
.venv/bin/python -m coverage run --branch --source=editor_probe -m unittest discover -v -s tests -p 'test_*.py'
.venv/bin/python -m coverage report --show-missing
```
Save the exact baseline results. Classify failures: a real defect, an explicit project convention, generated/vendor content that should be narrowly excluded, or a typing boundary needing a justified annotation. Never blanket-ignore the repository, add broad `# noqa`/`type: ignore`, or lower a threshold to hide a regression.
For this Step 6 lab, choose `80` only if the measured line-plus-branch total is at least 80%. If it is lower, improve meaningful tests first or record an approved floor at or below the measured baseline. A threshold must prevent regression without pretending untested code is trusted.
## Configure one policy file
Create project-root `pyproject.toml`:
```toml
[tool.ruff]
target-version = "py314"
line-length = 100
extend-exclude = [
".venv",
".venv-check",
".venv-replay",
".venv-ci",
".venv-quality-check",
]
[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "I"]
[tool.ruff.format]
preview = false
[tool.mypy]
python_version = "3.14"
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
exclude = '(^|/)[.]venv'
[tool.coverage.run]
branch = true
source = ["editor_probe"]
omit = ["tests/*"]
[tool.coverage.report]
show_missing = true
skip_covered = false
fail_under = 80
```
Use the approved measured floor if it is not 80. Ruff's selected rule families cover import sorting, serious syntax/name errors and a conservative initial style set. Expand them through reviewed, separately qualified changes—not a surprise all-rules switch.
The mypy scope in the command is authoritative and explicit. Its exclusion only prevents venv traversal. Coverage measures `editor_probe` because that is the tested application module in this lab; production repositories should name their actual import package(s), not copy this placeholder.
## Remediate findings without hiding them
Run the checks again and inspect every diagnostic. For example, if mypy correctly flags an assumed SQLite row in `resolute_probe.py`, preserve runtime safety with an explicit check:
```python
row = database.execute("select sqlite_version()").fetchone()
if row is None:
raise RuntimeError("SQLite version query returned no row")
sqlite_version = str(row[0])
```
Make a change only when the actual diagnostic and program contract justify it. Rerun the probe and tests after semantic edits.
Ruff's fix commands are local authoring tools:
```bash
.venv/bin/python -m ruff check --fix .
.venv/bin/python -m ruff format .
git diff -- .
```
Run them only after a clean checkpoint and review their entire diff. CI uses `check` and `format --check` only. An automated gate must report the submitted revision, not mutate it and test a different tree.
## Create one aggregate quality entry point
Create `quality_gate.py`:
```python
from __future__ import annotations
import shlex
import subprocess
import sys
def run(*arguments: str) -> None:
command = [sys.executable, *arguments]
print("+", shlex.join(command), flush=True)
subprocess.run(command, check=True)
def main() -> None:
run("-m", "pip", "check")
run("-m", "ruff", "check", ".")
run("-m", "ruff", "format", "--check", ".")
run("-m", "mypy", "resolute_probe.py", "dependency_probe.py", "editor_probe.py", "tests")
run("resolute_probe.py")
run("dependency_probe.py")
run("editor_probe.py")
run("-m", "coverage", "erase")
run("-m", "coverage", "run", "-m", "unittest", "discover", "-v", "-s", "tests", "-p", "test_*.py")
run("-m", "coverage", "report")
if __name__ == "__main__":
main()
```
This uses `sys.executable` so every subprocess stays in the invoking venv. Argument lists avoid shell parsing. `check=True` stops at the first failed contract, while the printed command makes local and CI logs auditable.
Run it in both accepted environments:
```bash
.venv/bin/python quality_gate.py
.venv-quality-check/bin/python quality_gate.py
git status --short
```
Both must pass. Only ignored caches/coverage data may appear. A tracked-file diff after the gate is a defect because the CI workflow will retain Step 7's `git diff --exit-code` proof.
## Qualify each failure boundary locally
Before committing, prove the gate rejects representative defects without committing them:
1. Add an unused import to a probe, run the gate, require Ruff failure, then restore only that deliberate edit.
2. Add a clear incompatible annotated assignment, require mypy failure, then restore it.
3. Temporarily set `fail_under = 101`, require Coverage.py exit nonzero, then restore the measured approved floor.
4. Run the unchanged aggregate gate and require green recovery.
Use `git diff` before and after every trial. Do not use destructive repository-wide reset commands, leave a failure staged, or call formatter auto-fix as the recovery mechanism. Retain concise command/output evidence without customer data.
## Update the Step 7 workflow
Edit `.github/workflows/python-ci.yml` without changing its triggers, permissions, full action SHAs, matrix labels, timeout, preview treatment or deliberate-failure input.
In **Recreate isolated environment**, install the quality lock:
```yaml
.venv-ci/bin/python -m pip install --only-binary=:all: --requirement requirements-quality-lock.txt
```
Replace the old compile/probe/test block with:
```yaml
- name: Run reproducible quality gate
shell: bash
run: |
set -euo pipefail
.venv-ci/bin/python -m compileall -q resolute_probe.py dependency_probe.py editor_probe.py quality_gate.py tests
.venv-ci/bin/python quality_gate.py
git diff --exit-code
```
Keep `permissions: contents: read`, `persist-credentials: false`, no secrets/caches, `ubuntu-24.04` stable required, and `ubuntu-26.04` Resolute preview informational. The existing uniquely named stable job now includes all Step 8 checks, so its ruleset mapping need not be renamed.
Do not introduce a floating formatter action, third-party coverage uploader, write token, artifact containing source, `pull_request_target`, or automatic fixes. Console coverage output is sufficient for this step.
## Audit configuration and staged scope
Check for expected declarations and split commands:
```bash
grep -nE 'target-version|python_version|branch|fail_under|select' pyproject.toml
grep -nE 'ruff|mypy|coverage|unittest' quality_gate.py
grep -nE 'requirements-quality-lock|quality_gate.py|contents: read|ubuntu-26.04' .github/workflows/python-ci.yml
grep -RInE 'python3? -c `$' . --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.venv-quality-check || true
```
Stage an exact allowlist, adding `resolute_probe.py` only if a reviewed real typing fix was necessary:
```bash
git add --dry-run -- .gitignore pyproject.toml requirements-quality.in requirements-quality-lock.txt quality_gate.py .github/workflows/python-ci.yml
git add -- .gitignore pyproject.toml requirements-quality.in requirements-quality-lock.txt quality_gate.py .github/workflows/python-ci.yml
git status --short
git diff --cached --name-status
git diff --cached --check
git diff --cached -- .
```
If source remediation is required, inspect it separately, then explicitly stage that one file. Reject unrelated, generated, credential, venv, cache or coverage artifacts.
Search staged content for disclosure and policy mistakes:
```bash
git grep --cached -nI -E '(password|passwd|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' || true
git grep --cached -nI -E 'ruff (check --fix|format \.)( |$)' -- .github || true
git grep --cached -nI -E 'uses: [^ ]+@(main|master|v[0-9]+)$' -- .github || true
```
The workflow should contain no fix command, secret value or floating action reference.
## Commit, push and review through a pull request
Verify branch and approved author identity, then commit:
```bash
git branch --show-current
git config --get --show-origin user.name
git config --get --show-origin user.email
git var GIT_AUTHOR_IDENT
git commit -m "quality: add Python 3.14 static and coverage gates"
git show --stat --summary HEAD
```
Push only the explicit quality branch after a dry run:
```bash
git push --dry-run --porcelain origin refs/heads/quality/python-3.14:refs/heads/quality/python-3.14
git push --set-upstream origin refs/heads/quality/python-3.14:refs/heads/quality/python-3.14
```
Open a customer-reviewed pull request to protected `main`. Confirm the diff contains the exact lock/config/gate/workflow changes, both CI lanes invoke the same aggregate gate, and `Python 3.14 / stable` is green for the current head. Inspect the preview lane's actual log even though infrastructure failure is allowed while the runner remains preview.
## Reprove CI red and green
The local trials prove individual contracts. After merge, use the existing Step 7 `workflow_dispatch` boolean to prove the protected aggregate job can still become red after all real Step 8 checks pass, then rerun with the boolean false to recover green.
Record commit SHA, run IDs, runner images, Python/tool versions, aggregate command output, coverage total, deliberate-red conclusion and recovered-green conclusion. Do not break main code or alter the coverage floor just to produce provider evidence.
Because the job name remains `Python 3.14 / stable`, verify the current branch ruleset still points to that exact check and a pull request cannot merge with it pending or failing. Do not add the preview check as a required blocker until its runner image is stable and formally qualified.
## Evidence and maintenance contract
Retain candidate review, dry-run report summary, exact quality lock, clean replay diff, baseline diagnostics, approved threshold rationale, configuration review, individual red/recovery trials, pull-request review, both CI logs, merged-main green run and branch-enforcement evidence.
Tool upgrades are supply-chain and policy changes. Review release notes, Python 3.14 wheels and dependencies; regenerate and replay the entire lock; run local individual/aggregate red-green qualification; then use a new pull request. Ruff minor releases can change behavior, mypy can surface new typing findings and coverage measurement can change, so never silently float them.
Coverage data and caches are local evidence, not durable source. Do not upload them to a third party without customer approval, retention review, scoped credentials and source-disclosure analysis.
## Troubleshooting
**Ruff reports the venv.** Confirm the config is at repository root and exclusions match the actual venv names. Do not exclude all hidden directories.
**`ruff format --check` fails.** Review `ruff format --diff` locally, apply formatting only on the author branch, inspect the diff, then rerun every gate. Never switch CI to mutation.
**mypy reports missing imports.** Confirm packages/stubs and import paths in the reviewed lock. Do not globally set `ignore_missing_imports = true` without a documented boundary decision.
**mypy sees SQLite `fetchone()` as optional.** Add a real `None` guard where runtime absence is an error; do not cast away the possibility.
**Coverage says no data collected.** Verify `source` names an importable application module and unittest actually imports it. Run with the same venv and working directory.
**Coverage floor fails after adding code.** Inspect missing lines/branches and add meaningful assertions or obtain an explicit policy change. Do not exclude new code or lower the floor reflexively.
**Clean replay differs.** Compare packaging-tool and dependency versions, index, architecture and Python patch version. Regenerate from an accepted clean environment; do not edit the replay output.
**Ruff/mypy command is not found.** Invoke through the correct venv's `python -m`; verify the quality lock was installed, not the runtime-only lock.
**CI passes locally but fails format.** Confirm both use the exact lock/config and that no local untracked config changes are influencing results. Inspect line endings and the submitted SHA.
**CI modifies tracked files.** The gate contains checks only. Identify a probe/test side effect or generated file and correct its ownership; do not remove `git diff --exit-code`.
**Preview lane alone fails.** Classify Ubuntu 26.04 compatibility versus preview infrastructure. Keep stable required, retain visible evidence and track remediation.
**Required check disappears.** Preserve workflow/job names and trigger coverage, then inspect ruleset mapping/current head. Treat renaming as a governed migration.
## What not to do in Step 8
- Do not install quality tools globally, with sudo or outside the project venv.
- Do not float tool versions or skip the clean wheel-only replay.
- Do not select a coverage floor before measuring the accepted baseline.
- Do not equate coverage percentage with correctness.
- Do not enable every Ruff/mypy strict rule in one unexplained migration.
- Do not hide findings with repository-wide exclusions or blanket ignores.
- Do not let CI run `ruff check --fix`, `ruff format` or any source mutation.
- Do not use different local and CI entry points or dependency locks.
- Do not rename the protected stable job casually.
- Do not grant tokens, secrets, caches, uploaders or persistent runners for these checks.
| Ubuntu 26.04 Step 8 gate | Pass condition | Corrective direction |
|---|---|---|
| baseline | Step 7 clean and green | repair owning step first |
| candidates | identity, release, wheel and license reviewed | reject or reselect tool version |
| lock/replay | exact lock recreates wheel-only with empty diff | fix resolver/index/platform drift |
| Ruff | lint and format checks pass without mutation | review finding/local diff |
| mypy | explicit Python 3.14 scope passes | repair types or justify narrow boundary |
| tests/coverage | behavior passes; measured branch floor holds | add meaningful assertions |
| aggregate gate | both local venvs run identical entry point | fix executable/config mismatch |
| CI/enforcement | stable required; preview visible; red/green proven | repair workflow or ruleset |
## Ubuntu 26.04 LTS Python Setup Step 8 completion gate
Step 8 is complete only when the Step 7 baseline is green; Coverage.py, mypy and Ruff candidates have explicit Python 3.14/package review; exact versions are installed only in `.venv`; a complete quality lock replays wheel-only in a clean `.venv-quality-check` with no freeze difference; diagnostic results are reviewed before an evidence-based coverage floor is selected; `pyproject.toml` records narrow Ruff, Python 3.14 mypy and branch-coverage policy; `quality_gate.py` binds every subprocess to `sys.executable`; Ruff lint/format checks, typing, probes, unittest and coverage pass locally and in the clean replay; representative Ruff, mypy and coverage failures are individually proven and cleanly recovered; CI installs the quality lock and runs the same non-mutating aggregate gate on stable Ubuntu plus visible Resolute preview; the merged current-head stable check is green; deliberate red/recovered green evidence remains valid; and protected `main` still requires exactly `Python 3.14 / stable` without new secrets or write permission.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git log -2 --oneline --decorate
.venv/bin/python -m pip check
.venv/bin/python -m ruff --version
.venv/bin/python -m mypy --version
.venv/bin/python -m coverage --version
.venv/bin/python quality_gate.py
.venv-quality-check/bin/python quality_gate.py
diff -u requirements-quality-lock.txt requirements-quality-replay.txt
git show --stat --summary HEAD
```
Retain the approved threshold rationale and CI run IDs with the commit SHA. Do not retain credentials, private package URLs, unrelated customer files, complete event payloads or local personal paths.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 9**: add an approved dependency-vulnerability and software-bill-of-materials workflow around the exact runtime/quality locks, define triage and exception ownership, generate evidence without publishing private dependency data, and keep advisory scanning distinct from deterministic build/test acceptance.
**Ubuntu 26.04 LTS Python Setup Step 8 succeeds when one reviewed Python 3.14 environment and one reproducible command make lint, format conformance, static typing, behavior and measured branch coverage equally observable locally and in CI—without hidden fixes, floating tools or broader trust.**
**Ubuntu 26.04 LTS Python Setup Step 9 is to add governed dependency intelligence to the Step 8 Python 3.14 repository: review and exactly lock an advisory scanner plus CycloneDX generator, build a reproducible runtime-only SBOM, scan the fully pinned runtime lock for known vulnerabilities, triage every finding against actual exposure, permit only owner-approved expiring exceptions, and run a least-privilege scheduled/manual CI workflow without silently changing dependencies or publishing private inventory.**
This step separates two different kinds of evidence. The SBOM is a deterministic inventory derived from the reviewed runtime lock. Vulnerability status is time-dependent external intelligence: the same commit can become vulnerable tomorrow when a new advisory appears. Treat the first as reproducible build evidence and the second as a monitored security decision, not as interchangeable pass/fail signals.
| Supply-chain surface | Step 9 policy | Acceptance evidence |
|---|---|---|
| runtime inventory | CycloneDX JSON from runtime lock only | validated reproducible SBOM and diff |
| scanner/tooling | reviewed Python 3.14 wheels | dry-run report and exact security lock |
| advisory source | approved PyPI advisory service | timestamp, service and result IDs |
| resolution | fully pinned input, `--no-deps` | no surprise resolver/install behavior |
| findings | applicability and fixed-version triage | owner, due date and remediation branch |
| exceptions | explicit ID, rationale, expiry, approval | machine-checked narrow registry |
| automation | read-only scheduled/manual job | current green or accountable red result |
| privacy | no public artifact/upload by default | reviewed logs and customer-held evidence |
## Reconfirm the Step 8 trust baseline
Run locally as the normal Ubuntu user:
```bash
cd ~/projects/resolute-python-lab
git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
git status --short --branch
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
.venv/bin/python quality_gate.py
diff -u requirements-quality-lock.txt requirements-quality-replay.txt
```
Require reviewed `main`, a clean tree, Python 3.14, true isolation, a green aggregate quality gate and the accepted Step 8 lock/replay state. Every `python -c`/`python3 -c` command in this guide occupies one physical line.
Do not add a security scanner while an existing quality or dependency baseline is red. Fix the owning step first so new evidence remains attributable.
## Approve scope, data flow and ownership
The customer must name the runtime lock, advisory service/network route, triage and exception approvers, response deadlines, SBOM classification/recipients/retention, release escalation, scan cadence and missed-run monitor. Dependency graphs and private URLs can disclose architecture, so a private repository does not authorize third-party SBOM upload.
This tutorial uses the documented public PyPI advisory service. Qualify OSV/internal alternatives separately. `pip-audit` finds known Python-distribution advisories; it is not malware, source, Ubuntu, native-library, container or exploitability analysis. Keep those controls separate and document reachability before excepting any match.
## Review current Python 3.14 security-tool candidates
As of August 2, 2026, review these exact candidates:
```text
pip-audit==2.10.1
cyclonedx-bom==7.3.1
```
`pip-audit` 2.10.1 declares Python 3.14 support and publishes a universal wheel. CycloneDX Python 7.3.1 requires Python 3.9 or newer and supports validated JSON generation from pip requirements.
Create a non-mutating installation plan:
```bash
.venv/bin/python -m pip install --dry-run --ignore-installed --only-binary=:all: --report security-install-plan.json 'pip-audit==2.10.1' 'cyclonedx-bom==7.3.1'
.venv/bin/python -c "import json; p=json.load(open('security-install-plan.json', encoding='utf-8')); print('\n'.join(f\"{x['metadata']['name']}=={x['metadata']['version']} | {x['download_info']['url']}\" for x in p['install']))"
```
Review all planned identities, releases, owners, licenses, sources, wheel tags, hashes and provenance. The scanner is network-capable third-party code, not a trust exemption. Fully pinned runtime input plus `--no-deps` avoids its resolver path.
## Create a dedicated branch
Start from verified `main`:
```bash
git switch -c security/python-dependency-evidence
```
If it already exists locally or remotely, inspect its owner and history. Do not reset, delete or overwrite it.
## Isolate security tooling from runtime inventory
Install exact approved tools into the project venv for authoring:
```bash
.venv/bin/python -m pip install --only-binary=:all: 'pip-audit==2.10.1' 'cyclonedx-bom==7.3.1'
.venv/bin/python -m pip check
.venv/bin/python -m pip_audit --version
.venv/bin/python -m cyclonedx_py --version
.venv/bin/python -c "from importlib.metadata import version; print(version('pip-audit')); print(version('cyclonedx-bom'))"
```
Create `requirements-security.in`:
```text
-r requirements-quality.in
pip-audit==2.10.1
cyclonedx-bom==7.3.1
```
Capture the complete accepted environment:
```bash
.venv/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-security-lock.txt
sed -n '1,260p' requirements-security-lock.txt
```
The security lock contains runtime, quality and scan tools for CI. SBOM/audit input remains runtime-only `requirements-lock.txt`; otherwise tools appear as shipped dependencies. Inventory extras, OS/container/browser components and services separately.
## Replay the security toolchain cleanly
Create a separate disposable environment:
```bash
python3.14 -m venv .venv-security-check
.venv-security-check/bin/python -m pip install --only-binary=:all: --requirement requirements-security-lock.txt
.venv-security-check/bin/python -m pip check
.venv-security-check/bin/python -m pip freeze --all | LC_ALL=C sort > requirements-security-replay.txt
diff -u requirements-security-lock.txt requirements-security-replay.txt
.venv-security-check/bin/python -c "import sys; print(sys.executable); print(sys.version_info); print(sys.prefix != sys.base_prefix)"
```
Require an empty freeze diff, Python 3.14 and true venv isolation. Investigate index, wheel tag, platform and lock differences rather than weakening wheel-only recreation.
## Add only disposable-state ignores
Review `.gitignore`, then add missing narrow rules:
```gitignore
.venv-security-check/
security-install-plan.json
requirements-security-replay.txt
security-audit-result.json
sbom.cdx.candidate.json
```
Do not ignore the committed SBOM, security input/lock, workflow, scan controller or exception registry. Do not write tokens or private index credentials into pip configuration, requirements files, URLs, logs or the SBOM.
## Generate a validated reproducible runtime SBOM
Generate CycloneDX 1.6 JSON from the reviewed runtime lock:
```bash
.venv/bin/python -m cyclonedx_py requirements requirements-lock.txt --spec-version 1.6 --output-format JSON --output-reproducible --output-file sbom.cdx.candidate.json
.venv/bin/python -c "import json; p=json.load(open('sbom.cdx.candidate.json', encoding='utf-8')); print(p['bomFormat'], p['specVersion'], len(p.get('components', [])), len(p.get('dependencies', [])))"
```
Require `CycloneDX`, spec 1.6, the expected runtime components/dependency graph and no validation error. Inspect the entire JSON for private URLs, user paths, credentials, unexpected tools and component mistakes.
Prove determinism:
```bash
cp sbom.cdx.candidate.json sbom.cdx.first.json
.venv/bin/python -m cyclonedx_py requirements requirements-lock.txt --spec-version 1.6 --output-format JSON --output-reproducible --output-file sbom.cdx.candidate.json
sha256sum sbom.cdx.first.json sbom.cdx.candidate.json
cmp -s sbom.cdx.first.json sbom.cdx.candidate.json
mv sbom.cdx.candidate.json sbom.cdx.json
```
Remove the temporary first copy after comparison and ensure it is not staged. `--output-reproducible` intentionally removes time/random variability; it does not prove input completeness or artifact authenticity.
Record the SBOM hash alongside the source commit and runtime-lock hash. Signing/attestation is a separate customer key-management and provenance workflow; do not improvise a personal signing key.
## Create the exception registry empty first
Create `security-advisory-exceptions.json`:
```json
{
"schema_version": 1,
"exceptions": []
}
```
Never pre-populate exceptions. A reviewed real entry must contain exactly `id`, `package`, `version`, `reason`, `compensating_control`, `owner`, `approved_by`, `approved_on`, `expires_on` and `ticket`. Prohibit credentials, vague “false positive,” wildcards, missing/far-future expiry and verbal approval. Expired or stale records fail.
## Remediate before excepting
Prefer a reviewed fixed direct/transitive version, regenerate and replay every dependent lock, rerun quality/SBOM/audit, deploy through change control, verify production, then close. If no fix works, evaluate removal, replacement, feature/network isolation or a vendor backport before a narrow temporary residual-risk approval. Never use `pip-audit --fix`; it bypasses review, locking and tests.
## Create a policy controller
Create `security_scan.py` to make exception behavior explicit:
```python
from __future__ import annotations
import datetime as dt
import json
import subprocess
import sys
from pathlib import Path
AUDIT = Path("security-audit-result.json")
EXCEPTIONS = Path("security-advisory-exceptions.json")
def main() -> None:
policy = json.loads(EXCEPTIONS.read_text(encoding="utf-8"))
if policy.get("schema_version") != 1 or not isinstance(policy.get("exceptions"), list):
raise SystemExit("invalid exception registry schema")
today = dt.date.today()
approved: dict[tuple[str, str, str], dict[str, object]] = {}
required = {"id", "package", "version", "reason", "compensating_control", "owner", "approved_by", "approved_on", "expires_on", "ticket"}
for item in policy["exceptions"]:
if not isinstance(item, dict) or set(item) != required:
raise SystemExit("invalid exception fields")
expiry = dt.date.fromisoformat(str(item["expires_on"]))
if expiry < today:
raise SystemExit(f"expired exception: {item['id']}")
key = (str(item["id"]), str(item["package"]).lower(), str(item["version"]))
if key in approved:
raise SystemExit(f"duplicate exception: {key}")
approved[key] = item
command = [sys.executable, "-m", "pip_audit", "--requirement", "requirements-lock.txt", "--no-deps", "--format", "json", "--output", str(AUDIT), "--progress-spinner", "off"]
completed = subprocess.run(command, check=False)
if completed.returncode not in (0, 1) or not AUDIT.is_file():
raise SystemExit(f"audit operational failure: {completed.returncode}")
report = json.loads(AUDIT.read_text(encoding="utf-8"))
active: set[tuple[str, str, str]] = set()
unapproved: list[tuple[str, str, str]] = []
for dependency in report.get("dependencies", []):
package = str(dependency["name"]).lower()
version = str(dependency["version"])
for vulnerability in dependency.get("vulns", []):
key = (str(vulnerability["id"]), package, version)
active.add(key)
if key not in approved:
unapproved.append(key)
stale = set(approved) - active
print(f"known={len(active)} approved={len(active & set(approved))} unapproved={len(unapproved)} stale={len(stale)}")
for key in sorted(unapproved):
print("UNAPPROVED", *key)
for key in sorted(stale):
print("STALE_EXCEPTION", *key)
if unapproved or stale:
raise SystemExit(1)
if __name__ == "__main__":
main()
```
This permits only exact advisory/package/version tuples, rejects expired/duplicate/stale records and distinguishes a scanner operational failure. It prints IDs and versions, not advisory descriptions or private URLs. Review the current `pip-audit` JSON schema during every tool upgrade.
Run locally:
```bash
.venv/bin/python security_scan.py
.venv-security-check/bin/python security_scan.py
```
Both should have the same policy result. If known findings exist, keep the result red until fixed or an authorized exception change is reviewed. Do not add `|| true` to manufacture green.
## Verify SBOM regeneration in CI without committing noise
Create `verify_sbom.py`:
```python
from __future__ import annotations
import json
import subprocess
import sys
import tempfile
from pathlib import Path
def main() -> None:
committed = Path("sbom.cdx.json").read_bytes()
with tempfile.TemporaryDirectory() as directory:
candidate = Path(directory) / "sbom.cdx.json"
subprocess.run([sys.executable, "-m", "cyclonedx_py", "requirements", "requirements-lock.txt", "--spec-version", "1.6", "--output-format", "JSON", "--output-reproducible", "--output-file", str(candidate)], check=True)
generated = candidate.read_bytes()
if generated != committed:
raise SystemExit("SBOM differs from requirements-lock.txt; regenerate and review")
document = json.loads(committed)
if document.get("bomFormat") != "CycloneDX" or document.get("specVersion") != "1.6":
raise SystemExit("unexpected SBOM format/specification")
print(f"SBOM verified: components={len(document.get('components', []))}")
if __name__ == "__main__":
main()
```
Run it in both venvs. Temporary output stays outside the repository and the committed SBOM must be byte-identical.
## Add the deterministic SBOM check to existing CI
In `.github/workflows/python-ci.yml`, install `requirements-security-lock.txt` in `.venv-ci` and add this before `git diff --exit-code`:
```yaml
.venv-ci/bin/python verify_sbom.py
```
This extends the existing stable required check with deterministic inventory consistency. Keep action SHAs, triggers, read-only permission, preview treatment and job names unchanged. Do not add the live advisory request to this required pull-request gate yet: mutable network intelligence can change independently of the submitted commit and requires explicit operational ownership.
## Create a scheduled/manual advisory workflow
Create `.github/workflows/python-advisory-scan.yml`:
```yaml
name: Python dependency advisory scan
on:
schedule:
- cron: "17 5 * * *"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: python-dependency-advisory-${{ github.ref }}
cancel-in-progress: false
jobs:
advisory:
name: Python runtime advisories
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: Check out default branch
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
persist-credentials: false
fetch-depth: 1
- name: Set up CPython 3.14
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: "3.14"
- name: Recreate security environment
shell: bash
run: |
set -euo pipefail
python -m venv .venv-security-ci
.venv-security-ci/bin/python -m pip install --only-binary=:all: --requirement requirements-security-lock.txt
.venv-security-ci/bin/python -m pip check
- name: Verify inventory and scan advisories
shell: bash
run: |
set -euo pipefail
.venv-security-ci/bin/python verify_sbom.py
.venv-security-ci/bin/python security_scan.py
git diff --exit-code
```
The schedule runs against the default branch. Confirm repository settings allow scheduled workflows and assign an owner to investigate cancellation, timeout, service failure and red findings. Scheduled workflows can be delayed or disabled after inactivity; a missing run must alert through an approved monitoring path, not count as green.
This example deliberately omits cache, secrets, artifact upload and Ubuntu 26.04 preview. Advisory freshness needs a stable runner and no customer workstation. If the approved feed requires authentication, redesign permission/secret/data flow and fork behavior before adding it.
## Decide enforcement deliberately
The existing `Python 3.14 / stable` remains the required pull-request gate and now verifies SBOM consistency. The scheduled `Python runtime advisories` result is an operational security control. Do not add it as a required PR check unless trigger coverage ensures every pull request gets a current result and the organization accepts external-feed availability as a merge dependency.
For releases, customer policy can require a successful manual advisory run at the exact release commit within a defined freshness window. Record run ID, advisory service, timestamp and commit SHA. “The nightly was green last week” is not release evidence.
## Qualify failures and recovery
Without committing bad state, prove a copied SBOM byte fails then recovers; an expired synthetic exception fails then recovers; an approved-service outage is operational failure rather than green; and a real unapproved finding stays red until fixed or formally excepted. After merge, run the workflow at the merged SHA. Never inject a fake production dependency, commit synthetic policy, use `--fix` or suppress exits.
## Stage an exact reviewed change
Audit commands and disclosure:
```bash
grep -RInE 'pip_audit|cyclonedx_py|--no-deps|output-reproducible' security_scan.py verify_sbom.py .github
grep -RInE '(--fix|pull_request_target|upload-artifact|contents: write)' .github security_scan.py || true
grep -RInE 'python3? -c `$' . --exclude-dir=.git --exclude-dir=.venv --exclude-dir=.venv-security-check || true
```
Stage only:
```bash
git add --dry-run -- .gitignore requirements-security.in requirements-security-lock.txt sbom.cdx.json security-advisory-exceptions.json security_scan.py verify_sbom.py .github/workflows/python-ci.yml .github/workflows/python-advisory-scan.yml
git add -- .gitignore requirements-security.in requirements-security-lock.txt sbom.cdx.json security-advisory-exceptions.json security_scan.py verify_sbom.py .github/workflows/python-ci.yml .github/workflows/python-advisory-scan.yml
git status --short
git diff --cached --name-status
git diff --cached --check
git diff --cached -- .
```
Reject audit results, venvs, replay output, install plans, private URLs, credentials and unrelated changes. Inspect the complete SBOM and executable workflow/controller files.
Search staged data:
```bash
git grep --cached -nI -E '(password|passwd|api[_-]?key|access[_-]?token|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY)' || true
git grep --cached -nI -E '(https?://[^/@:]+:[^/@]+@|--fix|uses: [^ ]+@(main|master|v[0-9]+)$)' || true
```
Package URLs such as `pkg:pypi/...` in CycloneDX are expected; credential-bearing HTTP URLs are not.
## Commit, push and review
Verify `security/python-dependency-evidence` and the approved identity, commit as `security: add Python dependency evidence workflow`, then dry-run and push that exact branch refspec. Use a reviewed PR to protected `main`; require stable/preview quality, byte-identical SBOM, clean security replay, full action SHAs and no secret/upload/write permission. After merge, verify the required stable check at the merged SHA, manually scan it and observe the next scheduled run.
For each finding retain detection source/time, IDs, package/version/owner, reachability, severity context, fixed versions, response, test/deploy evidence, due date, exception approval/expiry and verification. Reopen when intelligence/exposure changes. On every tool upgrade, recheck CLI/JSON schemas, Python support, feed semantics, provenance and exit codes; replay, regenerate and requalify through review. Regenerate the SBOM whenever the runtime lock changes.
## Troubleshooting
**`pip-audit` tries to resolve/install.** Confirm the runtime file is fully pinned and `--no-deps` is present. Do not audit an unconstrained intent file in CI.
**Exit status is 1.** Inspect the JSON. Status 1 means known findings, not scanner malfunction. Triage or remediate; do not append `|| true`.
**Audit service times out.** Classify operational failure, check approved network/proxy/CA/service status and rerun. Never interpret missing intelligence as no vulnerabilities.
**SBOM includes Ruff/mypy/scanner packages.** The wrong input was used. Generate from runtime `requirements-lock.txt`, not the security venv freeze.
**SBOM differs on every run.** Require `--output-reproducible`, exact tool lock, spec version and identical input. Compare JSON fields before accepting.
**An advisory has no fix.** Evaluate removal, replacement, disablement, isolation or backport; use only a narrow expiring approved exception with active tracking.
**Exception is stale.** Remove it through review. Stale allowances are policy debt, not harmless documentation.
**Scheduled workflow did not run.** Check default-branch workflow presence, Actions policy, inactivity, schedule delay and repository status. Monitoring must detect missing runs.
**Stable CI is red after lock change.** Regenerate/review the SBOM and all dependent locks, replay them and rerun every Step 8/9 gate. Scan native Ubuntu packages through their separate APT control.
## Step 9 prohibitions
Do not confuse inventory with scanning; include tools in the runtime SBOM; resolve unconstrained input; use `--fix`; suppress exits/outages; accept broad/unowned/unexpired exceptions; publish inventory without review; add tokens/uploads/persistent runners; accidentally require mutable feed availability on PRs; or claim Python metadata covers Ubuntu, containers, native libraries and application code.
| Ubuntu 26.04 Step 9 gate | Pass condition | Corrective direction |
|---|---|---|
| scope/ownership | runtime boundary, feed, owners and SLA approved | define governance before tooling |
| tool trust | exact candidates and all wheels/dependencies reviewed | reject or select approved versions |
| security replay | full lock recreates wheel-only with empty diff | repair index/platform/lock drift |
| SBOM | validated 1.6 JSON is reproducible and runtime-only | correct input/tool/privacy issue |
| advisory scan | pinned `--no-deps` input and current feed result | triage finding or operational error |
| exceptions | exact, justified, approved, owned and unexpired | remediate/remove/renew through review |
| automation | stable scheduled/manual read-only scan monitored | repair workflow/service/ownership |
| enforcement | SBOM required; mutable scan governed separately | fix CI/ruleset/release policy |
## Ubuntu 26.04 LTS Python Setup Step 9 completion gate
Step 9 is complete only when Step 8 remains green; runtime inventory and advisory data-flow scope are approved; `pip-audit` and CycloneDX candidates plus transitive wheels are reviewed; security tooling is exact-locked and wheel-only replayed in an isolated Python 3.14 venv with an empty freeze diff; a validated reproducible CycloneDX 1.6 JSON SBOM derives only from the runtime lock and is reviewed for completeness/privacy; the fully pinned runtime lock is scanned with resolution disabled; every finding is either remediated and verified or represented by one accountable, justified, approved and unexpired exception; expired, duplicate, stale and unapproved records fail the controller; automatic fixes and suppressed exits are absent; existing required CI verifies inventory deterministically without renaming its stable check; a separate read-only stable-runner schedule/manual workflow obtains current advisory intelligence without secrets, uploads or persistent runners; missing/red runs have named monitoring and response ownership; and merged-commit plus release evidence is retained safely.
Final compact evidence:
```bash
cd ~/projects/resolute-python-lab
git status --short --branch
git log -2 --oneline --decorate
.venv/bin/python quality_gate.py
.venv/bin/python verify_sbom.py
.venv/bin/python security_scan.py
.venv-security-check/bin/python verify_sbom.py
diff -u requirements-security-lock.txt requirements-security-replay.txt
sha256sum requirements-lock.txt sbom.cdx.json
git show --stat --summary HEAD
```
Retain hashes, commit SHA, tool/advisory-source versions, scan timestamp/run ID and triage decisions in customer-approved storage. Do not retain credentials, private index URLs, unrelated customer files or public inventory artifacts.
The next keyword should be **Ubuntu 26.04 LTS Python Setup Step 10**: package the tested application reproducibly, build wheel and source artifacts in a clean Python 3.14 environment, validate metadata/content, generate hashes and provenance, and rehearse installation from the exact artifact without publishing it.
**Ubuntu 26.04 LTS Python Setup Step 9 succeeds when the customer can prove exactly what Python runtime components ship, continuously compare that inventory with current known-advisory intelligence, and drive every exception toward an owned expiry or verified fix without broadening CI trust.**
**Ubuntu Python Setup Step 1 is to establish a trusted, supportable Ubuntu-owned Python base: identify the actual Ubuntu release and architecture, validate official APT repositories, apply reviewed updates, install Python development prerequisites through APT, and prove that `/usr/bin/python3` remains an operating-system-managed interpreter.**
The customer happens to run a fresh Microsoft Store Ubuntu distribution under WSL, but this article is intentionally Ubuntu-centric. WSL registration, Windows launch commands, VS Code remote setup, and project dependency installation have separate owners. Here, every command after launch runs in the Ubuntu shell.
| Surface | Ubuntu Step 1 decision | Evidence |
|---|---|---|
| user | normal account with controlled sudo | `whoami`, `id`, `sudo -v` |
| release | actual supported Ubuntu release | `/etc/os-release` |
| architecture | actual Linux machine architecture | `dpkg --print-architecture` |
| repositories | signed approved Ubuntu sources | APT source files/update |
| updates | reviewed normal package upgrades | clean apt/dpkg state |
| Python | Ubuntu default `python3` | dpkg owner and executable |
| tooling | full runtime/venv/pip prerequisites | apt package status |
| boundary | system Python is not project Python | venv handoff |
## Establish the Ubuntu identity
Open the installed Ubuntu instance and run:
```bash
whoami
id
printf 'home=%s cwd=%s shell=%s\n' "$HOME" "$PWD" "$SHELL"
cat /etc/os-release
uname -r
dpkg --print-architecture
```
Use a normal user, not root. Record `VERSION_ID`, codename, kernel and architecture from the machine rather than copying values from this page. Ubuntu package availability and support depend on the release/architecture.
Test administrative authorization without changing files:
```bash
sudo -v
```
The password is the Ubuntu user password and is intentionally not echoed. Do not configure passwordless sudo for convenience.
## Check release support without upgrading it
Prefer a supported LTS release for a customer development base. Routine package updates stay within the installed release; `do-release-upgrade` changes the operating-system release and is not part of Python Step 1.
Inspect the configured release-upgrade policy read-only:
```bash
cat /etc/update-manager/release-upgrades 2>/dev/null || true
```
Do not edit the policy, enable development releases, or force a release upgrade to obtain a newer Python. A project needing another Python version requires a separate compatibility/install decision and must not replace Ubuntu’s default interpreter.
## Inspect APT sources and trust
List source definitions:
```bash
find /etc/apt/sources.list /etc/apt/sources.list.d -maxdepth 1 -type f -print 2>/dev/null
grep -RhsE '^(deb |Types:|URIs:|Suites:|Components:|Signed-By:)' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null
```
Ubuntu 24.04 and later commonly use deb822 `/etc/apt/sources.list.d/ubuntu.sources`; earlier releases commonly use `/etc/apt/sources.list`. Inspect what exists. Official repositories must have expected release suites and signing-key references.
Do not add a PPA, third-party repository, unsigned key, HTTP mirror, or `[trusted=yes]` to make a tutorial command work. Repository changes affect the whole distribution and require provenance, compatibility, support and rollback review.
On corporate networks, configure approved proxy and CA trust without embedding passwords in URLs or shell history. TLS/signature failures must be diagnosed, never bypassed.
## Refresh and review Ubuntu packages
Run interactively:
```bash
sudo apt update
apt list --upgradable
```
`apt update` refreshes package metadata; it does not install upgrades. Read DNS, TLS, signature, suite and mirror messages. If any official source fails, resolve that before installing Python packages.
Apply normal upgrades after reviewing the plan:
```bash
sudo apt upgrade
```
The guide omits `-y` so the customer sees proposed changes. Packages may be kept back because of phased updates; do not disable phasing or force individual upgrades merely to make the count zero.
Check package-manager consistency and restart evidence:
```bash
sudo dpkg --audit
test -f /run/reboot-required && cat /run/reboot-required || true
```
An empty `dpkg --audit` is expected. Under WSL, restarting Ubuntu/WSL differs from rebooting a physical Ubuntu host; follow the environment owner’s controlled restart procedure. Do not interrupt other distributions with a broad shutdown casually.
## Inspect existing Python before installation
Run:
```bash
command -v python3
type -a python3
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.version)"
```
Ubuntu normally resolves `/usr/bin/python3`. Every `python3 -c` example is one physical line. A Windows `.exe`, `/mnt/c` path, `$HOME/.local` shim or custom `/usr/local` interpreter is not acceptable evidence for the Ubuntu base.
The bare `python` command may be absent; this is not an error. Do not create aliases or symlinks just to imitate another platform.
## Prove package ownership
Ask dpkg which package owns the interpreter:
```bash
dpkg -S "$(readlink -f "$(command -v python3)")"
apt-cache policy python3 python3-full python3-venv python3-pip
dpkg-query -W -f='${Package}\t${Status}\t${Version}\n' python3 2>/dev/null
```
The default Python is part of Ubuntu’s package graph. Many system tools may depend on it. Never remove it, change `/usr/bin/python3`, or use pip to overwrite its libraries.
## Choose the Ubuntu development package set
Ubuntu’s current developer guidance recommends the `python3-full` metapackage for a complete standard-library/runtime experience including venv support, plus pip tooling. Install through APT:
```bash
sudo apt install python3-full python3-pip
```
Review the transaction before approval. On a minimal/customer-controlled image where `python3-full` is intentionally too broad, the bounded alternative is:
```bash
sudo apt install python3 python3-venv python3-pip
```
Choose one approach according to system policy; do not run both blindly. `python3-full` can include tools such as IDLE that are not required on every headless system, while the smaller set explicitly supplies the interpreter, venv module and pip package.
Do not install compilers, headers, databases or scientific stacks until a project dependency demonstrates the need. Keep system footprint justified.
## Verify the installed base
Run:
```bash
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m venv --help
python3 -m pip --version
python3 -c "import ensurepip; print(ensurepip.__file__)" 2>/dev/null || true
```
The executable remains `/usr/bin/python3`. Pip/venv availability means tools exist; it does not authorize project installs into the system interpreter.
Inspect install paths:
```bash
python3 -c "import site; print(site.getsitepackages()); print(site.getusersitepackages())"
python3 -c "import sys; print(sys.prefix); print(sys.base_prefix)"
```
At the base, prefix and base-prefix normally match. Project work later requires a distinct prefix inside a virtual environment.
## Respect the externally managed environment
Modern Ubuntu/Debian marks the system Python environment as externally managed so pip does not overwrite APT-owned packages. This protects operating-system tools and package consistency.
Do not use:
```text
sudo pip install ...
python3 -m pip install --user ...
python3 -m pip install --break-system-packages ...
```
`sudo pip` can replace files outside APT’s database. `--user` can shadow system packages in unpredictable contexts. `--break-system-packages` explicitly bypasses the protection. A project virtual environment is the correct boundary.
For standalone Python CLI applications, a later workflow may use apt or pipx, which isolates applications. That is different from application dependencies inside a project `.venv`.
## Run a standard-library smoke test
Use only local standard-library behavior:
```bash
python3 -c "import json, pathlib, sqlite3, ssl; print('stdlib-ok')"
python3 -c "from pathlib import Path; print(Path.home())"
```
The home path should be the Ubuntu user’s home. This checks imports without internet access, credentials, GUI windows or customer files.
Test UTF-8 and locale facts:
```bash
locale
python3 -c "import locale, sys; print(sys.getfilesystemencoding()); print(locale.getpreferredencoding(False))"
```
Expect UTF-8 in a modern Ubuntu environment. Do not globally rewrite locale configuration to fix one program without understanding terminal, file and process effects.
## Inspect filesystem and disk readiness
For a Linux-first project:
```bash
printf 'home=%s\n' "$HOME"
findmnt -T "$HOME"
df -h "$HOME"
mkdir -p ~/projects
stat -c 'owner=%U mode=%A path=%n' ~/projects
```
The normal user must own `~/projects`. Under WSL, keep Linux-tool projects in the Ubuntu filesystem, not `/mnt/c`, to preserve Linux semantics/performance. Do not create project directories with sudo.
## Capture a non-sensitive baseline
Record facts in support notes, not secrets:
- Ubuntu `VERSION_ID` and codename.
- architecture.
- `python3 --version` and executable.
- dpkg package versions for the chosen Python set.
- whether apt/dpkg audits pass.
- locale/filesystem encoding.
Do not publish username/home, proxy credentials, internal mirror URLs, machine ID, tokens or full environment dumps.
APT actions are logged under `/var/log/apt` and `/var/log/dpkg.log`. Read narrow time/package entries when diagnosing; logs can contain internal repository names.
## System update versus project dependency
APT installs Ubuntu `.deb` packages into the distribution and manages their dependency/security lifecycle. Pip inside a future `.venv` installs Python distributions for one project. Similar names do not make them interchangeable.
Use APT for the base interpreter and system tools. Use an isolated environment plus the project’s declaration/lock policy for application dependencies. Never solve an import failure by installing the same thing through apt, system pip and project pip simultaneously.
## Troubleshooting
**`sudo apt update` fails DNS.** Test `getent hosts archive.ubuntu.com`, Windows/host connectivity and approved proxy. Do not hard-code public DNS without understanding managed resolver behavior.
**Certificate/signature errors.** Verify clock, proxy interception, CA policy, repository URL and Ubuntu keyring. Never use trusted/insecure flags.
**Package is not found.** Confirm release, enabled official components, architecture and a successful update. Do not add a random PPA.
**`dpkg --audit` reports incomplete state.** Preserve the exact message and repair package management before installing Python. Avoid deleting locks or database files.
**Python resolves to `/usr/local`.** Inspect `type -a`, PATH, alternatives, shell startup and prior custom installs. Do not delete until ownership/consumers are known.
**`venv` creation later says ensurepip unavailable.** Install the release-appropriate `python3-venv` through apt; do not download `get-pip.py` for the system interpreter.
**Pip reports externally managed.** That is expected outside a venv. Create/activate a project environment; do not bypass it.
**Packages are kept back.** Determine whether phased or held for another reason. Do not disable phased updates for a beginner setup.
**Disk space is low.** Inspect exact filesystem usage and apt cache; obtain approval before cleanup. Do not recursively delete Ubuntu/WSL package data.
## What not to do in Ubuntu Step 1
- Do not replace, remove or repoint `/usr/bin/python3`.
- Do not run `sudo pip`, `pip --user`, or `--break-system-packages`.
- Do not add untrusted PPAs, keys, mirrors or TLS bypasses.
- Do not force phased updates or a release upgrade.
- Do not work as root or create root-owned project directories.
- Do not mix Windows Python, wheels or virtual environments into Ubuntu.
- Do not install broad build stacks without a dependency need.
- Do not publish repository credentials or complete environment/log dumps.
| Ubuntu Step 1 gate | Pass condition | If it fails |
|---|---|---|
| identity | supported release/arch recorded | resolve support policy |
| repositories | approved signed sources | repair trust/configuration |
| update | apt refresh and reviewed upgrade | fix DNS/TLS/signature |
| package state | `dpkg --audit` empty | repair package database |
| Python owner | `/usr/bin/python3` belongs to dpkg | inspect custom PATH/install |
| tooling | venv and pip modules available | install through apt |
| smoke test | stdlib and UTF-8 facts pass | diagnose package/locale |
| boundary | no global pip/system changes | plan virtual environment |
## Ubuntu Python Setup Step 1 completion gate
Step 1 is complete only when a normal Ubuntu user can authenticate with sudo; actual release and architecture are known; approved repositories refresh with valid signatures; routine upgrades are reviewed; dpkg reports no incomplete package state; `/usr/bin/python3` remains owned by Ubuntu; the selected APT development set supplies venv and pip tooling; standard-library/encoding checks pass; `~/projects` is user-owned; and no global pip, interpreter replacement, untrusted repository or release upgrade occurred.
Final evidence:
```bash
cat /etc/os-release
dpkg --print-architecture
python3 --version
python3 -c "import sys; print(sys.executable)"
dpkg -S "$(readlink -f "$(command -v python3)")"
python3 -m venv --help
sudo dpkg --audit
```
The next keyword should be **Ubuntu Python Setup Step 2**: create a user-owned project under `~/projects`, build `.venv` with `python3 -m venv`, activate it using `source .venv/bin/activate`, and prove prefix/pip isolation without sudo.
**Ubuntu Python Setup Step 1 succeeds when Ubuntu’s trusted package system owns a verified Python base that is healthy, supported and venv-ready—without letting project packages modify the operating system interpreter.**
**Ubuntu Python Setup Step 2 is to create a normal-user-owned Ubuntu project and a project-local `.venv`, then prove isolation through executable, prefix, pip, import-path, activation, deactivation, and clean-recreation evidence.** Ubuntu’s APT-managed `/usr/bin/python3` remains the base; the environment becomes the only place future project dependencies are installed.
The customer runs Ubuntu under WSL, so the lab stays in Ubuntu’s Linux filesystem. This article starts inside the Ubuntu shell and does not repeat Windows WSL registration or VS Code remote setup. To avoid overwriting the earlier WSL tutorial, it uses `~/projects/ubuntu-python-lab`.
| Layer | Owner | Required evidence |
|---|---|---|
| project directory | normal Ubuntu user | home path and `stat` |
| base interpreter | APT | `/usr/bin/python3`, matching prefixes |
| environment | this project | `.venv/bin/python` |
| activation | current shell | `VIRTUAL_ENV` and PATH |
| pip | environment interpreter | `.venv` location |
| source | project | standard-library probe |
| generated state | disposable | ignored `.venv/` |
| reproduction | commands/declarations | `.venv-check` proof |
## Verify the Ubuntu Step 1 base
Run inside Ubuntu as the normal user:
```bash
whoami
printf 'home=%s cwd=%s\n' "$HOME" "$PWD"
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.prefix); print(sys.base_prefix)"
python3 -m venv --help
sudo dpkg --audit
```
The user must not be root, the executable should be `/usr/bin/python3`, prefix/base-prefix should match before isolation, venv help must load, and the dpkg audit should be empty. Every `python3 -c` and `python -c` example is one physical command line.
If venv is unavailable, use Ubuntu’s package manager—not a pip bootstrap:
```bash
sudo apt update
sudo apt install python3-full python3-pip
```
Review the APT plan. On a deliberately minimal image, `python3 python3-venv python3-pip` is the bounded alternative. Do not use sudo pip or `--break-system-packages`.
## Select the Linux project location
Inspect the intended parent:
```bash
mkdir -p ~/projects
findmnt -T ~/projects
stat -c 'owner=%U group=%G mode=%A path=%n' ~/projects
```
The user should own it. Under WSL, the filesystem must be the Ubuntu/Linux filesystem, not `/mnt/c`. Linux tools operating on Linux files get native permissions, case behavior, symlinks, notifications, and better workload performance.
Do not store `.venv` in OneDrive, a Windows user directory, a mapped drive, or a shared folder. Do not reuse a Windows `.venv\Scripts` directory; it contains the wrong executables and platform artifacts.
## Create a new, non-overlapping project
Run without sudo:
```bash
mkdir ~/projects/ubuntu-python-lab
cd ~/projects/ubuntu-python-lab
pwd
ls -la
stat -c 'owner=%U mode=%A path=%n' .
```
If the directory already exists, stop and inspect it. Do not use `mkdir -p` to silently merge this setup with unknown source or environment state. Choose another reviewed name or follow the existing project documentation.
The expected path is `/home//projects/ubuntu-python-lab`, owned by the normal Ubuntu user.
## Capture base-interpreter facts
Before creating `.venv`:
```bash
command -v python3
readlink -f "$(command -v python3)"
python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python3 -c "import site; print(site.getsitepackages())"
```
These facts describe the Ubuntu base. Record its Python minor version because environments are tied to their creator. If the base is later materially upgraded, recreate environments instead of repairing symlinks.
## Create `.venv`
From the project root:
```bash
python3 -m venv .venv
```
The command should produce no error and needs no sudo. It creates a separate prefix, launchers under `.venv/bin`, activation scripts, site-packages, and `pyvenv.cfg`.
Inspect safely:
```bash
ls -la .venv
ls -la .venv/bin | sed -n '1,80p'
sed -n '1,80p' .venv/pyvenv.cfg
```
Do not edit generated paths, copy the directory elsewhere, or commit it. `pyvenv.cfg` and launchers can embed base/location assumptions; recreation is the portability mechanism.
## Prove the environment without activation
Direct invocation is the strongest first test:
```bash
.venv/bin/python --version
.venv/bin/python -c "import sys; print(sys.executable)"
.venv/bin/python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
.venv/bin/python -m pip --version
.venv/bin/python -m pip check
```
Expected:
- executable ends in `/ubuntu-python-lab/.venv/bin/python`;
- `sys.prefix` points into `.venv`;
- `sys.base_prefix` points to the Ubuntu base and differs from prefix;
- pip reports an installation under `.venv/lib/pythonX.Y/site-packages`;
- pip check reports no broken requirements.
Activation is not required in CI, services, scheduled commands, or scripts when this exact path is available.
## Activate in Bash
Run:
```bash
source .venv/bin/activate
```
`source` executes the activation script in the current Bash process. It prepends `.venv/bin` to PATH, sets `VIRTUAL_ENV`, and defines `deactivate`. Running the script in a child shell would not preserve those changes.
Prove activation:
```bash
printf 'VIRTUAL_ENV=%s\n' "$VIRTUAL_ENV"
command -v python
command -v python3
command -v pip
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
python -m pip --version
```
Every path must be inside this project `.venv`. The prompt’s `(.venv)` decoration is helpful but not proof. Shell themes can hide or imitate it; `sys.executable` is authoritative.
Do not add automatic project activation to `~/.bashrc`. It can leak one project’s environment into unrelated directories and automation.
## Inspect isolation
With `.venv` active:
```bash
python -c "import site; print(site.getsitepackages()); print(site.getusersitepackages())"
python -c "import sys; print('\n'.join(sys.path))"
python -m pip list
```
The environment begins with a small packaging-tool set. Exact versions vary with Ubuntu/Python and are not acceptance targets. User/system site directories may be reported as concepts, but project imports should resolve through the environment’s configured paths.
Avoid setting `PYTHONPATH` globally. It can defeat isolation by injecting unrelated source into every interpreter. Check unexplained customizations with `env | grep '^PYTHON'` and review before changing them.
## Create the first standard-library program
Create `system_probe.py` with a Linux-aware editor:
```python
from __future__ import annotations
import json
import platform
import sys
from pathlib import Path
def main() -> None:
evidence = {
"platform": platform.system(),
"python": sys.executable,
"prefix": sys.prefix,
"base_prefix": sys.base_prefix,
"cwd": str(Path.cwd()),
}
print(json.dumps(evidence, indent=2, sort_keys=True))
if __name__ == "__main__":
main()
```
Run both ways:
```bash
python system_probe.py
.venv/bin/python system_probe.py
```
Both must report Linux, the project `.venv` executable/prefix, Ubuntu base-prefix, and the project directory. The probe uses only the standard library and exposes no secrets/network traffic.
## Keep generated state out of source control
Create `.gitignore` containing:
```gitignore
.venv/
.venv-check/
__pycache__/
*.py[cod]
```
If Git is already initialized:
```bash
git check-ignore -v .venv/bin/python
git status --short
```
Do not initialize or connect a remote repository without deciding customer ownership. The ignore file remains useful preparation. Do not ignore all dotfiles, because project configuration often uses them.
## Deactivate and reactivate
Run:
```bash
deactivate
printf 'VIRTUAL_ENV=%s\n' "${VIRTUAL_ENV-}"
command -v python || true
command -v python3
python3 -c "import sys; print(sys.executable)"
```
The environment variable should be empty and `python3` should return to Ubuntu’s base. Bare `python` may no longer exist; that is normal.
Reactivate rather than recreating:
```bash
cd ~/projects/ubuntu-python-lab
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python system_probe.py
```
Closing a terminal also deactivates its shell state. Every new shell needs explicit activation or direct environment invocation.
## Prove clean creation separately
Create a disposable comparison environment without nesting activation:
```bash
deactivate
python3 -m venv .venv-check
.venv-check/bin/python -m pip check
.venv-check/bin/python system_probe.py
```
It must report a `.venv-check` prefix and the same Ubuntu base. This proves the project source does not rely on global/user packages.
When third-party dependencies arrive in Step 3, declarations must be installed into this clean environment before the probe/tests run.
## Understand recreation and deletion safety
Virtual environments are disposable, but deletion is still destructive. Before recreating, confirm:
```bash
pwd
realpath .venv
test -f .venv/pyvenv.cfg && echo 'venv target confirmed'
```
Deactivate and preserve source/dependency declarations. Never use an empty variable, glob, `$HOME`, `~`, `/`, or a broad recursive target. Never copy `.venv` as backup; back up source and declarations.
This tutorial does not delete either environment automatically. The customer can retain `.venv-check` until Step 3 or remove the exact reviewed target later.
## Ownership and permission checks
Run:
```bash
stat -c 'owner=%U group=%G mode=%A path=%n' . .venv .venv-check system_probe.py
umask
```
The normal Ubuntu user should own all project state. No step needs sudo. If root ownership appears, identify which prior command created it. Do not recursively `chmod 777`, chown all of `$HOME`, or run the editor as root.
## WSL-specific filesystem boundary
For this customer, confirm:
```bash
findmnt -T .
pwd
```
The project must remain under `/home`, not `/mnt/c`. Windows can inspect it via `\\wsl.localhost\\home\...`, but Windows tools should not manipulate environment binaries/symlinks. VS Code should later connect through WSL remote mode rather than opening the UNC folder as a normal Windows workspace.
Do not transfer `.venv` between native Ubuntu, WSL Ubuntu, containers, machines, users, paths, architectures, or Python minor versions. Recreate on each target.
## Troubleshooting
**`No module named venv` or ensurepip unavailable.** Install `python3-full` or the correct `python3-venv` package through APT. Do not download get-pip into system Python.
**Permission denied.** Check user, path, mount and owner. Do not retry with sudo.
**`.venv/bin/activate` missing but `.venv/Scripts` exists.** A Windows environment was created/copied. Preserve source, remove only the exact environment after review, and recreate with Ubuntu `python3`.
**Activation seems successful but Python is global.** Inspect `type -a python`, aliases/functions, PATH, `VIRTUAL_ENV`, and `sys.executable`. Trust executable evidence, not prompt text.
**pip points to `/usr` or `$HOME/.local`.** Reactivate or use `.venv/bin/python -m pip`. Never use user installs inside this project.
**Works only from one directory.** The source assumes cwd or environment was activated elsewhere. Use project-root paths and explicit re-entry.
**Cannot delete a file from Windows Explorer.** Close processes/handles and manage Linux project state from Ubuntu. Do not reset WSL or weaken permissions broadly.
**Environment broke after Ubuntu Python update.** Recreate it from source/declarations using the current supported base; do not repoint symlinks.
## What not to do in Ubuntu Step 2
- Do not create project state with sudo.
- Do not install project packages into system Python.
- Do not use `/mnt/c` as the default Linux project location.
- Do not copy or move `.venv` between OSes/paths/machines.
- Do not edit generated venv launchers or `pyvenv.cfg`.
- Do not auto-activate one project globally.
- Do not trust prompt text without executable/prefix proof.
- Do not commit `.venv`, `.venv-check`, or caches.
- Do not delete an existing directory until its exact contents/ownership are known.
| Ubuntu Step 2 gate | Pass condition | If it fails |
|---|---|---|
| baseline | APT Python/venv healthy | return to Step 1 |
| project | unique user-owned Linux directory | repair path/ownership |
| direct environment | `.venv/bin/python` runs | inspect venv creation |
| isolation | prefix differs from base-prefix | wrong interpreter |
| activation | commands resolve inside `.venv` | source current shell |
| first program | Linux/project facts correct | fix cwd/interpreter |
| source control | generated environments ignored | repair ignore rules |
| recreation | `.venv-check` independently passes | find hidden state |
## Ubuntu Python Setup Step 2 completion gate
Step 2 is complete only when `~/projects/ubuntu-python-lab` is a unique normal-user-owned Linux directory; Ubuntu’s APT Python creates `.venv` without sudo; direct and activated commands show the environment executable, distinct prefix and local pip; the standard-library probe reports Linux/project facts; deactivation restores the Ubuntu base; reactivation works in a new shell; `.venv` and `.venv-check` are ignored; and the second environment reproduces the probe without copied/global state.
Final evidence:
```bash
cd ~/projects/ubuntu-python-lab
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
python -m pip --version
python -m pip check
python system_probe.py
.venv-check/bin/python system_probe.py
```
The next keyword should be **Ubuntu Python Setup Step 3**: inspect pip trust/configuration inside `.venv`, install one justified dependency, prove metadata/import ownership, record direct versus transitive requirements, and reproduce the graph in `.venv-check`.
**Ubuntu Python Setup Step 2 succeeds when a user-owned project has a proven, ignored, disposable `.venv` whose executable, prefix and pip are isolated from Ubuntu’s protected system Python and reproducible without sudo.**
**Ubuntu Python Setup Step 3 is to add one third-party dependency to `~/projects/ubuntu-python-lab` through the project `.venv`, prove where it came from and where it imports from, record the resolved graph, and reproduce it in `.venv-check`.** Ubuntu APT continues to own `/usr/bin/python3`; project pip never receives sudo or permission to break the system environment.
This tutorial uses the `httpx` distribution, which differs from the WSL-series dependency example. Its verification creates a request object but sends nothing, so setup does not depend on the internet after installation or expose customer data to a remote endpoint.
| Dependency surface | Required evidence | Failure boundary |
|---|---|---|
| interpreter | project `.venv/bin/python` | system/global Python |
| pip trust | known config/index/TLS/proxy | hidden or insecure source |
| distribution | canonical name/version/location | typo or wrong environment |
| import | module file under `.venv` | shadow/global leakage |
| graph | direct and transitive roles | undeclared packages |
| consistency | `pip check` succeeds | conflicting requirements |
| record | intent plus tested snapshot | machine-only state |
| reproduction | `.venv-check` passes probe | copied/cache dependency |
## Re-enter and prove Step 2
Inside Ubuntu:
```bash
cd ~/projects/ubuntu-python-lab
source .venv/bin/activate
pwd
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
python -m pip --version
python -m pip check
python system_probe.py
```
Executable, prefix and pip must be under `/home//projects/ubuntu-python-lab/.venv`; base-prefix should identify the Ubuntu base. Every `python -c` command is one physical line. Stop if the environment is global, root-owned, under `/mnt/c`, or inconsistent.
Confirm ownership and generated-state exclusions:
```bash
stat -c 'owner=%U mode=%A path=%n' . .venv
git check-ignore -v .venv/bin/python 2>/dev/null || true
```
Installing inside a user-owned venv does not require sudo. Permission errors must be diagnosed, not escalated.
## Inspect pip configuration before installation
Pip combines global, user, site/venv configuration, environment variables, and command options. Reveal effective sources:
```bash
python -m pip config debug
python -m pip config list -v
env | grep '^PIP_' || true
```
Review index URLs, proxy, certificate bundle, timeouts, `trusted-host`, `PIP_CONFIG_FILE`, and file origins. Redact credentials/internal hosts before sharing. Environment variables can override configuration files, so a clean-looking file is not full evidence.
The approved package source should use authenticated HTTPS as required by the organization. Never bypass certificate validation, use HTTP, add broad trusted hosts, or put proxy/index passwords on command lines. Mixing a private and public index can create dependency-confusion risk; follow one reviewed source policy.
Inspect pip ownership and Linux artifact compatibility:
```bash
python -m pip --version
python -m pip debug --verbose
uname -m
```
Ubuntu needs a compatible Linux wheel or an intentionally supported source build. Windows `.whl` files and Windows virtual environments are not compatible.
## Verify the intended package name
Search index metadata without installing:
```bash
python -m pip index versions httpx
```
Confirm spelling, official project identity, license, supported Python versions, release notes and maintenance. Popular-name imitation and typo-squatting are real supply-chain risks. Do not infer trust from download count alone.
This fresh tutorial accepts the currently resolved compatible release. Existing projects should follow their lock/constraint policy rather than silently upgrading.
## Install through the environment interpreter
Run:
```bash
python -m pip install httpx
```
Read the plan: index host, selected version, artifacts, cache use, build isolation and transitive dependencies. A successful final line is not enough if the source or package name is wrong.
Immediately check consistency:
```bash
python -m pip check
```
Do not use bare system pip, `/usr/bin/python3 -m pip`, sudo, `--user`, or `--break-system-packages`.
## Prove installed distribution metadata
Run:
```bash
python -m pip show httpx
python -c "from importlib.metadata import metadata, version; print(metadata('httpx')['Name']); print(version('httpx'))"
```
`pip show` location must be under `.venv`. `importlib.metadata` reports distribution metadata independently of module-defined version attributes.
Inspect its declared requirements and current graph:
```bash
python -m pip show httpx | sed -n '/^Requires:/p'
python -m pip list
python -m pip inspect > /tmp/ubuntu-step3-inspect.json
```
`httpx` is direct intent; packages it requires are transitive implementation of the resolved graph. Do not list every transitive package as an application decision. The inspect report can contain environment paths/metadata; keep it local unless reviewed/redacted.
## Prove import ownership
Run:
```bash
python -c "import httpx; print(httpx.__file__)"
python -c "import httpx; print(httpx.__version__)"
```
The module file must be under `.venv`, not the project root, `/usr`, `$HOME/.local`, `/mnt/c`, or Windows. Search for shadows:
```bash
find . -maxdepth 2 \( -name 'httpx.py' -o -name 'httpx' \) -print
```
If a local file shadows the distribution, inspect/source-control-review before renaming. Never delete customer source reactively.
## Create an offline-safe dependency probe
Create `http_probe.py`:
```python
from __future__ import annotations
import sys
import httpx
def main() -> None:
request = httpx.Request(
"GET",
"https://example.invalid/health",
params={"source": "ubuntu-step3"},
)
print(f"method={request.method}")
print(f"host={request.url.host}")
print(f"python={sys.executable}")
print(f"httpx={httpx.__file__}")
if __name__ == "__main__":
main()
```
Run:
```bash
python http_probe.py
```
It must show GET, `example.invalid`, and project `.venv` paths. Constructing a request exercises package behavior without DNS/network transmission. Do not use a production/customer URL for an installation probe.
## Record direct intent
Create `requirements.in` containing:
```text
httpx
```
This human-readable tutorial file expresses the direct dependency. Plain pip does not give `.in` special semantics. If a real project already uses `pyproject.toml`, dependency groups, constraints, pip-tools, uv, Poetry or another lock manager, use that one authority instead of creating parallel files.
Version bounds need compatibility reasoning. Do not paste old versions from tutorials or pin “latest” without testing/updating policy.
## Capture a tested snapshot
Run:
```bash
python -m pip freeze > requirements.txt
sed -n '1,120p' requirements.txt
python -m pip check
```
The snapshot includes direct and transitive packages installed in this environment. Review for editable installs, local paths, direct URLs, private hosts and credentials. A freeze reproduces current state—including contamination—so it is not automatically a good lock.
Keep intent and snapshot conceptually separate: humans review why `httpx` exists; recreation consumes the tested graph for this bounded tutorial.
## Recreate in `.venv-check`
Step 2 created `.venv-check`. Recreate it only after confirming it is the disposable project check environment and contains no needed state. For a non-destructive first attempt, if it is still clean, install directly:
```bash
.venv-check/bin/python -m pip install -r requirements.txt
.venv-check/bin/python -m pip check
.venv-check/bin/python http_probe.py
```
The probe must show `.venv-check` paths. This proves the dependency comes from declarations rather than `.venv`, user site or system Python.
Compare resolved snapshots:
```bash
.venv/bin/python -m pip freeze > /tmp/ubuntu-step3-working.txt
.venv-check/bin/python -m pip freeze > /tmp/ubuntu-step3-check.txt
diff -u /tmp/ubuntu-step3-working.txt /tmp/ubuntu-step3-check.txt
```
No difference is expected. If `.venv-check` already contained packages, that is not clean evidence; rebuild its exact verified target later with safe deletion or create a newly named disposable environment.
## Ignore derived state
Ensure `.gitignore` includes:
```gitignore
.venv/
.venv-check/
__pycache__/
*.py[cod]
```
Source and reviewed declarations belong in version control. Virtual environments, pip caches, temporary inspect reports, credentials and user config do not.
Inspect:
```bash
git status --short 2>/dev/null || true
python -m pip cache dir
python -m pip cache info
```
The cache accelerates downloads; it is not an environment, declaration or provenance guarantee. Cache misses are normal. Do not commit/copy it as recovery.
## Updates and rollback policy
Do not run blanket upgrades casually. A dependency update is a source/declaration change that needs release-note review, full tests, graph comparison and clean reproduction.
For this disposable lab, rollback means restore the prior reviewed requirements file and recreate the environment. Uninstalling the direct package does not necessarily remove all orphaned transitive packages. Recreation gives a clearer known state.
Never uninstall Ubuntu’s apt packages to manipulate project pip state. APT owns system Python; venv pip owns project distributions.
## Security boundaries
Package installation executes/builds third-party code and can access the user’s files/network. Verify names/sources and prefer reviewed artifacts/locks. Avoid installing untrusted projects just to test pip.
Do not expose private index tokens, `.netrc`, proxy credentials, CA material or full configuration output. Do not disable TLS. Do not mix public/private indexes without dependency-confusion controls. Do not run package build hooks as root.
Native packages may require compilers/headers. Add APT build dependencies only from trusted repositories with a documented need, and remove/retain according to policy—not random error-message copying.
## Troubleshooting
**Externally managed environment.** Wrong interpreter. Activate `.venv` or use `.venv/bin/python -m pip`; never bypass the protection.
**Permission denied.** Check normal user, project location and ownership. Do not add sudo.
**TLS/proxy/certificate failure.** Check clock, DNS, approved proxy/CA and index URL. Preserve/redact the exact error; do not trust-host it away.
**No matching distribution.** Check Python version, architecture, compatible tags, platform wheels and official release support. Do not use Windows wheels.
**Source build fails.** Inspect official build requirements and build-isolation logs. Do not globally install arbitrary toolchains.
**Import path is wrong.** Check activation, `sys.executable`, local shadowing, `PYTHONPATH` and user-site leakage.
**`pip check` fails.** Read conflicting distributions/specifiers and repair declarations/resolution; do not ignore or use `--no-deps`.
**Clean recreation differs.** Compare config/index, Python version, requirements, markers and existing check-environment state.
**Requirements leak a URL/token.** Do not commit. Recreate from approved sources, regenerate and review.
## What not to do in Ubuntu Step 3
- Do not use system pip, sudo pip, user installs or break-system-packages.
- Do not disable TLS or add untrusted package sources.
- Do not install Windows artifacts in Ubuntu.
- Do not trust import success without checking its file.
- Do not confuse direct intent with transitive packages.
- Do not send a live request as installation proof.
- Do not copy `.venv`; reproduce from declarations.
- Do not commit environments, caches or credentials.
| Ubuntu Step 3 gate | Pass condition | If it fails |
|---|---|---|
| interpreter/pip | both under project `.venv` | return to Step 2 |
| source trust | approved HTTPS config | repair index/proxy/CA |
| install | compatible httpx graph | inspect resolver/build |
| metadata/import | both located in `.venv` | fix shadow/leak |
| consistency | `pip check` passes | repair graph |
| declaration | intent and snapshot reviewed | remove unsafe origins |
| reproduction | `.venv-check` probe passes | find hidden state |
| security | no sudo/TLS bypass/secrets | stop and remediate |
## Ubuntu Python Setup Step 3 completion gate
Step 3 is complete only when the project `.venv` owns Python/pip; effective pip configuration shows approved sources; httpx installs without system-Python modification; metadata, import path and graph are reviewed; the local-only probe passes; pip reports consistency; direct intent and tested snapshot contain no unsafe origins; `.venv-check` independently installs and runs the same probe; and environments/caches/credentials remain uncommitted.
Final evidence:
```bash
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python -m pip config debug
python -m pip show httpx
python -c "import httpx; print(httpx.__file__)"
python -m pip check
python http_probe.py
.venv-check/bin/python http_probe.py
```
The next keyword should be **Ubuntu Python Setup Step 4**: configure an Ubuntu-native or WSL-remote editor to use `.venv/bin/python`, then prove terminal, Run, Debug, language analysis and tests share the same Linux environment.
**Ubuntu Python Setup Step 3 succeeds when a trusted third-party dependency belongs only to the project venv, its identity/graph/import are proven, and reviewed declarations reproduce it in a second clean Ubuntu environment.**
**UCIe (Universal Chiplet Interconnect Express)** is an open industry standard for connecting chiplets — separate silicon dies — together inside a single package. As monolithic chips hit the limits of what one die can economically contain, designers increasingly build a product from several smaller dies (a CPU die, an accelerator die, an I/O die, memory) placed side by side and wired together. UCIe standardizes that die-to-die link the way PCIe standardized board-level I/O, so that dies from different vendors and different process nodes can be mixed and matched in one package. It is the interconnect meant to turn chiplets from a proprietary, one-vendor trick into an open ecosystem.\n\n```svg\n\n```\n\n**The problem it solves is that die-to-die links were all proprietary.** AMD's Infinity Fabric, Intel's AIB/EMIB links, and NVIDIA's NVLink-C2C each let a company stitch its own dies together, but a chiplet built for one could not plug into another. UCIe defines a common physical interface, protocol, and software model so a die that speaks UCIe can interoperate with any other UCIe die, enabling a marketplace where you buy a best-in-class I/O chiplet from one vendor and pair it with a compute chiplet from another.\n\n**It is layered like PCIe, and deliberately reuses PCIe/CXL on top.** The physical layer defines the bumps, lanes, clocking, and a sideband channel. The die-to-die adapter handles link state management, CRC, retries, and arbitration for reliability. The protocol layer maps established protocols — PCIe and CXL — over the link, plus a raw "streaming" mode for anything else. Because the upper layers are just PCIe and CXL, existing software and IP work across a chiplet boundary with little change.\n\n**Two package classes trade reach against density.** A standard package routes UCIe over an ordinary organic substrate: cheaper, longer reach (roughly 10–25 mm), but wider bump pitch and lower bandwidth density. An advanced package uses a silicon interposer or bridge (2.5D integration like CoWoS or EMIB) with very fine bump pitch: short reach (a couple of millimeters) but enormous bandwidth density and better energy per bit. The same UCIe stack runs on both; you pick the package for your cost and bandwidth targets.\n\n**The figures of merit are bandwidth density and energy per bit, not just raw speed.** Because a die has only so much edge and area to place bumps, what matters is how much bandwidth you get per millimeter of die edge (or per mm²) and how few picojoules each bit costs. Advanced-package UCIe targets sub-0.5 pJ/bit and very high bandwidth per millimeter, with die-to-die latency under a couple of nanoseconds — numbers that make crossing a chiplet boundary feel almost like staying on-die.\n\n**It is foundational to modern AI silicon.** Large accelerators are already multi-die, and the economics of splitting a big design into yield-friendly chiplets — mixing process nodes, reusing I/O dies, scaling compute independently — only work if the interconnect between dies is fast, cheap, and standard. UCIe is the open bet on that future: it lets the industry build ever-larger "virtual" chips out of composable dies without every vendor reinventing the link.\n\n| Layer | Job |\n|---|---|\n| Protocol layer | map PCIe / CXL / raw streaming across the link |\n| Die-to-die adapter | link state, CRC, retry, arbitration |\n| Physical layer | bumps, lanes, clocking, sideband channel |\n| Standard package | organic substrate, long reach, lower density |\n| Advanced package | interposer/bridge, short reach, high density |\n\nRead UCIe through a *composable-die-ecosystem* lens rather than a *just-another-bus* lens: the point is not a single fast wire but a standard that lets dies from different vendors and process nodes snap together inside one package. Once the die-to-die link is open and cheap enough that crossing it costs almost nothing, a "chip" becomes a configuration of chiplets you assemble — and that is exactly how the largest AI processors are now being built.\n
**UCIe (Universal Chiplet Interconnect Express)** is an open industry standard for connecting chiplets — separate silicon dies — together inside a single package. As monolithic chips hit the limits of what one die can economically contain, designers increasingly build a product from several smaller dies (a CPU die, an accelerator die, an I/O die, memory) placed side by side and wired together. UCIe standardizes that die-to-die link the way PCIe standardized board-level I/O, so that dies from different vendors and different process nodes can be mixed and matched in one package. It is the interconnect meant to turn chiplets from a proprietary, one-vendor trick into an open ecosystem.\n\n```svg\n\n```\n\n**The problem it solves is that die-to-die links were all proprietary.** AMD's Infinity Fabric, Intel's AIB/EMIB links, and NVIDIA's NVLink-C2C each let a company stitch its own dies together, but a chiplet built for one could not plug into another. UCIe defines a common physical interface, protocol, and software model so a die that speaks UCIe can interoperate with any other UCIe die, enabling a marketplace where you buy a best-in-class I/O chiplet from one vendor and pair it with a compute chiplet from another.\n\n**It is layered like PCIe, and deliberately reuses PCIe/CXL on top.** The physical layer defines the bumps, lanes, clocking, and a sideband channel. The die-to-die adapter handles link state management, CRC, retries, and arbitration for reliability. The protocol layer maps established protocols — PCIe and CXL — over the link, plus a raw "streaming" mode for anything else. Because the upper layers are just PCIe and CXL, existing software and IP work across a chiplet boundary with little change.\n\n**Two package classes trade reach against density.** A standard package routes UCIe over an ordinary organic substrate: cheaper, longer reach (roughly 10–25 mm), but wider bump pitch and lower bandwidth density. An advanced package uses a silicon interposer or bridge (2.5D integration like CoWoS or EMIB) with very fine bump pitch: short reach (a couple of millimeters) but enormous bandwidth density and better energy per bit. The same UCIe stack runs on both; you pick the package for your cost and bandwidth targets.\n\n**The figures of merit are bandwidth density and energy per bit, not just raw speed.** Because a die has only so much edge and area to place bumps, what matters is how much bandwidth you get per millimeter of die edge (or per mm²) and how few picojoules each bit costs. Advanced-package UCIe targets sub-0.5 pJ/bit and very high bandwidth per millimeter, with die-to-die latency under a couple of nanoseconds — numbers that make crossing a chiplet boundary feel almost like staying on-die.\n\n**It is foundational to modern AI silicon.** Large accelerators are already multi-die, and the economics of splitting a big design into yield-friendly chiplets — mixing process nodes, reusing I/O dies, scaling compute independently — only work if the interconnect between dies is fast, cheap, and standard. UCIe is the open bet on that future: it lets the industry build ever-larger "virtual" chips out of composable dies without every vendor reinventing the link.\n\n| Layer | Job |\n|---|---|\n| Protocol layer | map PCIe / CXL / raw streaming across the link |\n| Die-to-die adapter | link state, CRC, retry, arbitration |\n| Physical layer | bumps, lanes, clocking, sideband channel |\n| Standard package | organic substrate, long reach, lower density |\n| Advanced package | interposer/bridge, short reach, high density |\n\nRead UCIe through a *composable-die-ecosystem* lens rather than a *just-another-bus* lens: the point is not a single fast wire but a standard that lets dies from different vendors and process nodes snap together inside one package. Once the die-to-die link is open and cheap enough that crossing it costs almost nothing, a "chip" becomes a configuration of chiplets you assemble — and that is exactly how the largest AI processors are now being built.\n
ucie link layer, die to die interface protocol, chiplet interconnect standard, ucie transport
**UCIe Protocol Design** is the **implementation strategy for standardized die to die communication across chiplets**.
**What It Covers**
- **Core concept**: defines reliable transfer, flow control, and link training behavior.
- **Engineering focus**: supports package level interoperability between heterogeneous dies.
- **Operational impact**: enables modular product design across process nodes.
- **Primary risk**: protocol corner cases can impact bring up and compatibility.
**Implementation Checklist**
- Define measurable targets for performance, yield, reliability, and cost before integration.
- Instrument the flow with inline metrology or runtime telemetry so drift is detected early.
- Use split lots or controlled experiments to validate process windows before volume deployment.
- Feed learning back into design rules, runbooks, and qualification criteria.
**Common Tradeoffs**
| Priority | Upside | Cost |
|--------|--------|------|
| Performance | Higher throughput or lower latency | More integration complexity |
| Yield | Better defect tolerance and stability | Extra margin or additional cycle time |
| Cost | Lower total ownership cost at scale | Slower peak optimization in early phases |
UCIe Protocol Design is **a practical lever for predictable scaling** because teams can convert this topic into clear controls, signoff gates, and production KPIs.
universal chiplet interconnect express, ucie, open die to die protocol
**UCIe standard definition and engineering boundary.** is the Universal Chiplet Interconnect Express specification for interoperable die-to-die links within a package. It defines a layered stack spanning physical lanes, a die-to-die adapter, management and protocol mappings so chiplets can carry PCIe, CXL, or raw streaming traffic over standard or advanced packages. Consortium support across IP, chip, foundry, packaging, cloud, and system companies is intended to create a broader ecosystem. Specifications must be versioned. UCIe 1.x established the core link and package classes; UCIe 2.0 added manageability, test, and 3D packaging support; the consortium’s UCIe 3.0 page documents 48 and 64 GT/s modes, extended sideband reach, streaming mappings, early firmware download, priority events, fast throttle and emergency shutdown, and backward compatibility. Earlier fixed numbers should not be presented as the whole current standard. Actual bandwidth and latency depend on lane count, package, negotiated rate, protocol overhead, implementation, and error handling. A useful specification begins with workloads and service objectives rather than peak arithmetic. It records tensor shapes, sparsity, precision and accumulator behavior; model size and reuse; batch and sequence distributions; latency percentiles; required throughput; memory capacity and bandwidth; host traffic; collective communication; power, thermal and area limits; availability; security; software versions; and cost. Every published number needs its operating point, data type, workload, compiler, clock, utilization method, and whether it is measured or theoretical. Without that context, TOPS, FLOPS, bandwidth, and energy figures are not comparable.
**Architecture, execution, and data movement.** Sideband and management coordinate discovery and initialization, PHYs train lanes and repair defects, adapters frame and protect traffic, protocols exchange flits or streams, CRC/retry handles eligible errors, and power management moves the link through supported states. Modern acceleration is a hierarchy: host processors orchestrate work, a runtime and compiler lower graphs into kernels, DMA engines move tensors, local SRAM captures reuse, arithmetic arrays execute dense or sparse operations, vector and scalar units handle nonlinear and control work, and external memory holds parameters and activations that do not fit on chip. Networks, package links, and coherency connect devices. The design is balanced only when compute, storage, movement, synchronization, and software can sustain one another under the target workload. Compilation is part of the architecture. Graph capture, operator legalization, fusion, layout selection, tiling, partitioning, scheduling, precision conversion, buffer allocation, collective insertion, code generation, and runtime dispatch determine whether the hardware is occupied. Dynamic shapes, small batches, irregular sparsity, unsupported operators, and host-device boundaries create bubbles or fallback. A healthy platform exposes counters and deterministic intermediate representations so teams can explain a result instead of tuning an opaque benchmark.
**Implementation and physical realization.** Select standard or advanced package profile, lane and module width, reach, bump pitch, clocks, protocol mapping, FDI/RDI boundaries, management, test, debug, security, power and thermal policy. Interoperability requires precise compliance rather than a UCIe-like electrical link. Implementation proceeds from trace-driven models and roofline analysis through microarchitecture, RTL, verification, physical design, packaging, firmware, compiler, runtime, framework integration, and fleet qualification. Designers budget cycles and bytes for every stage, size queues against burstiness, partition clock and voltage domains, place memories close to consumers, pipeline long wires, protect CDC and reset crossings, add DFT and telemetry, and reserve margin for process, voltage, temperature, aging, and workload drift. Power intent, thermal maps, package escape, signal integrity, and memory availability are architectural inputs, not late signoff details. Specialization removes instruction overhead and unnecessary data motion, but it narrows the efficient workload envelope. Larger arrays raise peak throughput yet waste lanes on unfavorable dimensions. More SRAM improves reuse but consumes die area and leakage. Narrow precision saves bandwidth and energy but demands calibration and numerically sound accumulation. Sparse execution helps only when metadata, load balance, and software preserve useful sparsity. Chiplets improve yield and reuse while adding link energy, latency, test, thermal, and package dependencies. The correct design optimizes delivered application value rather than one isolated component.
**Verification, security, and production operation.** Use specification compliance, protocol assertions, lane training and repair, BER, jitter and margin, package SI/PI, reset and power states, CRC/retry, management, debug, interoperability across vendors, thermal/mechanical stress, and production test. Verification combines reference-model comparison, arithmetic corner cases, protocol assertions, formal checks, constrained-random traffic, coherency and memory-order tests, CDC/RDC, power-state verification, emulation, compiler differential testing, operator and model suites, fault injection, post-layout timing and power analysis, silicon characterization, and long-running system stress. Accuracy is checked end to end after quantization and graph transformations. Performance testing reports warmup, steady state, percentiles, utilization, throttling, error bars, and reproducible software. Recovery tests cover malformed commands, link errors, memory faults, reset during work, and partial device failure. The trust boundary includes boot ROM, fuses, device firmware, management controllers, debug, DMA, shared memory, package links, compiler artifacts, model weights, and telemetry. Secure and measured boot, authenticated firmware, anti-rollback, IOMMU isolation, memory protection, zeroization, debug authorization, side-channel review, supply-chain provenance, and incident response are designed together. Multi-tenant accelerators also require scheduling and state-clearing rules that prevent one workload from observing another. Production operation needs admission control, isolation, scheduling, observability, firmware and compiler compatibility, signed updates, rollback, health checks, thermal and power management, error containment, and capacity models. Counters should attribute stalls to compute, memory, fabric, synchronization, compilation, or host overhead. Fleet telemetry closes the loop with architecture and software teams, but collection must respect tenant boundaries and data governance. Service owners define degraded modes and replacement policy before hardware faults appear.
| Interface family | Openness | Protocol scope | Packaging scope | Primary tradeoff |
|---|---|---|---|---|
| UCIe | Consortium standard | PCIe, CXL, Raw mappings | Standard, advanced, and newer 3D support | Interoperability versus implementation tuning |
| AMD Infinity Fabric-class | Vendor fabric | Vendor coherent/data fabric | Product-specific | Tight product optimization |
| Intel package fabrics/EMIB links | Vendor implementation | Product-specific fabrics | Bridge and advanced package | Platform integration |
| NVLink-C2C-class | Vendor coherent link | CPU/GPU coherent use | Advanced package | High optimization, closed ecosystem |
| Custom streaming D2D | Bilateral or proprietary | Application stream | Any co-designed package | Minimal overhead, low portability |
```svg
```
**Selection, applications, and lifecycle ownership.** Choose UCIe when ecosystem interoperability and standard protocol mappings outweigh proprietary optimization. Proprietary fabric can optimize a closed product but increases reuse and partner friction. Compute chiplets, I/O dies, memory and cache dies, accelerators, coherent package systems, and modular SiPs use UCIe. Requirements, workloads, datasets, model and compiler versions, architecture models, RTL, IP, timing and power constraints, package and board revisions, firmware, runtime, validation evidence, calibration, test limits, errata, field telemetry, and release approvals remain linked. A hardware generation cannot be patched like an application, so interface compatibility, diagnostic reach, spare capacity, and support lifetime matter. Cross-functional ownership prevents a local optimization from moving cost or risk into memory, packaging, cooling, software, manufacturing, or customer operations. A useful specification begins with workloads and service objectives rather than peak arithmetic. It records tensor shapes, sparsity, precision and accumulator behavior; model size and reuse; batch and sequence distributions; latency percentiles; required throughput; memory capacity and bandwidth; host traffic; collective communication; power, thermal and area limits; availability; security; software versions; and cost. Every published number needs its operating point, data type, workload, compiler, clock, utilization method, and whether it is measured or theoretical. Without that context, TOPS, FLOPS, bandwidth, and energy figures are not comparable. CFS connects this topic to semiconductor architecture, implementation, verification, manufacturing, packaging, test, and deployed AI-system tradeoffs across the platform.
**UDA** (Unsupervised Data Augmentation) is a **semi-supervised learning framework that applies advanced data augmentation (such as back-translation for text and RandAugment for images) to unlabeled data** — enforcing consistency between the original and augmented versions.
**How Does UDA Work?**
- **Strong Augmentation**: Apply task-specific strong augmentation to unlabeled data (back-translation, RandAugment, TF-IDF word replacement).
- **Consistency**: $mathcal{L}_{UDA} = ext{KL}(p(y|x) || p(y| ext{Aug}(x)))$ — predictions should be consistent under augmentation.
- **Confidence Masking**: Only compute the consistency loss when the model is confident about $p(y|x)$.
- **Paper**: Xie et al. (2020, Google Brain).
**Why It Matters**
- **Text + Vision**: One of the first methods to show strong semi-supervised results on both text (IMDb, BERT) and vision (CIFAR, ImageNet).
- **Augmentation Is Key**: The quality of the augmentation strategy is the primary driver of performance.
- **Low-Label**: 20 labels on IMDb → competitive with fully supervised BERT using 25K labels.
**UDA** is **augmentation-powered semi-supervised learning** — leveraging the best task-specific augmentations to extract maximum value from unlabeled data.
**ULMFiT** (Universal Language Model Fine-Tuning) is a **pioneering transfer learning method for NLP** — demonstrating that pre-trained language models can be effectively fine-tuned for text classification with very few labeled examples, using techniques like discriminative fine-tuning, progressive unfreezing, and slanted triangular learning rates.
**What Is ULMFiT?**
- **Three Stages**:
1. **LM Pre-Training**: Pre-train an AWD-LSTM language model on a large corpus (Wikitext-103).
2. **LM Fine-Tuning**: Fine-tune the LM on the target domain text (unsupervised).
3. **Classifier Fine-Tuning**: Add a classifier head and fine-tune using labeled data with progressive unfreezing + discriminative LR.
- **Paper**: Howard & Ruder (2018).
**Why It Matters**
- **NLP Transfer Pioneer**: Demonstrated that ImageNet-style transfer learning works for NLP — before BERT and GPT.
- **Key Techniques**: Introduced discriminative fine-tuning, progressive unfreezing, and STLR — now widely adopted.
- **Impact**: Directly inspired the pre-train/fine-tune paradigm that dominates modern NLP (BERT, GPT, T5).
**ULMFiT** is **the grandfather of modern NLP transfer learning** — the paper that proved pre-trained language models could be fine-tuned for any text task with minimal data.
Semiconductor cleanroom engineering, ultra-pure water synthesis, and advanced facility distribution networks constitute the critical physical infrastructure required to sustain nanoscale wafer fabrication. In modern semiconductor fabs manufacturing sub-2nm gate-all-around nanosheet transistors and multi-hundred-layer 3D memory architectures, ambient airborne particulates, chemical vapor impurities, trace ionic contamination, and floor vibrations represent lethal yield-killing hazards. A single twenty-nanometer airborne particle or airborne molecular ammonia concentration exceeding a fraction of a part per billion can ruin photolithographic exposure patterns, cause catastrophic dielectric breakdown, or induce complete wafer lot scrap. To guarantee defect-free manufacturing environments, semiconductor facilities deploy multi-level cleanroom architectures featuring automated laminar recirculation air loops, ultra-low particulate air (ULPA) filtration ceilings, vibration-isolated sub-fab utility matrices, continuous $18.2\text{ M}\Omega\cdot\text{cm}$ ultra-pure water (UPW) loops, and automated material handling systems (AMHS) transporting sealed front-opening unified pods (FOUPs) purged with ultra-pure nitrogen.
**Cleanroom classifications establish mathematical limits on maximum allowable airborne particle concentrations per cubic meter.** Standardized under ISO 14644-1 (superseding historical US Federal Standard 209E), the maximum permitted concentration of airborne particles ($C_n$, in particles per cubic meter) for a given particle diameter ($D$, in micrometers) is governed by the class index ($N$):
$$
C_n = 10^N \times \left( \frac{0.1}{D} \right)^{2.08}.
$$
Under this standard, an ISO Class 1 cleanroom environment permits no more than $10\text{ particles/m}^3$ of diameter $\ge 0.1\ \mu\text{m}$ and zero particles $\ge 0.5\ \mu\text{m}$, representing the pristine level maintained inside front-opening unified pods (FOUPs) and advanced lithography scanner minienvironments. In wafer fab main processing bays (the ballroom or chase areas), cleanliness is maintained at ISO Class 2 to ISO Class 4 (equivalent to Fed Std 209E Class 1 to Class 10), while wafer transport corridors and chase utility areas operate at ISO Class 5 to ISO Class 6 (Class 100 to Class 1000).
**Vertical unidirectional laminar airflow suppresses turbulent eddies to sweep particles continuously out of the active bay.** To prevent human personnel, automated robotic arms, and process tool wafer transfer mechanisms from contaminating exposed wafer surfaces, semiconductor cleanrooms utilize vertical downward laminar airflow (unidirectional displacement flow). Air is forced downward from a contiguous ceiling of Fan Filter Units (FFUs) fitted with Ultra-Low Particulate Air (ULPA) filters capable of removing $\ge 99.9995\%$ of all particles at the most penetrating particle size ($0.12\ \mu\text{m}$). The airflow descends at a calibrated velocity of $v_{\text{air}} = 0.45\text{ m/s} \pm 20\%$ ($90\text{ feet/minute}$), establishing a stable piston-like displacement field with an Air Change Rate ($\text{ACR}$) of $300\text{ to }600\text{ air changes per hour}$. The air passes smoothly through perforated raised aluminum floor tiles ($30\%\text{--}40\%$ open perforation ratio) into the sub-fab return air plenum, preventing lateral cross-contamination and eliminating stagnant recirculating air vortices.
| Cleanroom ISO Class | Fed Std 209E Equivalent | Max Particles $\ge 0.1\ \mu\text{m/m}^3$ | Max Particles $\ge 0.5\ \mu\text{m/m}^3$ | Airflow Regime & Velocity | Primary Fab Application Module |
|---|---|---|---|---|---|
| ISO Class 1 | Class 0.1 | $10$ | $0$ | Vertical Unidirectional ($0.45\text{ m/s}$) | Inside FOUP, EUV scanner minienvironment, track coat |
| ISO Class 2 | Class 1 | $100$ | $4$ | Vertical Unidirectional ($0.45\text{ m/s}$) | Leading-edge photolithography, wet bench loadports |
| ISO Class 3 | Class 10 | $1,000$ | $35$ | Vertical Unidirectional ($0.40\text{ m/s}$) | Dry plasma etch, ALD/CVD deposition, ion implant |
| ISO Class 4 | Class 100 | $10,000$ | $352$ | Mixed / Unidirectional ($0.35\text{ m/s}$) | CMP polish modules, metrology inspection bays |
| ISO Class 5 | Class 1,000 | $100,000$ | $3,520$ | Non-Unidirectional / Turbulent | Fab service chase, chemical distribution sub-fab |
| ISO Class 6 | Class 10,000 | $1,000,000$ | $35,200$ | Turbulent Recirculation | Gowning airlock, wafer shipping packaging, probe test |
**Ultra-pure water synthesis achieves theoretical thermodynamic resistivity limits for chemical surface cleaning.** Semiconductor wafer wet cleaning, chemical mechanical planarization (CMP), and post-etch rinsing consume millions of liters of water daily, all of which must achieve near-complete chemical and ionic purity. The theoretical maximum resistivity of pure water ($\rho_{\text{UPW}}$) at $25^\circ\text{C}$ is determined solely by the self-ionization of water ($2\text{H}_2\text{O} \rightleftharpoons \text{H}_3\text{O}^+ + \text{OH}^-$), where the ionic product is $K_w = 1.0 \times 10^{-14}\text{ mol}^2/\text{L}^2$:
$$
\rho_{\text{UPW}} = \frac{1}{F \left( \mu_{\text{H}^+} c_{\text{H}^+} + \mu_{\text{OH}^-} c_{\text{OH}^-} \right)} \approx 18.18\text{ M}\Omega\cdot\text{cm}\ (18.2\text{ M}\Omega\cdot\text{cm}).
$$
Modern UPW treatment plants deploy multi-stage purification trains comprising reverse osmosis (RO), electro-deionization (EDI), vacuum membrane degassing (dissolved oxygen $\text{DO} < 1\text{ ppb}$), 185nm DUV photo-oxidation (suppressing Total Organic Carbon $\text{TOC} < 0.5\text{ ppb}$), continuous catalytic resin polisher beds, and $0.02\ \mu\text{m}$ point-of-use (POU) ultrafiltration, ensuring that water delivered to wet benches contains fewer than one particle per milliliter.
**Airborne molecular contamination and environmental stability dictate lithographic yield predictability.** Beyond solid particulates, gaseous Airborne Molecular Contamination (AMC) poses severe chemical risks. Volatile base amines, specifically airborne ammonia ($\text{NH}_3$), neutralize the photogenerated photoacid catalyst in chemically amplified DUV and EUV photoresists, producing insoluble crusts known as resist T-topping defects; consequently, fab HVAC systems deploy chemical carbon-impregnated filters to suppress ambient ammonia below $0.1\text{ ppb}$. Simultaneously, fab environmental control units maintain ambient cleanroom temperatures at $21.0^\circ\text{C} \pm 0.1^\circ\text{C}$ and relative humidity at $45.0\% \pm 1.0\%$ to prevent wafer thermal expansion mismatch ($0.5\text{ ppm/}^\circ\text{C}$) and electrostatic discharge (ESD) charge accumulation, while deep concrete table waffle slabs dampen ground vibration to Generic Vibration Criteria VC-D and VC-E ($< 3.12\ \mu\text{m/s RMS}$) to ensure nanoscale EUV scanner stage alignment stability.
```flowchart
st=>start: Outside ambient air intake: particulate, humidity, and volatile chemical contamination
pre_filtration=>operation: HVAC Makeup Air Unit (MAU): chemical carbon scrubber (strip NH3/SOx) & HEPA pre-filter
recirc_plenum=>operation: Recirculation air mixing plenum: blend return air with temperature (±0.1°C) & humidity (±1%) control
ulpa_ceiling=>operation: Fan Filter Unit (FFU) ceiling grid: ULPA filtration (> 99.9995% @ 0.12 um)
laminar_sweep=>operation: Vertical laminar flow (0.45 m/s): sweep particles downward through perforated raised floor
foup_isolation=>operation: Nitrogen-purged FOUP transfer: isolate wafers in ISO Class 1 microenvironment (AMC < 0.1 ppb)
upw_supply=>operation: Continuous UPW loop supply: deliver 18.2 MOhm-cm water (TOC < 0.5 ppb, DO < 1 ppb)
pass=>end: Cleanroom Facilities Certified: zero particle escapes and defect-free nanoscale manufacturing
st->pre_filtration->recirc_plenum->ulpa_ceiling->laminar_sweep->foup_isolation->upw_supply->pass
```
**Delivering ultra-high yield learning rates and sub-angstrom process predictability across nanoscale semiconductor manufacturing requires evaluating fab infrastructure through a cleanroom-iso-classification-laminar-airflow-and-ultra-pure-water-facilities lens.** By uniting ISO 14644-1 airborne particle concentration kinetics, ULPA-driven vertical laminar displacement fields, thermodynamic $18.2\text{ M}\Omega\cdot\text{cm}$ ultra-pure water synthesis, chemical AMC carbon scrubbing, FOUP nitrogen micro-environments, and sub-micron structural vibration isolation, facility engineering teams create the pristine physical foundation required for leading-edge semiconductor fabrication. Mastering cleanroom and facility physics guarantees that billion-transistor logic dies, high-density 3D memory wafers, and advanced 2.5D/3D packaging chiplets achieve reproducible defect-free processing across decades of high-volume manufacturing.
**Ultimate SD Upscale** is the **advanced Stable Diffusion upscaling workflow that combines tile management, redraw control, and seam-aware refinement** - it is designed for high-resolution outputs with better boundary continuity than naive tiled processing.
**What Is Ultimate SD Upscale?**
- **Definition**: Extends SD upscaling with configurable tile redraw order and edge blending strategies.
- **Control Surface**: Exposes tile size, overlap, denoising, and seam-fix parameters for fine tuning.
- **Workflow Goal**: Preserves global composition while improving local detail across large canvases.
- **Typical Environment**: Used in advanced Stable Diffusion interfaces for large image rendering.
**Why Ultimate SD Upscale Matters**
- **Seam Reduction**: Improves cross-tile continuity in texture and lighting.
- **Large Canvas Quality**: Handles high pixel counts more robustly than simple upscale scripts.
- **Operational Flexibility**: Parameter-rich workflow supports domain-specific presets.
- **Production Value**: Useful for print-ready assets and high-resolution creative deliverables.
- **Complexity Cost**: More parameters increase tuning time and operator error risk.
**How It Is Used in Practice**
- **Preset Strategy**: Create validated presets for portrait, product, and environment content.
- **Seam Testing**: Inspect tile boundaries at full zoom before accepting final output.
- **Progressive Upscale**: Scale in multiple passes for very large resolution targets.
Ultimate SD Upscale is **a high-control workflow for demanding Stable Diffusion upscaling tasks** - Ultimate SD Upscale performs best when seam handling and denoising presets are rigorously validated.
**Ultra-Low-Power Subthreshold Circuit Design** is **a circuit methodology operating transistors below normal threshold voltages enabling exponentially reduced power consumption at the cost of reduced speed and increased process sensitivity** — Subthreshold operation leverages the exponential current-voltage relationship of MOSFET devices, enabling orders-of-magnitude power reduction for energy-constrained applications. **Transistor Physics** exploits exponential subthreshold current dependence on gate voltage, trading speed for power since lower voltages reduce current and frequency. **Power Benefits** deliver power consumption primarily from subthreshold leakage current avoiding dynamic switching power, enabling microwatt and nanowatt operation. **Speed Trade-offs** accept reduced circuit speed operating at kilohertz frequencies compared to gigahertz conventional operation, suitable for energy-constrained sensors and biomedical devices. **Voltage Scaling** reduces supply voltages to 0.3-0.5V from nominal 1.8-3.3V, enabling near-threshold operation maximizing energy efficiency. **Device Sizing** requires larger transistors compensating reduced transconductance, increasing area and capacitive loading. **Variability Management** addresses increased process variations in subthreshold region causing frequency and threshold voltage spreads, requiring robust design and adaptive techniques. **Circuit Topologies** employ differential pairs, cascode structures, and current mirrors adapted for subthreshold operation. **Applications** include biomedical sensors harvesting microwatts, wireless sensor networks requiring months of battery operation, and implantable devices demanding tiny power budgets. **Ultra-Low-Power Subthreshold Circuit Design** enables perpetually-operating autonomous systems.
Ion implantation, atomic doping profile engineering, and advanced millisecond thermal annealing constitute the fundamental semiconductor manufacturing disciplines required to construct p-n junctions, source/drain extensions, and electrostatic halo wells in integrated circuits. In modern nanoscale transistor architectures—including FinFETs, Gate-All-Around (GAA) nanosheets, and power semiconductor devices—controlling the spatial distribution of electrically active donor and acceptor atoms with sub-nanometer depth resolution determines on-state drive current, off-state leakage, and short-channel suppression. Achieving high dopant activation while maintaining ultra-shallow junction (USJ) abruptness requires balancing nuclear versus electronic ion stopping mechanics, eliminating crystal lattice channeling through tilt/twist orientation and pre-amorphization, suppressing transient enhanced diffusion (TED), and deploying non-melt laser spike annealing (LSA) to activate dopants beyond equilibrium solid solubility.
**Ion implantation introduces precisely calibrated quantities of chemical dopants by accelerating energetic ions into the silicon crystal lattice.** In an industrial high-current or medium-current beamline implanter, an arc-discharge plasma source ionizes precursor gases (such as boron trifluoride $\text{BF}_3$, phosphine $\text{PH}_3$, or arsine $\text{AsH}_3$). An analyzing magnet bends the extracted beam through a magnetic field ($r = \frac{1}{B} \sqrt{\frac{2m V_{\text{acc}}}{q}}$) to select exclusively the desired isotope species, filtering out unwanted molecular fragments. The purified ion beam is accelerated across electrostatic potentials ranging from sub-kilovolt regimes ($0.2\text{ keV}$ for shallow extensions) to mega-electron-volt regimes ($> 1\text{ MeV}$ for deep retrograde well isolation). As the incident ions penetrate the substrate, they lose kinetic energy through Lindhard-Scharff-Schiøtt (LSS) stopping mechanics: nuclear stopping ($S_n(E)$), involving elastic collisions with host silicon atomic nuclei that displace atoms and generate crystal damage; and electronic stopping ($S_e(E)$), involving inelastic drag against target electrons that decelerates ions without crystal lattice damage.
**Projected range and straggle govern the vertical Gaussian and Pearson depth distribution of implanted dopant species.** In an amorphous or randomized target, the one-dimensional atomic concentration profile ($C(x)$, in $\text{atoms/cm}^3$) as a function of depth ($x$) is described to first order by a Gaussian distribution governed by the ion dose ($\Phi$, in $\text{ions/cm}^2$), the mean projected range ($R_p$), and the longitudinal straggle ($\Delta R_p$):
$$
C(x) = \frac{\Phi}{\sqrt{2\pi} \Delta R_p} \exp\left[ -\frac{(x - R_p)^2}{2 \Delta R_p^2} \right].
$$
In single-crystal silicon wafers, if ions travel parallel to low-index crystallographic axes (such as $\langle 100 \rangle$ or $\langle 110 \rangle$), they experience reduced nuclear stopping and glide deep into open crystal interstitial corridors, producing an exponential channeling tail that broadens the junction depth. To suppress channeling, wafer implanters mechanically tilt the wafer normal by $\theta = 7^\circ$ and rotate the flat/notch twist angle by $\phi = 22^\circ$. For sub-3nm ultra-shallow extensions, fabs perform Pre-Amorphization Implantation (PAI), bombarding the substrate with heavy neutral germanium ($\text{Ge}^+$) or silicon ($\text{Si}^+$) ions to convert the top fifteen nanometers into a completely randomized amorphous layer prior to dopant introduction.
| Implantation Step | Dopant Species | Typical Energy Range | Typical Dose Range ($\text{ions/cm}^2$) | Projected Range ($R_p$) | Dominant Annealing Regrowth Mechanism | Primary Device Engineering Role |
|---|---|---|---|---|---|---|
| Deep Retrograde Well | $\text{B}^+ / \text{P}^+$ | $100\text{--}400\text{ keV}$ | $10^{13}\text{--}5 \times 10^{13}$ | $300\text{--}800\text{ nm}$ | Furnace / Soak RTP ($1000^\circ\text{C}$) | CMOS latch-up immunity, inter-well isolation |
| Threshold Voltage Adjust | $\text{BF}_2^+ / \text{As}^+$ | $5\text{--}25\text{ keV}$ | $10^{12}\text{--}5 \times 10^{12}$ | $15\text{--}40\text{ nm}$ | Rapid thermal anneal (RTA) | Target $V_{\text{th}}$ calibration for NMOS/PMOS |
| Angled Halo / Pocket | $\text{B}^+ / \text{In}^+ / \text{As}^+$ | $5\text{--}30\text{ keV}$ ($15^\circ\text{--}45^\circ\text{ tilt}$) | $2 \times 10^{13}\text{--}8 \times 10^{13}$ | $10\text{--}35\text{ nm}$ under gate edge | Spike RTA / Flash Anneal | Suppress DIBL, $V_{\text{th}}$ roll-off & punchthrough |
| Source/Drain Extension (SDE) | $\text{B}^+ / \text{BF}_2^+ / \text{As}^+$ | $0.2\text{--}2\text{ keV}$ (Sub-keV) | $10^{15}\text{--}3 \times 10^{15}$ | $3\text{--}10\text{ nm}$ | Laser Spike Anneal (LSA) | Ultra-shallow junction ($x_j < 10\text{nm}$), low overlap $C_{\text{ov}}$ |
| Deep Source/Drain Contact | $\text{P}^+ / \text{As}^+ / \text{B}^+$ | $10\text{--}40\text{ keV}$ | $3 \times 10^{15}\text{--}8 \times 10^{15}$ | $25\text{--}60\text{ nm}$ | Spike Anneal ($1050^\circ\text{C}$) | Low sheet resistance ($R_s < 100\ \Omega/\text{sq}$), salicide feed |
| Plasma Immersion (PLAD) | $\text{B}_2\text{H}_6 / \text{AsH}_3\text{ plasma}$ | $0.1\text{--}1.0\text{ kV bias}$ | $10^{15}\text{--}5 \times 10^{16}$ | Surface deposition / $< 5\text{nm}$ | Millisecond Laser Anneal | Conformal 3D sidewall doping for FinFET & GAA |
**Angled halo and pocket implants provide localized channel counter-doping to eliminate threshold voltage roll-off and drain-induced barrier lowering.** As MOSFET gate lengths shrink below twenty nanometers, the depletion regions of the source and drain junctions expand toward one another, lowering the channel potential barrier and causing severe $V_{\text{th}}$ roll-off and source-to-drain punchthrough leakage. Halo (or pocket) implantation injects dopants of the same conductivity type as the body (boron or indium for NMOS; arsenic or phosphorus for PMOS) at quad-rotation tilt angles ranging from $15^\circ\text{ to }45^\circ$ directly underneath the gate edges. This creates self-aligned, highly localized retrograde doping pockets adjacent to the source/drain extensions. The elevated local substrate doping sharpens junction depletion boundaries and maintains high electrostatic barrier heights under high drain bias ($V_{\text{DS}}$), suppressing DIBL ($\Delta V_{\text{th}} / \Delta V_{\text{DS}} < 40\text{ mV/V}$) while allowing the center channel to remain lightly doped for high electron and hole drift mobility.
**Transient enhanced diffusion and defect dissolution require millisecond laser spike annealing to achieve sub-ten-nanometer ultra-shallow junctions.** During ion bombardment, displaced host silicon atoms create excess self-interstitials and vacancies. Upon thermal heating, these interstitials aggregate into rod-like $\{311\}$ defect clusters and interstitial dislocation loops. At temperatures between $600^\circ\text{C}\text{ and }800^\circ\text{C}$, the $\{311\}$ clusters dissolve, releasing an intense, non-equilibrium burst of free silicon self-interstitials that pair with substitutional boron atoms, accelerating boron diffusion by up to four orders of magnitude—a phenomenon termed Transient Enhanced Diffusion (TED). To bypass TED and prevent junction broadening ($x_j$), advanced fabs employ non-melt Laser Spike Annealing (LSA) and Flash Lamp Annealing (FLA). Operating with infrared diode or $\text{CO}_2$ lasers ($10.6\ \mu\text{m}$ or $980\text{ nm}$), LSA heats the top wafer surface to $1200^\circ\text{C}\text{ to }1350^\circ\text{C}$ for a dwell time of only $0.1\text{ to }1.0\text{ milliseconds}$ ($D \cdot t \to 0$). The extreme temperature activates dopants onto substitutional lattice sites beyond equilibrium solid solubility ($> 2 \times 10^{20}\text{ atoms/cm}^3$), while the ultra-short duration freezes interstitial migration, delivering ultra-abrupt junction slopes ($< 1.5\text{ nm/decade}$) and sheet resistances below $300\ \Omega/\text{sq}$.
```flowchart
st=>start: Patterned Transistor Stack: gate stack with offset spacers exposing extension regions
pai_implant=>operation: Pre-Amorphization Implant (PAI): Ge+ bombardment amorphizes top 15nm to block channeling
ext_implant=>operation: Ultra-Shallow Extension Implant: sub-keV B+/As+ beamline implant forms SDE profile (xj < 10nm)
halo_implant=>operation: Quad-Rotational Angled Halo Implant: tilt 30° counter-doping under gate edges (suppress DIBL)
spacer_formation=>operation: Sidewall Spacer Deposition & Deep S/D Implant: heavy As+/P+ implant for low contact resistance
laser_anneal=>operation: Non-Melt Laser Spike Annealing (LSA): pulse 1300°C for 500 us (100% activation with zero TED)
pass=>end: Ultra-Shallow Junction Signoff: junction depth xj < 8nm with Rs < 300 ohm/sq and abruptness < 1.5 nm/dec
st->pai_implant->ext_implant->halo_implant->spacer_formation->laser_anneal->pass
```
**Delivering ultra-high drive currents and minimal parasitic series resistance in nanoscale devices requires evaluating junction formation through an ion-implantation-halo-pocket-doping-and-laser-annealing lens.** By uniting mass-analyzed beamline ion acceleration, LSS nuclear and electronic stopping physics, pre-amorphization channeling suppression, self-aligned angled halo electrostatics, and millisecond laser spike activation kinetics, doping engineering teams achieve optimal transistor performance. Mastering ion implantation and thermal activation fundamentals ensures that sub-2nm GAA nanosheets, high-speed FinFETs, and high-voltage power switches maintain precise junction abruptness, low leakage, and robust reliability across high-volume wafer manufacturing.
**Ultra-thin body and buried oxide (UTBB) is an FD-SOI transistor architecture built on a very thin silicon device layer above a thin buried-oxide layer.** The thin silicon body can be fully depleted during normal operation, improving electrostatic control of the channel, while the thin buried oxide (BOX) enables the substrate or back plane to act as an effective second control terminal.
UTBB is closely associated with fully depleted silicon-on-insulator (FD-SOI) technology. The exact silicon and BOX thicknesses are process-specific rather than universal: published platforms may use a silicon film of only several nanometers and a BOX on the order of a few tens of nanometers. Uniformity of both layers is critical because thickness variation can shift transistor electrostatics and circuit performance.
**The front gate controls the channel through the gate dielectric, while the back plane influences it through the BOX.** To first order, a process can characterize the body-bias response as:
$$
\Delta V_T \approx \eta\,\Delta V_{BB}
$$
where $V_{BB}$ is the applied back-bias voltage and $\eta$ is a process-, device-, bias-, and temperature-dependent coupling coefficient. This compact relationship is useful for intuition, but circuit sign conventions and allowable bias ranges must follow the foundry models for the specific NMOS and PMOS devices.
| UTBB element | Function | Key control concern |
|---|---|---|
| Ultra-thin silicon body | Allows full depletion and strong front-gate control | Thickness uniformity and interface quality |
| Thin buried oxide | Electrically isolates the body while enabling back-gate coupling | Defects, breakdown, coupling, and self-heating |
| Back plane or well | Provides the body-bias control terminal | Well isolation, resistance, noise, and bias range |
| Front gate stack | Controls inversion and switching | Work function, equivalent oxide thickness, and variability |
| Source/drain regions | Inject and collect carriers | Series resistance, junction design, and contact integration |
**Full depletion improves short-channel electrostatics.** Because the silicon film contains little neutral body volume, the gate can control the channel potential with less dependence on heavy channel doping. Lower channel doping can reduce random-dopant fluctuation, although total variability still includes line-edge roughness, gate work-function variation, film-thickness variation, interfaces, and process-pattern effects.
Body bias provides a useful performance and leakage control. One bias direction lowers effective threshold voltage, increasing drive current and speed at the cost of leakage; the opposite direction raises threshold voltage, reducing leakage at the cost of speed. This enables adaptive operation across active, idle, and standby modes. Designers can also use separate back-plane configurations and device options to create threshold-voltage choices without relying solely on channel doping.
| Operating objective | Body-bias intent | Typical tradeoff |
|---|---|---|
| Performance boost | Reduce effective threshold voltage | Higher leakage and tighter reliability limits |
| Leakage reduction | Increase effective threshold voltage | Lower speed |
| Process compensation | Offset die-to-die or within-die shifts | Requires sensing, control, and bias distribution |
| Dynamic power management | Change bias with workload state | Transition latency and bias-generator overhead |
**Body bias is not free.** The chip needs bias generators or external rails, a distribution network, isolation structures, sequencing rules, and verification across operating modes. Back-bias transitions can couple noise into sensitive blocks, and well resistance can create spatial voltage differences. Analog, RF, memory, I/O, and high-voltage circuits may have different bias restrictions, so the power-domain and well architecture must be planned early.
The thin BOX improves electrostatic coupling but is a thermal insulator. Heat generated in the channel and source/drain regions may have a more difficult path into the substrate than in bulk silicon, creating self-heating and temperature-dependent delay or reliability effects. Thermal behavior depends on geometry, activity, layout density, interconnect, package, and workload; it should be characterized with process-qualified compact models rather than inferred from a single generic number.
**Manufacturing begins with a specialized SOI substrate.** The device film and BOX must meet tight thickness, defect, roughness, and contamination requirements. Front-end integration then forms isolation, wells or back planes, gate stacks, spacers, source/drain structures, contacts, and interconnects. Process control must preserve the ultra-thin film through cleaning, oxidation, etch, implantation, and thermal steps without consuming or damaging the channel.
| Architecture | Electrostatic control | Body-bias capability | Integration character |
|---|---|---|---|
| Bulk planar CMOS | Weaker at short gate lengths | Conventional body effect, junction-limited | Mature substrate and process flow |
| UTBB FD-SOI | Fully depleted thin planar body | Strong, useful back-gate coupling | Specialized SOI wafer and back-plane design |
| FinFET | Multi-surface gate control | Usually limited body-bias leverage | Three-dimensional fin patterning |
| Gate-all-around | Gate surrounds nanosheet or nanowire | Architecture-dependent | Complex stacked-channel fabrication |
UTBB can preserve a planar transistor layout style while delivering strong electrostatics and dynamic threshold control. That can be attractive for energy-efficient digital logic, embedded systems, mixed-signal integration, RF, and products with wide performance states. The best architecture still depends on density, frequency, leakage, analog requirements, IP availability, cost, design ecosystem, and manufacturing maturity.
Production design uses foundry-qualified compact models that capture front-gate behavior, back-bias response, temperature, self-heating, capacitance, noise, and statistical variation. Signoff should cover permitted bias combinations, power sequencing, reliability limits, electromigration in bias distribution, latch-up or parasitic behavior where applicable, ESD interactions, and test access. Silicon monitors can track process speed and temperature so adaptive bias control operates within characterized limits.
```svg
```
In short, UTBB combines a fully depleted planar silicon body with a thin BOX that makes back bias a practical circuit-control knob. Its value comes from the co-design of substrate, transistor electrostatics, bias infrastructure, thermal behavior, compact models, and system power management rather than from thin films alone.
**Ultralytics YOLO** is the **most widely used real-time object detection framework, providing the YOLOv5 and YOLOv8 model families with a "zero to hero" developer experience** — enabling training of state-of-the-art detection, segmentation, pose estimation, and classification models on custom datasets with as few as 3 lines of Python code, automatic export to every major deployment format (ONNX, CoreML, TFLite, TensorRT), and real-time inference on webcams, edge devices, and production servers.
**What Is Ultralytics YOLO?**
- **Definition**: A Python framework by Ultralytics (founded by Glenn Jocher) that implements the YOLO (You Only Look Once) family of single-stage object detection models — where the entire image is processed in one forward pass through the network, predicting bounding boxes and class probabilities simultaneously for real-time speed.
- **YOLOv8**: The latest generation supporting four task types in a unified architecture — object detection (bounding boxes), instance segmentation (pixel masks), pose estimation (keypoint skeletons), and image classification — all trained and deployed through the same CLI and Python API.
- **Speed/Accuracy Balance**: YOLO models are the default choice for real-time applications — YOLOv8n (nano) runs at 300+ FPS on a modern GPU for edge deployment, while YOLOv8x (extra-large) achieves 53.9% mAP on COCO for maximum accuracy.
- **Ecosystem**: Built-in data augmentation (mosaic, mixup, copy-paste), automatic hyperparameter tuning, Weights & Biases / MLflow / Comet integration, and one-command export to 11+ deployment formats.
**YOLOv8 Model Variants**
| Model | Params | mAP (COCO) | Speed (A100) | Use Case |
|-------|--------|-----------|-------------|----------|
| YOLOv8n | 3.2M | 37.3% | 0.99ms | Edge, mobile, IoT |
| YOLOv8s | 11.2M | 44.9% | 1.20ms | Balanced speed/accuracy |
| YOLOv8m | 25.9M | 50.2% | 1.83ms | General production |
| YOLOv8l | 43.7M | 52.9% | 2.39ms | High accuracy |
| YOLOv8x | 68.2M | 53.9% | 3.53ms | Maximum accuracy |
**Key Features**
- **3-Line Training**: `from ultralytics import YOLO; model = YOLO("yolov8n.pt"); model.train(data="coco128.yaml", epochs=100)` — complete training pipeline with augmentation, validation, and checkpointing in three lines.
- **Multi-Task Architecture**: The same YOLOv8 backbone supports detection (`yolov8n.pt`), segmentation (`yolov8n-seg.pt`), pose (`yolov8n-pose.pt`), and classification (`yolov8n-cls.pt`) — switch tasks by changing the model file.
- **Export to 11+ Formats**: `model.export(format="onnx")` converts to ONNX, TensorRT, CoreML, TFLite, OpenVINO, PaddlePaddle, NCNN, and more — one command for any deployment target.
- **Real-Time Inference**: `model.predict(source="webcam")` runs real-time detection on webcam, video files, RTSP streams, or image directories — with built-in visualization and tracking (ByteTrack, BoT-SORT).
- **Ultralytics HUB**: Cloud platform for dataset management, model training, and deployment — train YOLOv8 models without local GPU resources.
**YOLO vs Other Detection Frameworks**
| Framework | Ease of Use | Speed | Accuracy | Research Flexibility |
|-----------|------------|-------|----------|---------------------|
| Ultralytics YOLO | Excellent | Fastest | Very good | Moderate |
| MMDetection | Moderate | Good | Excellent | Excellent |
| Detectron2 | Moderate | Good | Excellent | Excellent |
| TF Object Detection | Complex | Good | Good | Good |
| DETR (Transformers) | Moderate | Slower | Excellent | Excellent |
**Ultralytics YOLO is the real-time object detection framework that makes production computer vision accessible to every developer** — combining state-of-the-art accuracy with unmatched ease of use, multi-task support, and universal export capabilities that take a custom detection model from training to edge deployment in minutes rather than weeks.
**Ultrasonic Testing** is **high-frequency acoustic inspection used to detect leaks, friction, and material discontinuities** - It captures early-stage faults often invisible to visual inspection.
**What Is Ultrasonic Testing?**
- **Definition**: high-frequency acoustic inspection used to detect leaks, friction, and material discontinuities.
- **Core Mechanism**: Ultrasonic signatures from turbulence, arcing, or mechanical contact are trended against baseline behavior.
- **Operational Scope**: It is applied in manufacturing-operations workflows to improve flow efficiency, waste reduction, and long-term performance outcomes.
- **Failure Modes**: Background noise and poor probe technique can reduce detection reliability.
**Why Ultrasonic Testing Matters**
- **Outcome Quality**: Better methods improve decision reliability, efficiency, and measurable impact.
- **Risk Management**: Structured controls reduce instability, bias loops, and hidden failure modes.
- **Operational Efficiency**: Well-calibrated methods lower rework and accelerate learning cycles.
- **Strategic Alignment**: Clear metrics connect technical actions to business and sustainability goals.
- **Scalable Deployment**: Robust approaches transfer effectively across domains and operating conditions.
**How It Is Used in Practice**
- **Method Selection**: Choose approaches by bottleneck impact, implementation effort, and throughput gains.
- **Calibration**: Train inspectors and validate signal thresholds with controlled defect references.
- **Validation**: Track throughput, WIP, cycle time, lead time, and objective metrics through recurring controlled evaluations.
Ultrasonic Testing is **a high-impact method for resilient manufacturing-operations execution** - It extends predictive diagnostics to pressure systems and electrical assets.
Ultraviolet photoelectron spectroscopy, abbreviated UPS, uses ultraviolet photons to eject electrons from occupied valence states and measures their kinetic-energy distribution in ultrahigh vacuum. With a helium discharge source, the common He I line is 21.22 eV and He II is 40.81 eV. The resulting spectrum can reveal valence-band density of states, Fermi-edge position, valence onset, sample work function, and ionization energy with extreme surface sensitivity, often dominated by roughly the upper 0.5–1 nm of material.
**Photoemission is an energy-conservation measurement.** For an electron referenced consistently to the sample and analyzer,
$$E_{kin}=h\nu-E_B-\Phi_{spec}$$
where $h\nu$ is photon energy, $E_B$ is binding energy, and $\Phi_{spec}$ represents the analyzer work-function convention used by the instrument. Calibration establishes how the kinetic-energy axis maps to binding energy and the Fermi level. Mixing analyzer, sample, and vacuum-level references is a common source of plausible-looking but incorrect work-function or band-alignment values.
**The secondary-electron cutoff carries the sample work function.** A small negative sample bias separates low-energy electrons from the analyzer threshold so the cutoff can be fit reliably. Under a common calibrated convention, work function is photon energy minus the measured spectral width between cutoff and Fermi edge. An illustrative He I spectrum with width 16.70 eV gives
$$\Phi=21.22-16.70=4.52\ \text{eV}$$
provided bias, contact potential, energy scale, and edge definitions are handled correctly. The arithmetic is simple; defining and fitting the two edges is the real experiment.
**Valence onset converts work function into ionization energy.** For a semiconductor or molecular film whose occupied-state onset lies 0.80 eV below the Fermi reference, the illustrative ionization energy is $IE=4.52+0.80=5.32$ eV. That quantity helps align a valence-band maximum or highest occupied molecular orbital to vacuum. If the sample charges, lacks electrical equilibrium, contains gap states, or has a gradual density-of-states tail, the onset becomes model dependent and the band diagram must carry that uncertainty.
**UPS sees the prepared surface rather than an abstract bulk material.** Adsorbed water, oxygen, hydrocarbons, oxide, cleaning residue, sputter damage, molecular orientation, termination, reconstruction, and ambient transfer can shift work function or change valence intensity. A few hours in air may alter the exact quantity UPS is meant to measure. In-situ deposition, vacuum transfer, glovebox coupling, controlled dosing, annealing, or capped-reference strategies are often more important than adding spectral decimals.
**Sample charging and electrical contact determine whether the energy scale is trustworthy.** Conductive samples equilibrate with the analyzer through the mount. Insulators and poorly contacted films can charge positively during photoemission, shifting and broadening spectra. Flood guns, lower flux, thinner films, conductive substrates, improved grounding, or pulsed acquisition may help, but compensation can introduce its own fields and energy uncertainty. Ground-path verification and repeat spectra at different photon flux belong in the method.
| UPS control | Purpose | Failure if uncontrolled | Evidence retained |
|---|---|---|---|
| Photon line and flux | define excitation and count rate | satellites, damage or drift | source line, current and exposure |
| Energy calibration | establish EF and kinetic scale | systematic work-function error | reference metal before/after |
| Sample bias | reveal secondary cutoff | analyzer-threshold ambiguity | applied and measured bias sweep |
| Surface preparation | represent intended interface | adventitious layer dominates | transfer history and survey data |
| Grounding/charging | maintain common energy reference | shifted or broadened spectrum | flux series and contact check |
| Edge/onset fitting | extract width and band position | analyst-dependent result | fit window, model, residual, uncertainty |
The workflow preserves the full path from surface state to band-alignment decision.
```flowchart
Define interface and energy quantity -> Prepare and transfer representative surface -> Establish electrical contact and UHV -> Calibrate EF and energy scale -> Apply qualified bias and acquire cutoff plus valence spectrum -> Fit cutoff, EF, and onset with uncertainty -> Cross-check charging and damage -> Build work-function and band-alignment model
```
The He discharge lamp is not perfectly monochromatic. He I and He II operation, satellite lines, source pressure, window state, differential pumping, and lamp aging affect spectrum and background. Monochromated or synchrotron excitation can provide different resolution, tunability, and polarization. Source choice changes photoionization cross sections, escape depth, and orbital sensitivity, so intensity differences between He I at 21.22 eV and He II at 40.81 eV should not be interpreted as composition changes without cross-section analysis.
Energy resolution combines source linewidth, analyzer pass energy, slit, lens mode, angular acceptance, sample temperature, and electronic stability. A narrow Fermi edge on a clean reference metal can estimate system resolution. Lower pass energy improves resolution but reduces count rate; longer acquisition increases damage or drift risk. The chosen resolution should answer the onset or state-separation question rather than maximize a specification disconnected from sample stability.
Angle-resolved UPS can measure band dispersion and molecular orbital orientation, while angle-integrated UPS emphasizes density of occupied states. Changing emission angle also changes surface sensitivity and matrix elements. Polarization selects orbital symmetries at synchrotron sources. Those capabilities require accurate geometry, sample orientation, momentum conversion, and crystalline order. A polycrystalline or rough sample cannot support the same momentum-space claims as a clean single crystal.
Depth sensitivity is both advantage and limitation. UPS is exceptionally sensitive to the surface and topmost interface, making it ideal for electrode treatments, organic semiconductor alignment, two-dimensional materials, catalysts, oxides, and freshly deposited films. It cannot by itself reveal a deeply buried interface beneath a thick overlayer. Stepwise deposition, controlled sputtering with damage awareness, wedge samples, hard/soft X-ray photoemission, or cross-sectional approaches may be required for depth-dependent alignment.
UPS and XPS answer complementary questions. XPS uses higher-energy X-rays to identify elemental composition, chemical states, and core-level shifts, while UPS resolves occupied valence structure and work function more directly. HAXPES increases information depth; inverse photoemission probes unoccupied states; Kelvin probe measures contact-potential difference; optical absorption estimates gaps; scanning tunneling spectroscopy or transport provides local or device behavior. A credible energy-level diagram often combines several methods rather than asking UPS to supply every edge.
Data analysis should retain raw counts, dwell, pass energy, source line, bias, energy convention, calibration, background, fit intervals, smoothing, and residuals. The secondary cutoff may be fit with a line intersection, derivative, sigmoid, or physical response model; valence onset may use linear extrapolation or density-of-states modeling. Different choices can shift results by tenths of an electronvolt, large enough to change a claimed injection barrier. Reporting only the final 4.52 eV hides the decision path.
Kratos Analytical, Thermo Fisher Scientific, ULVAC-PHI, Scienta Omicron, SPECS, PREVAC, JEOL, and STAIB Instruments provide photoelectron systems, analyzers, and sources. MKS Instruments, Pfeiffer Vacuum, Edwards Vacuum, Agilent Technologies, and VACOM support UHV infrastructure. NIST, PTB, synchrotron laboratories, imec, CEA-Leti, Fraunhofer institutes, universities, and semiconductor or display manufacturers develop reference methods and apply UPS to gate metals, organic electronics, contacts, dielectrics, two-dimensional materials, and surface treatments.
Reproducibility requires more than repeated scans on one spot. Sample-to-sample preparation, transfer time, chamber base pressure, illumination history, grounding, analyzer calibration, fit operator, and surface aging should enter the measurement-system study. Spatial nonuniformity may require multiple sites; beam damage may require fresh sites. A reference metal measured before and after the batch separates instrument drift from sample change, while XPS surveys detect contamination that invalidates a nominally clean UPS interpretation.
Band alignment must respect equilibrium. When two materials contact, interface dipoles, charge transfer, chemical reaction, band bending, gap states, and Fermi-level pinning can make the real interface different from the vacuum-level alignment inferred from separate pristine surfaces. Measuring incremental film thickness or the actual interface stack provides stronger evidence. UPS supplies occupied-state and work-function constraints, but the final device barrier is an interface property.
Read ultraviolet photoelectron spectroscopy through an *energy-reference* lens: every work function and valence onset is meaningful only when photon energy, analyzer calibration, sample bias, Fermi reference, charging state, surface history, and fit convention share one consistent energy accounting. A professional UPS result is not just a spectrum or a number; it is a traceable band-alignment measurement tied to the exact surface and interface the device will use.
**Umbrella Sampling** is a **fundamental enhanced sampling technique in computational chemistry used to calculate the absolute Free Energy Profile (Potential of Mean Force) along a specific reaction pathway** — operating by restricting a molecular system into a series of overlapping segments and utilizing artificial harmonic springs to aggressively drag it through highly unfavorable transition states that normal physics would avoid.
**How Umbrella Sampling Works**
- **The Reaction Coordinate**: You define a specific pathway (e.g., pulling a Sodium ion physically straight through a thick lipid membrane).
- **The Windows**: You divide that continuous pathway into 20 to 50 distinct overlapping "windows" (e.g., 1 Angstrom depth, 2 Angstrom depth, 3 Angstrom depth).
- **The Restraint (The Umbrella)**: You run an independent Molecular Dynamics simulation specifically for each window. You apply a heavy harmonic bias potential (essentially a stiff mathematical spring) that violently snaps the system back if it tries to escape that specific window.
- **The Data Splicing**: The molecule spends the simulation fighting against the spring. By mathematically un-biasing the data and splicing all the windows together using the standard **WHAM (Weighted Histogram Analysis Method)** algorithm, the precise continuous energy landscape is revealed.
**Why Umbrella Sampling Matters**
- **Calculating Permeability**: The only definitive way to prove if a small molecule drug can physically penetrate the human blood-brain barrier. By dragging the drug explicitly through the membrane in 1-Angstrom steps, scientists identify the exact energetic peak required for crossing.
- **Binding Affinity (Absolute)**: While Free Energy Perturbation (FEP) calculates *relative* differences between two drugs alchemically, Umbrella sampling can calculate the *absolute* binding energy of a single drug by physically dragging it out of the protein pocket into the surrounding water and measuring the total resistance.
- **Catalytic Pathways**: Discovering the exact peak activation energy ($E_a$) of a chemical reaction catalyzed by an enzyme, informing modifications to accelerate the process.
**Challenges and Limitations**
**The Perpendicular Problem**:
- Umbrella sampling works flawlessly if the chosen path is correct. However, if you pull the drug "straight out" of the pocket, but the *true* physical pathway requires the drug to twist 90 degrees and slip out a side channel, you will calculate an artificially massive, false energy barrier.
**Steered Molecular Dynamics (SMD)**:
- Often serves as the prequel to Umbrella Sampling. SMD rapidly drags the molecule to generate the starting configurations (the coordinates) for all the individual windows, before settling in for the long, rigorous sampling calculations.
**Umbrella Sampling** is **computational resistance training** — anchoring a molecule to a rigorous geometric treadmill to surgically measure the extreme thermodynamic costs of biological intrusion.
**Unbiased HAST (uHAST)** is a **moisture reliability test performed without electrical bias that evaluates the mechanical integrity of semiconductor packages under accelerated moisture exposure** — subjecting packages to 130°C, 85% RH, and >2 atm pressure without applied voltage to test for moisture-induced delamination, popcorn cracking, mold compound swelling, and adhesion failures that are driven by moisture absorption and thermal stress rather than electrochemical mechanisms.
**What Is uHAST?**
- **Definition**: A HAST test performed without electrical bias applied to the device — the package is exposed to the same elevated temperature, humidity, and pressure conditions as biased HAST, but without voltage, isolating the mechanical and physical effects of moisture from the electrochemical effects that require an electric field.
- **Mechanical Focus**: Without bias, there is no electrochemical driving force for corrosion or dendritic growth — uHAST specifically tests for moisture-induced mechanical failures: delamination at material interfaces, mold compound swelling, popcorn cracking, and adhesion degradation.
- **Package Integrity Test**: uHAST answers the question "does the package physically survive moisture exposure?" — while biased HAST answers "does the device electrically survive moisture exposure?" Both are needed for complete moisture reliability qualification.
- **JEDEC Standard**: uHAST follows JESD22-A118 — typically 96 hours at 130°C/85% RH without bias, with pre- and post-test electrical measurements and acoustic microscopy (C-SAM) to detect internal delamination.
**Why uHAST Matters**
- **Delamination Detection**: Moisture absorbed by mold compound creates internal vapor pressure during heating — if the adhesion between mold compound and die/lead frame is insufficient, this pressure causes delamination that uHAST reveals through C-SAM imaging.
- **Popcorn Cracking**: Rapid heating of a moisture-saturated package (e.g., during reflow) can cause explosive steam generation — uHAST pre-conditions the package with moisture to test susceptibility to popcorn cracking during subsequent reflow simulation.
- **Material Qualification**: uHAST is the primary test for qualifying new mold compounds, underfill materials, and die attach adhesives — evaluating their moisture absorption, adhesion retention, and dimensional stability under accelerated moisture exposure.
- **Separate from Corrosion**: By removing electrical bias, uHAST isolates mechanical failure modes from electrochemical ones — enabling root cause analysis that distinguishes between "the package fell apart" (mechanical) and "the metal corroded" (electrochemical).
**uHAST Test Protocol**
| Step | Action | Purpose |
|------|--------|---------|
| 1 | Pre-test electrical measurement | Baseline parameters |
| 2 | Pre-test C-SAM imaging | Baseline delamination map |
| 3 | uHAST exposure (130°C/85%RH, 96 hrs) | Moisture stress |
| 4 | Post-test electrical measurement | Detect parametric shifts |
| 5 | Post-test C-SAM imaging | Detect new delamination |
| 6 | Cross-section analysis (if failed) | Root cause identification |
**uHAST is the mechanical moisture integrity test that complements biased HAST** — evaluating whether semiconductor packages can physically withstand accelerated moisture exposure without delamination, cracking, or adhesion failure, providing the mechanical reliability assurance that biased HAST's electrochemical focus does not cover.
**Unbiased Learning Rank** is **learning-to-rank with corrections for click and position bias in logged interaction data.** - It aims to recover true relevance signals from biased user-feedback logs.
**What Is Unbiased Learning Rank?**
- **Definition**: Learning-to-rank with corrections for click and position bias in logged interaction data.
- **Core Mechanism**: Propensity-corrected losses reweight clicks by observation likelihood to remove exposure bias.
- **Operational Scope**: It is applied in debiasing and causal recommendation systems to improve robustness, accountability, and long-term performance outcomes.
- **Failure Modes**: High-variance weights can destabilize training when propensities are very small.
**Why Unbiased Learning Rank Matters**
- **Outcome Quality**: Better methods improve decision reliability, efficiency, and measurable impact.
- **Risk Management**: Structured controls reduce instability, bias loops, and hidden failure modes.
- **Operational Efficiency**: Well-calibrated methods lower rework and accelerate learning cycles.
- **Strategic Alignment**: Clear metrics connect technical actions to business and sustainability goals.
- **Scalable Deployment**: Robust approaches transfer effectively across domains and operating conditions.
**How It Is Used in Practice**
- **Method Selection**: Choose approaches by uncertainty level, data availability, and performance objectives.
- **Calibration**: Clip extreme weights and evaluate debiased metrics on interleaving or randomized traffic samples.
- **Validation**: Track quality, stability, and objective metrics through recurring controlled evaluations.
Unbiased Learning Rank is **a high-impact method for resilient debiasing and causal recommendation execution** - It is central for reliable ranking from observational click data.
**Uncertainty Quantification (UQ)** is the **science of measuring and communicating the confidence of machine learning model predictions** — distinguishing between uncertainty that arises from irreducible noise in data (aleatoric) and uncertainty that arises from insufficient training data or model limitations (epistemic), enabling AI systems to know what they don't know.
**What Is Uncertainty Quantification?**
- **Definition**: UQ methods produce not just a point prediction (class label, numeric value) but a probability distribution or confidence interval over possible outcomes — quantifying how much the model should be trusted for any given input.
- **Core Problem**: Standard neural networks trained with maximum likelihood estimation produce single-point predictions without native uncertainty estimates — they output "Cat: 97%" whether the input is a clear cat photo or a blurry blob that barely resembles a cat.
- **Safety Imperative**: In autonomous driving, medical diagnosis, structural engineering, and financial risk — acting on overconfident predictions causes systematic errors. Knowing when to defer to humans or collect more data requires reliable uncertainty estimates.
**The Two Types of Uncertainty**
**Aleatoric Uncertainty (Data Uncertainty)**:
- Caused by inherent noise, ambiguity, or randomness in the data-generating process.
- Example: A blurry medical image where even expert radiologists disagree.
- Example: Speech recognition in a loud environment where phonemes are genuinely ambiguous.
- Cannot be reduced by collecting more training data — the noise is in the measurement itself.
- Reducible only by improving data quality (better sensors, cleaner measurements).
- Modeled by: Having the network predict a distribution over outputs (mean + variance) rather than a point estimate.
**Epistemic Uncertainty (Model Uncertainty)**:
- Caused by lack of knowledge — insufficient training data in certain regions of input space.
- Example: A medical AI trained only on adults encountering its first pediatric patient.
- Example: An autonomous vehicle encountering snow for the first time after training only in California.
- Can be reduced by collecting more training data in the uncertain region.
- Modeled by: Maintaining uncertainty over model parameters (Bayesian approaches) or using model ensembles.
- Key diagnostic signal: High epistemic uncertainty on an input suggests the model is being asked to extrapolate beyond its training distribution.
**Why UQ Matters**
- **Medical AI**: A radiology model that can flag "I'm uncertain about this scan — please have a specialist review it" is safer than one that always outputs a confident prediction.
- **Autonomous Systems**: An autonomous drone that knows when its navigation model is unreliable can reduce speed, request human override, or refuse the mission.
- **Active Learning**: Epistemic uncertainty identifies which unlabeled examples would be most informative to label — directing human annotation effort efficiently.
- **Anomaly Detection**: High uncertainty on an input is a strong signal that the input is out-of-distribution or anomalous.
- **Scientific Discovery**: UQ in surrogate models for molecular simulation tells researchers which regions of chemical space need more expensive simulation.
**UQ Methods**
**Bayesian Neural Networks (BNNs)**:
- Replace point weight estimates with probability distributions over weights.
- Inference integrates over all possible weight values (expensive but principled).
- Methods: Variational inference (mean-field), MCMC (Laplace approximation).
- Limitation: Computationally prohibitive for large networks; approximations reduce accuracy.
**Deep Ensembles**:
- Train N independent models with different random initializations.
- Prediction = average of N predictions; uncertainty = variance across N predictions.
- Simple, effective, and scales well; often considered the practical gold standard.
- Cost: N× training and inference compute.
**Monte Carlo Dropout (MC Dropout)**:
- Keep dropout active during inference; run multiple forward passes.
- Different dropout masks = different model variants; variance = uncertainty estimate.
- Gal & Ghahramani (2016): Mathematically equivalent to approximate Bayesian inference.
- Practical advantage: No architecture change required; uncertainty from any dropout-trained model.
**Conformal Prediction**:
- Distribution-free, statistically valid coverage guarantee.
- Output: Prediction set containing true label with probability ≥ 1-α.
- No distributional assumptions; valid coverage guaranteed under exchangeability.
- Limitation: Prediction sets can be large when uncertainty is high.
**Deterministic UQ Methods**:
- Single-model approaches: Deep Deterministic Uncertainty (DDU), SNGP (Spectral-normalized GP).
- Compute efficiency of standard neural networks with uncertainty estimates.
**UQ for LLMs**
Language model uncertainty quantification is particularly challenging:
- **Verbalized Confidence**: Ask the model "How confident are you?" — often unreliable due to RLHF-induced overconfidence.
- **Logit-based**: Use softmax probabilities of output tokens — limited to token-level uncertainty.
- **Semantic Entropy**: Measure diversity of semantically equivalent generations — higher diversity = higher uncertainty (Kuhn et al., 2023).
- **Multiple Sampling**: Generate K responses; high variance in factual claims signals uncertainty.
Uncertainty quantification is **the mechanism that transforms AI from a black-box oracle into a calibrated epistemic partner** — by honestly communicating what it knows and doesn't know, a UQ-equipped AI system enables humans to make better decisions about when to trust, verify, or override model predictions.
**Uncertainty Quantification Bayesian Deep Learning** is **methods estimating prediction uncertainty, distinguishing between epistemic (model) uncertainty and aleatoric (data) uncertainty, enabling confident predictions and risk quantification** — essential for safety-critical applications. Uncertainty crucial for decision-making. **Epistemic Uncertainty** model uncertainty: given observed data, uncertainty about true parameters. Reduces with more data. Comes from limited training data. **Aleatoric Uncertainty** data uncertainty: irreducible noise in observations. Examples: measurement noise, inherent randomness. Cannot reduce with more data. **Bayesian Neural Networks** place probability distributions over weights rather than point estimates. Predictions are distributions, not scalars. **Variational Inference** approximate posterior over weights with variational distribution q(w). Optimize KL divergence between q and true posterior p(w|data). Computationally efficient. **Monte Carlo Dropout** Bayesian interpretation of dropout: different dropout masks correspond to samples from approximate posterior. Multiple forward passes with dropout provide uncertainty. **Uncertainty in Layers** different layers contribute differently to uncertainty. Analyze layer-wise contributions. **Predictive Posterior** p(y|x, data) = ∫ p(y|x,w) p(w|data) dw. Integral over parameter distribution. Approximated via sampling. **Calibration** model calibration: predicted uncertainty matches empirical error. Well-calibrated model's 90% confidence predictions correct 90% of time. **Overconfidence** neural networks often overconfident (predictions poorly calibrated). Temperature scaling: divide logits by learnable temperature. **Adversarial Examples and Uncertainty** adversarial examples often high-confidence incorrect predictions. Uncertainty estimation detects some (but not all) adversarial examples. **Out-of-Distribution Detection** uncertain predictions on out-of-distribution inputs. Separate epistemic uncertainty (OOD) from aleatoric (test distribution). **Laplace Approximation** approximate posterior with Gaussian around MAP estimate. Second-order Taylor expansion of log posterior. **Deep Ensembles** train multiple models, predictions averaged. Disagreement among ensemble measures uncertainty. Approximates Bayesian averaging. **Heteroscedastic Regression** aleatoric uncertainty: output distribution variance alongside mean. Network predicts both μ and σ. **Selective Prediction** models abstain on uncertain predictions. Improves reliability by ignoring uncertain cases. **Uncertainty for Active Learning** select most uncertain examples for labeling. Reduces annotation cost. **Reinforcement Learning Uncertainty** uncertainty in Q-learning, policy gradients. Exploration-exploitation tradeoff. Uncertainty-driven exploration. **Risk-Sensitive Decisions** use uncertainty for risk-aware decisions. Medical diagnosis: high uncertainty → require more tests. **Information Theory and Entropy** entropy of prediction: high entropy = high uncertainty. Mutual information: epistemic information. **Bayesian Optimization** select next point to evaluate minimizing posterior uncertainty of optimum. Acquisition functions (expected improvement, uncertainty-based). **Neural Network Approximations** sampling-based (Monte Carlo Dropout, deep ensembles) vs. parametric (variational inference). Trade-offs: accuracy vs. computational cost. **Applications** autonomous driving (uncertain predictions trigger caution), medical diagnosis (uncertain predictions need review), exploration in RL. **Benchmarks and Evaluation** metrics: calibration error, Brier score, negative log-likelihood. **Scalability Challenges** uncertainty estimation adds computational cost. Sampling multiple models/forward passes. **Uncertainty Quantification is increasingly important for deploying AI systems** in high-stakes settings.
**Uncertainty-Based Rejection** is a selective prediction strategy that uses estimated prediction uncertainty—rather than raw confidence scores—to decide when a model should abstain from making predictions, routing uncertain inputs to human experts or fallback systems. By leveraging uncertainty estimates from Bayesian methods, ensembles, or MC Dropout, this approach captures model ignorance (epistemic uncertainty) that raw softmax confidence often fails to detect.
**Why Uncertainty-Based Rejection Matters in AI/ML:**
Uncertainty-based rejection provides **more reliable abstention decisions** than confidence thresholding because it directly measures model uncertainty rather than relying on softmax probabilities, which are notoriously overconfident and poorly calibrated for detecting out-of-distribution inputs.
• **Softmax overconfidence problem** — Standard softmax probabilities can assign ≥99% confidence to completely wrong predictions, especially on out-of-distribution inputs; uncertainty-based rejection using ensemble disagreement or Bayesian uncertainty detects these cases that confidence thresholding misses
• **Ensemble disagreement** — When multiple independently trained models disagree on a prediction, the variance across their outputs provides a direct measure of epistemic uncertainty; high disagreement triggers rejection even if individual models appear confident
• **MC Dropout uncertainty** — Running T stochastic forward passes (T=10-50) with dropout enabled at inference produces a distribution of predictions; the variance of this distribution estimates epistemic uncertainty without requiring multiple trained models
• **Predictive entropy** — The entropy of the mean prediction distribution H[E[p(y|x,θ)]] captures both aleatoric and epistemic uncertainty; high predictive entropy triggers rejection as it indicates the model is uncertain about the correct class
• **Mutual information** — The difference between predictive entropy and expected data entropy (mutual information I[y;θ|x,D]) isolates epistemic uncertainty specifically, enabling rejection based on model ignorance rather than inherent class ambiguity
| Method | Uncertainty Source | OOD Detection | Computation Cost |
|--------|-------------------|---------------|-----------------|
| Softmax Confidence | Data only (poor) | Weak | 1× inference |
| Deep Ensemble Variance | Epistemic + Aleatoric | Strong | 5-10× inference |
| MC Dropout Variance | Approx. Epistemic | Good | 10-50× inference |
| Predictive Entropy | Both combined | Moderate | Method-dependent |
| Mutual Information | Pure Epistemic | Strong | Method-dependent |
| Evidential Uncertainty | Distributional | Good | 1× inference |
**Uncertainty-based rejection provides superior abstention decisions by leveraging principled uncertainty estimates that capture model ignorance, detecting unreliable predictions that overconfident softmax scores miss, and enabling robust deployment of AI systems in safety-critical environments where identifying what the model doesn't know is as important as what it does know.**
**Uncertainty Budget** is a **structured tabular analysis listing all sources of measurement uncertainty, their magnitudes, types, distributions, and contributions to the combined uncertainty** — the systematic documentation of every error source in a measurement process, organized to calculate the total uncertainty.
**Uncertainty Budget Structure**
- **Source**: Description of each uncertainty contributor (repeatability, calibration, temperature, resolution, etc.).
- **Type**: A (statistical) or B (other means) — classification per GUM.
- **Distribution**: Normal, rectangular, triangular, or other — determines divisor for standard uncertainty.
- **Standard Uncertainty**: Each source converted to a standard uncertainty ($u_i$) in the same units.
- **Sensitivity Coefficient**: How much the measurement result changes per unit change in each source ($c_i$).
**Why It Matters**
- **Transparency**: The budget makes all assumptions explicit — reviewable and auditable.
- **Improvement**: Identifies the dominant uncertainty contributors — focus improvement on the largest sources.
- **ISO 17025**: Accredited laboratories must maintain uncertainty budgets for all reported measurements.
**Uncertainty Budget** is **the blueprint of measurement doubt** — a comprehensive accounting of every uncertainty source for transparent, traceable, and improvable measurement results.
**Uncertainty Quantification (UQ)** is the systematic process of identifying, characterizing, and reducing the uncertainties in model predictions, encompassing both the estimation of prediction confidence intervals and the decomposition of total uncertainty into its constituent sources. In machine learning, UQ provides calibrated measures of how much a model's predictions should be trusted, distinguishing between uncertainty due to limited data (epistemic) and inherent randomness in the process (aleatoric).
**Why Uncertainty Quantification Matters in AI/ML:**
UQ is **essential for deploying AI systems in safety-critical applications** (medical diagnosis, autonomous driving, financial risk) where knowing when the model is uncertain is as important as the prediction itself, enabling informed decision-making under uncertainty.
• **Prediction intervals** — Beyond point predictions, UQ provides calibrated intervals (e.g., "95% confidence the value is between A and B") that communicate the range of plausible outcomes, enabling risk-aware decision-making
• **Epistemic vs. aleatoric decomposition** — Separating reducible uncertainty (epistemic: can be reduced with more data) from irreducible uncertainty (aleatoric: inherent noise) guides data collection strategy and sets realistic performance expectations
• **Out-of-distribution detection** — Models with well-calibrated uncertainty naturally flag OOD inputs with high epistemic uncertainty, providing a safety mechanism that alerts when the model is operating outside its training distribution
• **Active learning** — UQ guides data acquisition by identifying inputs where the model is most uncertain, prioritizing labeling effort where it will most improve the model, reducing total data requirements by 50-80%
• **Bayesian approaches** — Bayesian neural networks, MC Dropout, and deep ensembles provide principled UQ by maintaining distributions over predictions; ensemble disagreement directly measures epistemic uncertainty
| UQ Method | Uncertainty Type | Computational Cost | Calibration Quality |
|-----------|-----------------|-------------------|-------------------|
| Deep Ensembles | Epistemic + Aleatoric | 5-10× (multiple models) | Excellent |
| MC Dropout | Epistemic | 10-50× inference passes | Good |
| Bayesian NN | Both (principled) | 2-5× training | Theoretically optimal |
| Temperature Scaling | Calibration only | Negligible | Good (post-hoc) |
| Quantile Regression | Aleatoric | 1× (single model) | Good for intervals |
| Conformal Prediction | Coverage guarantee | 1× + calibration set | Guaranteed coverage |
**Uncertainty quantification transforms AI systems from black-box predictors into calibrated, trustworthy decision-support tools that communicate not just what they predict but how confident they are, enabling safe deployment in critical applications where understanding and managing prediction uncertainty is as important as prediction accuracy itself.**
**Uncertainty Quantification** is **the measurement of model confidence and uncertainty to estimate how reliable predictions are under varying conditions** - It is a core method in modern AI evaluation and safety execution workflows.
**What Is Uncertainty Quantification?**
- **Definition**: the measurement of model confidence and uncertainty to estimate how reliable predictions are under varying conditions.
- **Core Mechanism**: Methods separate confidence into meaningful components and expose when predictions should be trusted or escalated.
- **Operational Scope**: It is applied in AI safety, evaluation, and deployment-governance workflows to improve reliability, comparability, and decision confidence across model releases.
- **Failure Modes**: Without usable uncertainty signals, systems can make high-confidence mistakes in critical contexts.
**Why Uncertainty Quantification Matters**
- **Outcome Quality**: Better methods improve decision reliability, efficiency, and measurable impact.
- **Risk Management**: Structured controls reduce instability, bias loops, and hidden failure modes.
- **Operational Efficiency**: Well-calibrated methods lower rework and accelerate learning cycles.
- **Strategic Alignment**: Clear metrics connect technical actions to business and sustainability goals.
- **Scalable Deployment**: Robust approaches transfer effectively across domains and operating conditions.
**How It Is Used in Practice**
- **Method Selection**: Choose approaches by risk profile, implementation complexity, and measurable impact.
- **Calibration**: Calibrate uncertainty scores against real error rates and monitor reliability drift after deployment.
- **Validation**: Track objective metrics, compliance rates, and operational outcomes through recurring controlled reviews.
Uncertainty Quantification is **a high-impact method for resilient AI execution** - It is a core requirement for safe decision-making in high-stakes AI workflows.
**Under-Sampling Majority Class** is the **class imbalance technique that reduces the majority class by removing samples** — creating a balanced training set by discarding excess majority examples, trading off majority class information for balanced training.
**Under-Sampling Methods**
- **Random Under-Sampling**: Randomly remove majority samples — simple but loses information.
- **NearMiss**: Select majority samples close to minority decision boundaries — keep the informative ones.
- **Tomek Links**: Remove majority samples that form Tomek links (closest pairs of opposite classes) — clean decision boundary.
- **Cluster Centroids**: Cluster majority samples and keep only centroids — preserves distribution structure.
**Why It Matters**
- **Fast Training**: Smaller balanced dataset trains much faster than the full imbalanced dataset.
- **Information Loss**: The main drawback — discarding majority samples loses potentially useful information.
- **Complementary**: Often combined with over-sampling (SMOTE + Tomek Links) for better results.
**Under-Sampling** is **trimming the majority** — reducing dominant class samples to create a balanced training set at the cost of some information loss.
Advanced semiconductor packaging, 2.5D/3D heterogeneous integration, and direct copper-to-copper hybrid bonding constitute the post-Moore microelectronic integration disciplines that bridge the gap between monolithic die scaling and massive multi-terabyte computing bandwidth. As conventional transistor physical gate scaling encounters severe economic diminishing returns and maximum lithographic reticle field limits ($858\text{ mm}^2$), modern high-performance computing (HPC) processors, AI training accelerators, and graphics engines transition to modular multi-chiplet architectures. By decomposing monolithic system-on-chips into specialized functional chiplets—such as compute cores, high-bandwidth memory (HBM3e/HBM4) cubes, and analog input/output interface dies fabricated on disparate, optimal process technology nodes—heterogeneous packaging reconstructs single-package electrical performance. Achieving seamless chiplet interoperability requires integrating sub-micron redistribution layers (RDL), high-aspect-ratio Through-Silicon Vias (TSV), micro-bumps, capillary underfills (CUF), and bumpless dielectric-metal hybrid bonding, all while resolving severe coefficient of thermal expansion (CTE) mismatch warpage and extreme thermal dissipation flux.
**Silicon interposers and high-density redistribution layers establish ultra-wide parallel interconnect channels between multi-die chiplets.** In 2.5D Chip-on-Wafer-on-Substrate (CoWoS-S) integration, compute dies and high-bandwidth memory (HBM) stacks are assembled side-by-side atop a passive or active silicon interposer. Fabricated using dual damascene copper metallization, the interposer features sub-micron redistribution layer (RDL) metal lines (with linewidth and spacing $L/S \le 0.8\ \mu\text{m}$) and Through-Silicon Vias (TSVs) that route short, low-capacitance traces between adjacent dies. Compared to conventional printed circuit board (PCB) traces or organic package substrates, the fine-pitch silicon interconnect reduces line parasitics by more than an order of magnitude, enabling massive die-to-die (D2D) bus widths exceeding eight thousand parallel lanes while keeping interconnect transmission energy below $0.5\text{ pJ per bit}$.
**Through-Silicon Vias provide vertical electrical conduits across thinned silicon substrates for true three-dimensional stacking.** To construct 3D memory cubes (such as 12-high and 16-high HBM3e/HBM4 stacks) and 3D logic-on-logic architectures (such as Intel Foveros and TSMC SoIC), dice are thinned down to thicknesses of thirty to fifty micrometers and populated with vertical copper Through-Silicon Vias (TSVs). TSVs are manufactured via the via-middle flow: deep reactive ion etching (DRIE Bosch process alternating $\text{SF}_6$ plasma etching and $\text{C}_4\text{F}_8$ passivation steps) creates high-aspect-ratio ($10:1$) via cavities ($5\text{--}10\ \mu\text{m}$ diameter) in the silicon substrate; a PECVD $\text{SiO}_2$ dielectric liner and $\text{Ta}/\text{Cu}$ barrier-seed are deposited; and electrochemical copper superfilling fills the via core. Because the coefficient of thermal expansion of copper ($\alpha_{\text{Cu}} \approx 16.7\text{ ppm/K}$) is much larger than silicon ($\alpha_{\text{Si}} \approx 2.6\text{ ppm/K}$), thermal annealing induces copper pumping (vertical protrusion of the TSV core above the wafer surface) and intense localized radial compressive and tangential tensile stresses, which must be engineered through keep-out zones (KOZ) to prevent carrier mobility degradation in adjacent transistors.
| Packaging Architecture | Interconnect Pitch ($\mu\text{m}$) | Pad Density ($\text{pads/mm}^2$) | Energy Efficiency ($\text{pJ/bit}$) | Interconnect Bandwidth Density ($\text{TB/s/mm}$) | Assembly Mechanism | Dominant Reliability Failure Mode |
|---|---|---|---|---|---|---|
| Wire Bonding (Leadframe/BGA) | $35\text{--}80\ \mu\text{m}$ | $10\text{--}50$ | $5.0\text{--}15.0$ | $< 0.05$ | Ultrasonic thermosonic ball bonding | Wire sweep, intermetallic voiding, heel fracture |
| Flip-Chip BGA (C4 Solder Bumps) | $100\text{--}150\ \mu\text{m}$ | $50\text{--}100$ | $2.0\text{--}5.0$ | $0.1\text{--}0.3$ | Mass reflow ($\text{SAC305}$ solder) | Solder fatigue, underfill delamination |
| 2.5D Silicon Interposer (CoWoS) | $25\text{--}45\ \mu\text{m}$ (Micro-bump) | $500\text{--}1,600$ | $0.5\text{--}1.0$ | $1.0\text{--}3.0$ | Thermal compression bonding (TCB) | Micro-bump bridging, interposer warpage |
| Fan-Out Wafer-Level (InFO) | $15\text{--}30\ \mu\text{m}$ (RDL / Pillar) | $1,000\text{--}4,000$ | $0.3\text{--}0.8$ | $2.0\text{--}4.0$ | Substrate-less molded RDL assembly | Epoxy mold compound warpage, RDL trace cracking |
| 3D TSV Micro-Bump Stacking | $10\text{--}25\ \mu\text{m}$ | $1,600\text{--}10,000$ | $0.2\text{--}0.5$ | $3.0\text{--}6.0$ | TCB with non-conductive film (NCF) | Solder squeeze-out, TSV copper pumping stress |
| Direct Cu-Cu Hybrid Bonding | $< 1.0\ \mu\text{m}$ (Bumpless) | $> 1,000,000$ | $< 0.05$ | $> 10.0$ | Dielectric fusion $+ \text{Cu}$ diffusion | Interfacial voiding, nanometer overlay misalignment |
**Direct copper-to-copper hybrid bonding eliminates solder micro-bumps to achieve sub-micron interconnect pitches.** As interconnect pitches scale below ten micrometers, conventional solder micro-bumps suffer from molten solder bridging shorts and intermetallic compound ($\text{Cu}_6\text{Sn}_5, \text{Cu}_3\text{Sn}$) embrittlement. Bumpless direct Cu-Cu hybrid bonding (such as TSMC SoIC and Sony 3D image sensors) joins two planarized dielectric-metal surfaces in a two-stage process: first, surface chemical planarization via specialized CMP creates slightly recessed copper pads ($1\text{--}3\text{ nm}$) embedded in a dielectric field ($\text{SiO}_2$ or $\text{SiCN}$); next, plasma surface activation terminates the dielectric with hydrophilic silanol groups ($\text{Si-OH}$), enabling room-temperature spontaneous covalent wafer bonding ($\text{Si-OH} + \text{HO-Si} \to \text{Si-O-Si} + \text{H}_2\text{O}$). During subsequent batch thermal annealing at $200^\circ\text{C}\text{ to }300^\circ\text{C}$, the higher thermal expansion of copper closes the nanoscale pad recess, forcing intimate metal contact and driving copper grain boundary interdiffusion across the bonding seam. Hybrid bonding achieves interconnect contact densities exceeding one million pads per square millimeter with near-zero parasitic capacitance ($< 1\text{ fF/pad}$).
**Capillary underfill fluid dynamics and coefficient of thermal expansion mismatch dictate package thermomechanical longevity.** In micro-bump and flip-chip assemblies, the narrow gap between the chiplet and interposer ($10\text{--}25\ \mu\text{m}$) must be completely filled with a thermosetting epoxy underfill to encapsulate solder joints and redistribute thermal stresses. The underfill flow front penetration length ($L_{\text{flow}}$) over time ($t$) is governed by the Washburn capillary flow equation for flow between parallel plates separated by standoff height ($r_{\text{gap}}$):
$$
L_{\text{flow}}^2 = \left( \frac{\gamma_{\text{LV}} r_{\text{gap}} \cos\theta}{2 \eta} \right) t,
$$
where $\gamma_{\text{LV}}$ is the liquid underfill surface tension, $\theta$ is the contact wetting angle, and $\eta$ is the dynamic shear viscosity. Underfills are heavily filled with spherical silica nanoparticles ($60\%\text{--}75\%\text{ by weight}$) to lower the composite underfill CTE from $60\text{ ppm/K}$ down to $25\text{ ppm/K}$, matching the effective expansion rate of the assembly. Thermomechanical shear stress ($\sigma_{\text{CTE}} = E_{\text{eff}} \Delta\alpha \Delta T$) generated by the CTE mismatch between the silicon die ($\alpha_{\text{Si}} \approx 2.6\text{ ppm/K}$) and the organic package substrate ($\alpha_{\text{sub}} \approx 15\text{ ppm/K}$) drives solder joint cyclic fatigue, which is accurately modeled by the Coffin-Manson relationship:
$$
N_f = C \left( \Delta\epsilon_p \right)^{-m},
$$
where $N_f$ is the number of thermal cycles to failure and $\Delta\epsilon_p$ is the plastic shear strain range per thermal cycle (tested under JEDEC $-40^\circ\text{C}\text{ to }+125^\circ\text{C}$ temperature cycling).
```flowchart
st=>start: Known Good Die (KGD) Wafer: logic chiplets & HBM memory cubes verified at wafer sort
wafer_thinning=>operation: Backside Grinding & CMP Thinning: thin silicon substrate to 30-50 um & reveal TSVs
surface_prep=>operation: Dual-Inlaid Cu/Dielectric CMP: create 1-3nm Cu pad recess & activate surface with N2/O2 plasma
hybrid_bonding=>operation: High-Precision Direct Hybrid Bonding: room-temp fusion followed by 250°C Cu interdiffusion
interposer_attach=>operation: 2.5D CoWoS Assembly: attach chiplet cluster onto silicon interposer via TCB / CUF dispense
lid_tim_attach=>operation: Package Integration: apply high-conductivity TIM2 & attach stiffener ring and copper lid
pass=>end: Advanced Package Certified: > 10^6 pads/mm2 with JEDEC TC-G thermal cycle reliability
st->wafer_thinning->surface_prep->hybrid_bonding->interposer_attach->lid_tim_attach->pass
```
**Delivering exascale computing throughput and multi-terabyte memory bandwidth across heterogeneous multi-chiplet processors requires evaluating electronic systems through an advanced-packaging-heterogeneous-integration-and-hybrid-bonding lens.** By uniting 2.5D sub-micron silicon interposer routing, 3D high-aspect-ratio Through-Silicon Vias, bumpless direct Cu-Cu hybrid bonding, Washburn capillary underfill rheology, and Coffin-Manson thermomechanical fatigue modeling, packaging architecture teams transcend monolithic silicon scaling barriers. Mastering advanced packaging physics guarantees that modular artificial intelligence supercomputers, high-performance data center processors, and 3D stacked memory cubes operate with maximum energy efficiency, signal integrity, and multi-year structural reliability.
capillary underfill, molded underfill, no flow underfill, flip chip epoxy
Advanced semiconductor packaging, 2.5D/3D heterogeneous integration, and direct copper-to-copper hybrid bonding constitute the post-Moore microelectronic integration disciplines that bridge the gap between monolithic die scaling and massive multi-terabyte computing bandwidth. As conventional transistor physical gate scaling encounters severe economic diminishing returns and maximum lithographic reticle field limits ($858\text{ mm}^2$), modern high-performance computing (HPC) processors, AI training accelerators, and graphics engines transition to modular multi-chiplet architectures. By decomposing monolithic system-on-chips into specialized functional chiplets—such as compute cores, high-bandwidth memory (HBM3e/HBM4) cubes, and analog input/output interface dies fabricated on disparate, optimal process technology nodes—heterogeneous packaging reconstructs single-package electrical performance. Achieving seamless chiplet interoperability requires integrating sub-micron redistribution layers (RDL), high-aspect-ratio Through-Silicon Vias (TSV), micro-bumps, capillary underfills (CUF), and bumpless dielectric-metal hybrid bonding, all while resolving severe coefficient of thermal expansion (CTE) mismatch warpage and extreme thermal dissipation flux.
**Silicon interposers and high-density redistribution layers establish ultra-wide parallel interconnect channels between multi-die chiplets.** In 2.5D Chip-on-Wafer-on-Substrate (CoWoS-S) integration, compute dies and high-bandwidth memory (HBM) stacks are assembled side-by-side atop a passive or active silicon interposer. Fabricated using dual damascene copper metallization, the interposer features sub-micron redistribution layer (RDL) metal lines (with linewidth and spacing $L/S \le 0.8\ \mu\text{m}$) and Through-Silicon Vias (TSVs) that route short, low-capacitance traces between adjacent dies. Compared to conventional printed circuit board (PCB) traces or organic package substrates, the fine-pitch silicon interconnect reduces line parasitics by more than an order of magnitude, enabling massive die-to-die (D2D) bus widths exceeding eight thousand parallel lanes while keeping interconnect transmission energy below $0.5\text{ pJ per bit}$.
**Through-Silicon Vias provide vertical electrical conduits across thinned silicon substrates for true three-dimensional stacking.** To construct 3D memory cubes (such as 12-high and 16-high HBM3e/HBM4 stacks) and 3D logic-on-logic architectures (such as Intel Foveros and TSMC SoIC), dice are thinned down to thicknesses of thirty to fifty micrometers and populated with vertical copper Through-Silicon Vias (TSVs). TSVs are manufactured via the via-middle flow: deep reactive ion etching (DRIE Bosch process alternating $\text{SF}_6$ plasma etching and $\text{C}_4\text{F}_8$ passivation steps) creates high-aspect-ratio ($10:1$) via cavities ($5\text{--}10\ \mu\text{m}$ diameter) in the silicon substrate; a PECVD $\text{SiO}_2$ dielectric liner and $\text{Ta}/\text{Cu}$ barrier-seed are deposited; and electrochemical copper superfilling fills the via core. Because the coefficient of thermal expansion of copper ($\alpha_{\text{Cu}} \approx 16.7\text{ ppm/K}$) is much larger than silicon ($\alpha_{\text{Si}} \approx 2.6\text{ ppm/K}$), thermal annealing induces copper pumping (vertical protrusion of the TSV core above the wafer surface) and intense localized radial compressive and tangential tensile stresses, which must be engineered through keep-out zones (KOZ) to prevent carrier mobility degradation in adjacent transistors.
| Packaging Architecture | Interconnect Pitch ($\mu\text{m}$) | Pad Density ($\text{pads/mm}^2$) | Energy Efficiency ($\text{pJ/bit}$) | Interconnect Bandwidth Density ($\text{TB/s/mm}$) | Assembly Mechanism | Dominant Reliability Failure Mode |
|---|---|---|---|---|---|---|
| Wire Bonding (Leadframe/BGA) | $35\text{--}80\ \mu\text{m}$ | $10\text{--}50$ | $5.0\text{--}15.0$ | $< 0.05$ | Ultrasonic thermosonic ball bonding | Wire sweep, intermetallic voiding, heel fracture |
| Flip-Chip BGA (C4 Solder Bumps) | $100\text{--}150\ \mu\text{m}$ | $50\text{--}100$ | $2.0\text{--}5.0$ | $0.1\text{--}0.3$ | Mass reflow ($\text{SAC305}$ solder) | Solder fatigue, underfill delamination |
| 2.5D Silicon Interposer (CoWoS) | $25\text{--}45\ \mu\text{m}$ (Micro-bump) | $500\text{--}1,600$ | $0.5\text{--}1.0$ | $1.0\text{--}3.0$ | Thermal compression bonding (TCB) | Micro-bump bridging, interposer warpage |
| Fan-Out Wafer-Level (InFO) | $15\text{--}30\ \mu\text{m}$ (RDL / Pillar) | $1,000\text{--}4,000$ | $0.3\text{--}0.8$ | $2.0\text{--}4.0$ | Substrate-less molded RDL assembly | Epoxy mold compound warpage, RDL trace cracking |
| 3D TSV Micro-Bump Stacking | $10\text{--}25\ \mu\text{m}$ | $1,600\text{--}10,000$ | $0.2\text{--}0.5$ | $3.0\text{--}6.0$ | TCB with non-conductive film (NCF) | Solder squeeze-out, TSV copper pumping stress |
| Direct Cu-Cu Hybrid Bonding | $< 1.0\ \mu\text{m}$ (Bumpless) | $> 1,000,000$ | $< 0.05$ | $> 10.0$ | Dielectric fusion $+ \text{Cu}$ diffusion | Interfacial voiding, nanometer overlay misalignment |
**Direct copper-to-copper hybrid bonding eliminates solder micro-bumps to achieve sub-micron interconnect pitches.** As interconnect pitches scale below ten micrometers, conventional solder micro-bumps suffer from molten solder bridging shorts and intermetallic compound ($\text{Cu}_6\text{Sn}_5, \text{Cu}_3\text{Sn}$) embrittlement. Bumpless direct Cu-Cu hybrid bonding (such as TSMC SoIC and Sony 3D image sensors) joins two planarized dielectric-metal surfaces in a two-stage process: first, surface chemical planarization via specialized CMP creates slightly recessed copper pads ($1\text{--}3\text{ nm}$) embedded in a dielectric field ($\text{SiO}_2$ or $\text{SiCN}$); next, plasma surface activation terminates the dielectric with hydrophilic silanol groups ($\text{Si-OH}$), enabling room-temperature spontaneous covalent wafer bonding ($\text{Si-OH} + \text{HO-Si} \to \text{Si-O-Si} + \text{H}_2\text{O}$). During subsequent batch thermal annealing at $200^\circ\text{C}\text{ to }300^\circ\text{C}$, the higher thermal expansion of copper closes the nanoscale pad recess, forcing intimate metal contact and driving copper grain boundary interdiffusion across the bonding seam. Hybrid bonding achieves interconnect contact densities exceeding one million pads per square millimeter with near-zero parasitic capacitance ($< 1\text{ fF/pad}$).
**Capillary underfill fluid dynamics and coefficient of thermal expansion mismatch dictate package thermomechanical longevity.** In micro-bump and flip-chip assemblies, the narrow gap between the chiplet and interposer ($10\text{--}25\ \mu\text{m}$) must be completely filled with a thermosetting epoxy underfill to encapsulate solder joints and redistribute thermal stresses. The underfill flow front penetration length ($L_{\text{flow}}$) over time ($t$) is governed by the Washburn capillary flow equation for flow between parallel plates separated by standoff height ($r_{\text{gap}}$):
$$
L_{\text{flow}}^2 = \left( \frac{\gamma_{\text{LV}} r_{\text{gap}} \cos\theta}{2 \eta} \right) t,
$$
where $\gamma_{\text{LV}}$ is the liquid underfill surface tension, $\theta$ is the contact wetting angle, and $\eta$ is the dynamic shear viscosity. Underfills are heavily filled with spherical silica nanoparticles ($60\%\text{--}75\%\text{ by weight}$) to lower the composite underfill CTE from $60\text{ ppm/K}$ down to $25\text{ ppm/K}$, matching the effective expansion rate of the assembly. Thermomechanical shear stress ($\sigma_{\text{CTE}} = E_{\text{eff}} \Delta\alpha \Delta T$) generated by the CTE mismatch between the silicon die ($\alpha_{\text{Si}} \approx 2.6\text{ ppm/K}$) and the organic package substrate ($\alpha_{\text{sub}} \approx 15\text{ ppm/K}$) drives solder joint cyclic fatigue, which is accurately modeled by the Coffin-Manson relationship:
$$
N_f = C \left( \Delta\epsilon_p \right)^{-m},
$$
where $N_f$ is the number of thermal cycles to failure and $\Delta\epsilon_p$ is the plastic shear strain range per thermal cycle (tested under JEDEC $-40^\circ\text{C}\text{ to }+125^\circ\text{C}$ temperature cycling).
```flowchart
st=>start: Known Good Die (KGD) Wafer: logic chiplets & HBM memory cubes verified at wafer sort
wafer_thinning=>operation: Backside Grinding & CMP Thinning: thin silicon substrate to 30-50 um & reveal TSVs
surface_prep=>operation: Dual-Inlaid Cu/Dielectric CMP: create 1-3nm Cu pad recess & activate surface with N2/O2 plasma
hybrid_bonding=>operation: High-Precision Direct Hybrid Bonding: room-temp fusion followed by 250°C Cu interdiffusion
interposer_attach=>operation: 2.5D CoWoS Assembly: attach chiplet cluster onto silicon interposer via TCB / CUF dispense
lid_tim_attach=>operation: Package Integration: apply high-conductivity TIM2 & attach stiffener ring and copper lid
pass=>end: Advanced Package Certified: > 10^6 pads/mm2 with JEDEC TC-G thermal cycle reliability
st->wafer_thinning->surface_prep->hybrid_bonding->interposer_attach->lid_tim_attach->pass
```
**Delivering exascale computing throughput and multi-terabyte memory bandwidth across heterogeneous multi-chiplet processors requires evaluating electronic systems through an advanced-packaging-heterogeneous-integration-and-hybrid-bonding lens.** By uniting 2.5D sub-micron silicon interposer routing, 3D high-aspect-ratio Through-Silicon Vias, bumpless direct Cu-Cu hybrid bonding, Washburn capillary underfill rheology, and Coffin-Manson thermomechanical fatigue modeling, packaging architecture teams transcend monolithic silicon scaling barriers. Mastering advanced packaging physics guarantees that modular artificial intelligence supercomputers, high-performance data center processors, and 3D stacked memory cubes operate with maximum energy efficiency, signal integrity, and multi-year structural reliability.
**Underfill filler** is the **solid particulate component added to underfill resin to tune CTE, modulus, flow behavior, and thermal properties** - filler selection strongly influences package stress and reliability.
**What Is Underfill filler?**
- **Definition**: Micron-scale inorganic particles dispersed in resin matrix within underfill materials.
- **Primary Functions**: Adjust thermal expansion, stiffness, viscosity, and thermal conductivity.
- **Common Types**: Silica and other engineered fillers selected by size, shape, and surface treatment.
- **Process Interaction**: Filler loading changes capillary flow and void propensity during dispense.
**Why Underfill filler Matters**
- **CTE Engineering**: Proper filler content helps match package and substrate expansion behavior.
- **Stress Control**: Mechanical response of cured underfill depends strongly on filler system.
- **Flow Performance**: Particle characteristics affect fill speed and gap-penetration reliability.
- **Thermal Behavior**: Filler composition influences heat transport and cure shrinkage effects.
- **Defect Risk**: Poor dispersion or oversized particles can induce clogging and voids.
**How It Is Used in Practice**
- **Formulation Tuning**: Balance filler loading against flowability and target mechanical properties.
- **Dispersion Control**: Use robust mixing and filtration to maintain uniform particle distribution.
- **Reliability Correlation**: Map filler formulations to thermal-cycle life and warpage outcomes.
Underfill filler is **a key material-engineering lever in underfill design** - filler optimization is essential for both processability and interconnect durability.
**Underfill** is a **highly engineered, profoundly critical composite silica-epoxy glue utilized universally in advanced flip-chip packaging specifically designed to absorb, distribute, and neutralize the violent mechanical stresses tearing an assembled processor apart caused fundamentally by Coefficient of Thermal Expansion (CTE) mismatches.**
**The Thermodynamic Battleground**
- **The Flip-Chip Dilemma**: A bare silicon die is flipped completely upside down and soldered directly onto an organic green motherboard substrate using hundreds of microscopic lead-solder balls (bumps).
- **The CTE Nightmare**: Silicon is a rigid crystal. It barely expands when heated ($CTE approx 2.6 ext{ ppm}/^{circ} ext{C}$). The organic motherboard is a cheap plastic-like resin. It violently expands and stretches in all directions when heated ($CTE approx 15 ext{ ppm}/^{circ} ext{C}$).
- **The Shearing Severance**: When the server powers on and the chip reaches $80^{circ}C$, the motherboard aggressively stretches outward beneath the silicon, causing a massive shear force directly on the tiny solder bumps connecting them. Without intervention, the constant power-cycling of the computer will literally crack and rip the solder balls in half (fatigue failure), completely destroying the billion-dollar chip within weeks.
**The Mechanical Buffer**
- **The Capillary Flow**: To save the chip, engineers utilize capillary action to suck a highly specialized liquid epoxy (Underfill) into the microscopic $50 mu m$ gap beneath the flipped die, completely encasing the delicate solder bumps in a solid block of hardened plastic.
- **The Silica Armor**: This epoxy is heavily doped with microscopic silica spheres, rigidly tuning the overall expansion rate of the glue (CTE) to be exactly halfway between the rigid Silicon and the stretchy motherboard.
- **The Distribution of Stress**: Instead of the violent stretching force being concentrated in a microscopic crack on a single fragile solder ball, the solid Underfill locks the structures together. It evenly distributes the shear stress across the incredibly massive, solid surface area of the entire bottom of the die.
**Underfill for CTE Matching** is **mechanical stress armor** — a localized, atomic shock absorber engineered to prevent a silicon mind from physically tearing itself apart from its plastic body every time it gets hot.
advanced packaging, microbump underfill, tsv 3d stacking
Through-Silicon Vias are the vertical conductive interconnect pillars that traverse the bulk silicon substrate to establish high-density, low-latency electrical connections between stacked dies in 2.5D and 3D heterogeneous packaging architectures. From multi-layer High-Bandwidth Memory DRAM cubes and silicon interposers to backside power delivery networks, TSVs provide the massive interconnect density and short interconnect lengths required to overcome the memory wall and wire delay bottlenecks of planar integrated circuits. Fabricated through deep reactive ion etching using the time-multiplexed Bosch process, conformal dielectric isolation lining, barrier-seed metallization, and bottom-up copper electroplating, TSVs must satisfy rigorous aspect ratio, thermomechanical stress, and keep-out zone design rules to guarantee robust multi-die reliability.
**The time-multiplexed Bosch deep reactive ion etching process achieves high-aspect-ratio vertical silicon profiles.** In manufacturing Through-Silicon Vias, conventional continuous plasma etching cannot maintain anisotropic vertical profiles across depths exceeding $50\ \mu\text{m}$. The Bosch DRIE process resolves this by cycling repeatedly through chemical etching (where $\text{SF}_6$ plasma generates fluorine radicals to spontaneously etch silicon), passivation deposition (where $\text{C}_4\text{F}_8$ deposits a protective fluorocarbon polymer layer on sidewalls), and directional polymer clearing (where energetic ions selectively depolymerize the trench floor while leaving vertical sidewalls protected). By pulsing cycles within sub-second intervals ($0.5\text{--}2.0\text{ s}$), modern DRIE tools achieve silicon etch rates exceeding $10\ \mu\text{m/min}$ with sidewall scalloping depths controlled below $50\text{ nm}$.
**Bottom-up electrochemical superfilling eliminates seam and pinch-off voids in deep vias.** Following Bosch DRIE, a dielectric isolation liner (typically $200\text{ nm}$ PECVD/SACVD $\text{SiO}_2$) and a diffusion barrier/seed stack (PVD or ALD $\text{TaN/Ta}$ barrier followed by a copper seed layer) are deposited. To fill the high-aspect-ratio via ($AR > 10:1$) with copper without trapping centerline voids, the electroplating bath utilizes a three-component organic additive system comprising suppressors (such as PEG that retard top opening plating), accelerators (such as SPS that concentrate at the bottom to drive fast upward growth), and levelers that suppress nodular overgrowth at via corners.
**Thermomechanical stress from coefficient of thermal expansion mismatch establishes the Keep-Out Zone.** Copper has a high thermal expansion coefficient ($\alpha_{\text{Cu}} \approx 16.7\times 10^{-6}\text{/K}$) compared to the surrounding silicon substrate ($\alpha_{\text{Si}} \approx 2.6\times 10^{-6}\text{/K}$). When cooling from high-temperature copper annealing ($350^\circ\text{C}\text{--}400^\circ\text{C}$), the copper via contracts significantly faster than the silicon matrix, generating severe radial tensile stresses ($\sigma_r$) and tangential compressive hoop stresses ($\sigma_\theta$):
$$
\sigma_r(r) = -\sigma_\theta(r) = - \frac{E_{\text{Si}} \cdot \Delta\alpha \cdot \Delta T}{1 + \mu_{\text{Poisson}}} \left( \frac{R_{\text{TSV}}}{r} \right)^2.
$$
These localized stress fields alter the silicon band structure via piezoresistive coupling, shifting transistor carrier mobility ($\Delta\mu_p / \mu_p > 15\%$, $\Delta\mu_n / \mu_n > 8\%$) and threshold voltages. Consequently, physical design rules enforce a Keep-Out Zone ($\text{KOZ} \approx 3\text{--}5\ \mu\text{m}$ radius around each TSV) where no active transistors or analog circuits may be placed.
**Backside wafer thinning and TSV reveal enable vertical 3D interconnection.** After front-end and middle-end metallization, the active wafer is temporarily bonded face-down to a rigid glass or silicon carrier wafer using a polymeric adhesive. Mechanical coarse and fine backgrinding thins the bulk silicon substrate from $775\ \mu\text{m}$ down to $50\ \mu\text{m}$ or less. A subsequent selective chemical dry etch or CMP step etches back the remaining silicon to reveal the copper TSV tips (the "TSV Reveal" process). A backside passivating dielectric ($\text{SiN} / \text{SiO}_2$) is deposited and polished via CMP to expose the planar copper TSV pads, followed by backside redistribution layer (RDL) formation and microbump attachment.
| TSV Integration Architecture | Insertion Point | Typical Dimensions ($D \times H$) | Aspect Ratio (AR) | Primary Metallization | Primary Semiconductor Application |
|---|---|---|---|---|---|
| Via-First (FEOL) | Prior to active transistor formation | $1\text{--}3\ \mu\text{m} \times 15\text{--}30\ \mu\text{m}$ | $10:1\text{--}15:1$ | Doped Polysilicon / W | Specialized CMOS image sensors |
| Via-Middle (Post-FEOL) | After transistor contact, before BEOL | $3\text{--}10\ \mu\text{m} \times 40\text{--}80\ \mu\text{m}$ | $8:1\text{--}12:1$ | Electroplated Copper (Cu) | HBM DRAM stacks & 2.5D/3D interposers |
| Via-Last (Backside Packaging) | After completed BEOL wafer fabrication | $10\text{--}25\ \mu\text{m} \times 50\text{--}150\ \mu\text{m}$ | $4:1\text{--}6:1$ | Conformal Cu or W liner | Wafer-level chip-scale packaging & MEMS |
| High-Bandwidth Memory (HBM) | Dense vertical 8/12/16-die stacking | $4\text{--}6\ \mu\text{m} \times 30\text{--}50\ \mu\text{m}$ | $\approx 8:1$ | Fine-pitch Cu with microbumps | HBM3E / HBM4 memory bandwidth scaling |
| Backside Power Nano-TSVs | Backside Power Delivery Network | $0.05\text{--}0.2\ \mu\text{m} \times 0.2\text{--}0.5\ \mu\text{m}$ | $2:1\text{--}4:1$ | Refractory Ruthenium / W | Sub-2nm BSPDN logic (PowerVia / A16) |
**Copper pumping protrusion presents critical reliability challenges during thermal packaging cycles.** Because copper possesses a much higher thermal expansion rate than silicon, elevated thermal cycles during flip-chip reflow or underfill curing ($200^\circ\text{C}\text{--}260^\circ\text{C}$) cause copper via cores to expand vertically and permanently protrude from the wafer surface (known as "copper pumping"). This irreversible out-of-plane plastic deformation can delaminate overlying low-k dielectric layers, crack inter-metal dielectric capping films, and produce catastrophic short-circuits. Foundries mitigate copper pumping by incorporating pre-CMP high-temperature thermal stabilization anneals ($400^\circ\text{C}$) to drive grain growth and relieve residual plating stresses before final planarization.
```flowchart
st=>start: Complete active CMOS transistors; apply photoresist mask for TSV locations
drie_etch=>operation: Bosch DRIE etching (SF6/C4F8 multiplexed cycles) etches deep via (AR > 10:1)
liner_dep=>operation: Deposit conformal PECVD SiO2 isolation liner + ALD TaN barrier / Cu seed layer
superfill_cu=>operation: Bottom-up electroplating fills via with void-free copper using PEG/SPS additives
cmp_overburden=>operation: Chemical mechanical planarization (CMP) removes overburden copper and barrier
back_thin=>operation: Temporary carrier wafer bonding + mechanical backgrinding thins wafer to ~50um
tsv_reveal=>operation: Backside silicon etch-back + CMP reveals copper TSV tips for backside interconnects
pass=>end: Fully formed, low-stress TSVs ready for multi-die microbump or hybrid bonding assembly
st->drie_etch->liner_dep->superfill_cu->cmp_overburden->back_thin->tsv_reveal->pass
```
**Overcoming planar interconnect bottlenecks in 3D multi-die systems requires evaluating vertical connections through a bosch-drie-aspect-ratio-superfill-and-thermo-mechanical-koz lens.** By harmonizing time-multiplexed plasma chemistry, bottom-up superfilling electrokinetics, thermomechanical stress field mitigation, and wafer-level thinning reveal mechanics, semiconductor manufacturers construct dense vertical interconnect matrices. Mastering TSV manufacturing ensures that High-Bandwidth Memory cubes, massive 2.5D interposers, and advanced backside power delivery networks deliver extreme bandwidth, minimal parasitics, and multi-year structural reliability across advanced heterogeneous computing systems.
**Underfill process** is the **assembly step that dispenses and cures polymer material between flip-chip die and substrate to reinforce solder joints and redistribute stress** - it is a core reliability technique for area-array interconnects.
**What Is Underfill process?**
- **Definition**: Flow of liquid encapsulant into die-substrate gap followed by thermal cure to form supportive matrix.
- **Mechanical Function**: Transfers and spreads thermo-mechanical strain away from solder bumps.
- **Process Inputs**: Depends on gap size, bump pitch, viscosity, dispense pattern, and cure profile.
- **Variant Forms**: Includes capillary underfill, no-flow underfill, and molded underfill options.
**Why Underfill process Matters**
- **Fatigue Reliability**: Underfill greatly extends solder-joint life under thermal cycling.
- **Shock Robustness**: Improves drop and vibration tolerance in portable applications.
- **Warpage Resilience**: Helps stabilize interconnects under package and board deformation.
- **Yield Dependence**: Voids and incomplete fill can create critical weak points.
- **Product Qualification**: Underfill quality is often a gating factor for reliability release.
**How It Is Used in Practice**
- **Dispense Optimization**: Tune flow path, needle strategy, and temperature for complete gap fill.
- **Void Control**: Use pre-bake, cleanliness controls, and process timing to minimize trapped gas.
- **Cure Validation**: Qualify cure schedule for adhesion, modulus, and CTE performance targets.
Underfill process is **a reliability-critical module in flip-chip package assembly** - underfill quality directly determines mechanical durability of solder interconnects.
**Underfill voids** is the **gas-filled defects trapped within cured underfill regions that disrupt stress transfer and can reduce joint reliability** - void control is a major quality objective in underfill processing.
**What Is Underfill voids?**
- **Definition**: Entrapped bubbles or unfilled pockets inside under-die encapsulant after cure.
- **Typical Origins**: Outgassing, poor wetting, contamination, and incomplete capillary flow.
- **Location Sensitivity**: Voids near corner bumps and high-stress zones are most reliability-critical.
- **Detection Methods**: X-ray, acoustic microscopy, and cross-section analysis identify void distribution.
**Why Underfill voids Matters**
- **Stress Concentration**: Voids create local mechanical discontinuities that accelerate crack initiation.
- **Fatigue Reduction**: Underfill support becomes non-uniform, shortening solder-joint life.
- **Yield Impact**: High void populations increase reliability screening failures.
- **Process Signal**: Void trends indicate dispense, cleanliness, or cure-window problems.
- **Customer Quality**: Void criteria are common acceptance limits in package qualification specs.
**How It Is Used in Practice**
- **Pre-Conditioning**: Control moisture and bake components to reduce outgassing sources.
- **Dispense Optimization**: Tune flow path, temperature, and speed for complete wetting and venting.
- **Inspection Gates**: Implement void-map thresholds with lot hold criteria and corrective action loops.
Underfill voids is **a high-priority defect mode in flip-chip reinforcement processes** - void suppression is essential for stable thermo-mechanical reliability.