windows python step 86, python setup step 86 windows
**Windows Python Setup Step 86 is Concurrency safety: produce a explicit shared-state ownership that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **races are prevented and duplicate requests remain safe**. The main failure to design against is **assuming the GIL makes compound operations atomic**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Concurrency safety behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 86 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 86 boundary
The deliverable is **explicit shared-state ownership**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Concurrency safety. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Concurrency safety"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Concurrency safety policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 86 exercise command is:
```powershell
python -m pytest tests\test_concurrency.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 86 threat review must directly address **assuming the GIL makes compound operations atomic**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Concurrency safety. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 86
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 86 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | explicit shared-state ownership exists in reviewed source | machine-only hidden state |
| normal behavior | races are prevented and duplicate requests remain safe | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses assuming the GIL makes compound operations atomic | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 86 completion gate
Step 86 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_concurrency.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 87 continues with **Performance tuning**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 86 succeeds when races are prevented and duplicate requests remain safe, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 87, python setup step 87 windows
**Windows Python Setup Step 87 is Performance tuning: produce a measured end-to-end optimization that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **a representative baseline improves without correctness regressions**. The main failure to design against is **micro-optimizing the wrong bottleneck**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Performance tuning behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 87 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 87 boundary
The deliverable is **measured end-to-end optimization**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Performance tuning. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Performance tuning"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Performance tuning policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 87 exercise command is:
```powershell
python -m pytest tests\test_performance_budget.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 87 threat review must directly address **micro-optimizing the wrong bottleneck**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Performance tuning. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 87
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 87 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | measured end-to-end optimization exists in reviewed source | machine-only hidden state |
| normal behavior | a representative baseline improves without correctness regressions | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses micro-optimizing the wrong bottleneck | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 87 completion gate
Step 87 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_performance_budget.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 88 continues with **Internationalization**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 87 succeeds when a representative baseline improves without correctness regressions, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 88, python setup step 88 windows
**Windows Python Setup Step 88 is Internationalization: produce a Unicode-safe locale-aware message boundary that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **multiple locales, fallback, formatting, and missing translations pass**. The main failure to design against is **using locale-sensitive data formats for machine interfaces**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Internationalization behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 88 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 88 boundary
The deliverable is **Unicode-safe locale-aware message boundary**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Internationalization. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Internationalization"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Internationalization policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 88 exercise command is:
```powershell
python -m pytest tests\test_i18n.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 88 threat review must directly address **using locale-sensitive data formats for machine interfaces**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Internationalization. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 88
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 88 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | Unicode-safe locale-aware message boundary exists in reviewed source | machine-only hidden state |
| normal behavior | multiple locales, fallback, formatting, and missing translations pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses using locale-sensitive data formats for machine interfaces | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 88 completion gate
Step 88 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_i18n.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 89 continues with **Time zones**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 88 succeeds when multiple locales, fallback, formatting, and missing translations pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 89, python setup step 89 windows
**Windows Python Setup Step 89 is Time zones: produce a timezone-aware scheduling and storage that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **UTC storage and daylight-saving edge cases are deterministic**. The main failure to design against is **naive datetimes and ambiguous local times**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Time zones behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 89 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 89 boundary
The deliverable is **timezone-aware scheduling and storage**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Time zones. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Time zones"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Time zones policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 89 exercise command is:
```powershell
python -m pytest tests\test_timezones.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 89 threat review must directly address **naive datetimes and ambiguous local times**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Time zones. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 89
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 89 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | timezone-aware scheduling and storage exists in reviewed source | machine-only hidden state |
| normal behavior | UTC storage and daylight-saving edge cases are deterministic | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses naive datetimes and ambiguous local times | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 89 completion gate
Step 89 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_timezones.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 90 continues with **Excel automation**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 89 succeeds when UTC storage and daylight-saving edge cases are deterministic, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 9, python setup step 9 windows
**Windows Python Setup Step 9 is CI artifacts and retention: produce a small non-sensitive diagnostic artifact that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **a failed and a successful run expose useful bounded evidence**. The main failure to design against is **publishing credentials, user paths, or oversized caches**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | CI artifacts and retention behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 9 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 9 boundary
The deliverable is **small non-sensitive diagnostic artifact**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns CI artifacts and retention. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "CI artifacts and retention"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the CI artifacts and retention policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 9 exercise command is:
```powershell
python -m pytest --junitxml=test-results.xml
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 9 threat review must directly address **publishing credentials, user paths, or oversized caches**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to CI artifacts and retention. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 9
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 9 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | small non-sensitive diagnostic artifact exists in reviewed source | machine-only hidden state |
| normal behavior | a failed and a successful run expose useful bounded evidence | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses publishing credentials, user paths, or oversized caches | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 9 completion gate
Step 9 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest --junitxml=test-results.xml
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 10 continues with **Automated dependency updates**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 9 succeeds when a failed and a successful run expose useful bounded evidence, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 90, python setup step 90 windows
**Windows Python Setup Step 90 is Excel automation: produce a bounded workbook import-export adapter that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **types, formulas, dates, missing cells, and file locks are handled**. The main failure to design against is **executing untrusted macros or overwriting source workbooks**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Excel automation behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 90 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 90 boundary
The deliverable is **bounded workbook import-export adapter**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Excel automation. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Excel automation"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Excel automation policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 90 exercise command is:
```powershell
python -m pytest tests\test_workbooks.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 90 threat review must directly address **executing untrusted macros or overwriting source workbooks**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Excel automation. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 90
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 90 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | bounded workbook import-export adapter exists in reviewed source | machine-only hidden state |
| normal behavior | types, formulas, dates, missing cells, and file locks are handled | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses executing untrusted macros or overwriting source workbooks | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 90 completion gate
Step 90 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_workbooks.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 91 continues with **Windows COM automation**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 90 succeeds when types, formulas, dates, missing cells, and file locks are handled, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 91, python setup step 91 windows
**Windows Python Setup Step 91 is Windows COM automation: produce a isolated Office COM adapter that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **apartment setup, cleanup, timeouts, and absent Office behavior are controlled**. The main failure to design against is **orphan Office processes and interactive prompts**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Windows COM automation behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 91 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 91 boundary
The deliverable is **isolated Office COM adapter**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Windows COM automation. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Windows COM automation"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Windows COM automation policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 91 exercise command is:
```powershell
python -m pytest tests\test_com_adapter.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 91 threat review must directly address **orphan Office processes and interactive prompts**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Windows COM automation. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 91
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 91 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | isolated Office COM adapter exists in reviewed source | machine-only hidden state |
| normal behavior | apartment setup, cleanup, timeouts, and absent Office behavior are controlled | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses orphan Office processes and interactive prompts | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 91 completion gate
Step 91 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_com_adapter.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 92 continues with **Network shares**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 91 succeeds when apartment setup, cleanup, timeouts, and absent Office behavior are controlled, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 92, python setup step 92 windows
**Windows Python Setup Step 92 is Network shares: produce a resilient UNC-path data access that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **disconnects, permissions, atomicity, and retries are bounded**. The main failure to design against is **assuming mapped drive letters exist in services**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Network shares behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 92 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 92 boundary
The deliverable is **resilient UNC-path data access**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Network shares. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Network shares"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Network shares policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 92 exercise command is:
```powershell
python -m pytest tests\test_network_storage.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 92 threat review must directly address **assuming mapped drive letters exist in services**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Network shares. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 92
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 92 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | resilient UNC-path data access exists in reviewed source | machine-only hidden state |
| normal behavior | disconnects, permissions, atomicity, and retries are bounded | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses assuming mapped drive letters exist in services | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 92 completion gate
Step 92 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_network_storage.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 93 continues with **Corporate proxies**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 92 succeeds when disconnects, permissions, atomicity, and retries are bounded, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 93, python setup step 93 windows
**Windows Python Setup Step 93 is Corporate proxies: produce a explicit HTTP proxy configuration that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **approved proxy, bypass, authentication, and redaction cases pass**. The main failure to design against is **disabling verification or logging proxy credentials**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Corporate proxies behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 93 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 93 boundary
The deliverable is **explicit HTTP proxy configuration**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Corporate proxies. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Corporate proxies"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Corporate proxies policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 93 exercise command is:
```powershell
python -m pytest tests\test_proxy_config.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 93 threat review must directly address **disabling verification or logging proxy credentials**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Corporate proxies. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 93
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 93 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | explicit HTTP proxy configuration exists in reviewed source | machine-only hidden state |
| normal behavior | approved proxy, bypass, authentication, and redaction cases pass | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses disabling verification or logging proxy credentials | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 93 completion gate
Step 93 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_proxy_config.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 94 continues with **Corporate certificate authorities**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 93 succeeds when approved proxy, bypass, authentication, and redaction cases pass, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 94, python setup step 94 windows
**Windows Python Setup Step 94 is Corporate certificate authorities: produce a scoped enterprise CA trust that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **approved internal and public endpoints validate correctly**. The main failure to design against is **replacing trust stores or accepting every certificate**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Corporate certificate authorities behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 94 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 94 boundary
The deliverable is **scoped enterprise CA trust**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Corporate certificate authorities. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Corporate certificate authorities"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Corporate certificate authorities policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 94 exercise command is:
```powershell
python -c "import ssl; print(ssl.get_default_verify_paths())"
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 94 threat review must directly address **replacing trust stores or accepting every certificate**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Corporate certificate authorities. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 94
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 94 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | scoped enterprise CA trust exists in reviewed source | machine-only hidden state |
| normal behavior | approved internal and public endpoints validate correctly | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses replacing trust stores or accepting every certificate | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 94 completion gate
Step 94 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -c "import ssl; print(ssl.get_default_verify_paths())"
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 95 continues with **Offline installation**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 94 succeeds when approved internal and public endpoints validate correctly, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 95, python setup step 95 windows
**Windows Python Setup Step 95 is Offline installation: produce a local wheelhouse installation workflow that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **a disconnected clean environment installs verified artifacts**. The main failure to design against is **missing transitive wheels or mixing architectures**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Offline installation behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 95 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 95 boundary
The deliverable is **local wheelhouse installation workflow**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Offline installation. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Offline installation"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Offline installation policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 95 exercise command is:
```powershell
python -m pip install --no-index --find-links .\wheelhouse -r requirements.txt
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 95 threat review must directly address **missing transitive wheels or mixing architectures**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Offline installation. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 95
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 95 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | local wheelhouse installation workflow exists in reviewed source | machine-only hidden state |
| normal behavior | a disconnected clean environment installs verified artifacts | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses missing transitive wheels or mixing architectures | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 95 completion gate
Step 95 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip install --no-index --find-links .\wheelhouse -r requirements.txt
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 96 continues with **Air-gapped operations**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 95 succeeds when a disconnected clean environment installs verified artifacts, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 96, python setup step 96 windows
**Windows Python Setup Step 96 is Air-gapped operations: produce a controlled package-transfer and update process that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **approved media, manifests, scans, install, and rollback are auditable**. The main failure to design against is **treating physical isolation as complete supply-chain security**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Air-gapped operations behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 96 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 96 boundary
The deliverable is **controlled package-transfer and update process**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Air-gapped operations. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Air-gapped operations"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Air-gapped operations policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 96 exercise command is:
```powershell
python -m pip check
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 96 threat review must directly address **treating physical isolation as complete supply-chain security**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Air-gapped operations. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 96
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 96 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | controlled package-transfer and update process exists in reviewed source | machine-only hidden state |
| normal behavior | approved media, manifests, scans, install, and rollback are auditable | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses treating physical isolation as complete supply-chain security | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 96 completion gate
Step 96 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pip check
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 97 continues with **Self-hosted GitHub runner**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 96 succeeds when approved media, manifests, scans, install, and rollback are auditable, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 97, python setup step 97 windows
**Windows Python Setup Step 97 is Self-hosted GitHub runner: produce a ephemeral least-privilege runner design that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **jobs start clean, cannot reach unnecessary assets, and are destroyed**. The main failure to design against is **running untrusted code on a persistent privileged host**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Self-hosted GitHub runner behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 97 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 97 boundary
The deliverable is **ephemeral least-privilege runner design**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Self-hosted GitHub runner. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Self-hosted GitHub runner"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Self-hosted GitHub runner policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 97 exercise command is:
```powershell
Get-Service actions.runner*
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 97 threat review must directly address **running untrusted code on a persistent privileged host**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Self-hosted GitHub runner. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 97
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 97 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | ephemeral least-privilege runner design exists in reviewed source | machine-only hidden state |
| normal behavior | jobs start clean, cannot reach unnecessary assets, and are destroyed | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses running untrusted code on a persistent privileged host | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 97 completion gate
Step 97 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
Get-Service actions.runner*
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 98 continues with **Production monitoring**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 97 succeeds when jobs start clean, cannot reach unnecessary assets, and are destroyed, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 98, python setup step 98 windows
**Windows Python Setup Step 98 is Production monitoring: produce a actionable service-level monitoring that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **signals map to user impact with owned, tested alerts**. The main failure to design against is **alerting on every fluctuation and missing real symptoms**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Production monitoring behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 98 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 98 boundary
The deliverable is **actionable service-level monitoring**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Production monitoring. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Production monitoring"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Production monitoring policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 98 exercise command is:
```powershell
python -m pytest tests\test_alerts.py
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 98 threat review must directly address **alerting on every fluctuation and missing real symptoms**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Production monitoring. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 98
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 98 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | actionable service-level monitoring exists in reviewed source | machine-only hidden state |
| normal behavior | signals map to user impact with owned, tested alerts | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses alerting on every fluctuation and missing real symptoms | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 98 completion gate
Step 98 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m pytest tests\test_alerts.py
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 99 continues with **Incident response**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 98 succeeds when signals map to user impact with owned, tested alerts, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
windows python step 99, python setup step 99 windows
**Windows Python Setup Step 99 is Incident response: produce a rehearsed Python service incident runbook that can be rebuilt, reviewed, tested, and operated from the verified Windows project established in Steps 1–7.** This milestone adds one bounded capability. It does not replace interpreter ownership, the project `.venv`, dependency declarations, the Step 6 quality gate, or the Step 7 clean Windows CI matrix.
The working contract is specific: **triage preserves evidence, protects secrets, and supports recovery**. The main failure to design against is **making destructive changes before capturing state**. Treat those as acceptance and risk statements, not optional commentary.
| Surface | Required decision | Review evidence |
|---|---|---|
| ownership | project file/module and named maintainer | diff has a clear boundary |
| interpreter | verified console Python | executable and pip agree |
| inputs | typed, bounded, and documented | invalid cases fail clearly |
| operation | Incident response behavior | deterministic command/test |
| failure | explicit timeout/error/cleanup path | injected failure is observed |
| security | least privilege and redaction | no secret or unsafe default |
| CI | same non-mutating project command | clean Windows matrix passes |
| rollback | reversible change or runbook | prior behavior can be restored |
## Resume from the proven project
Open a fresh PowerShell window at the repository root:
```powershell
Set-Location "$HOME\Projects\hello-python"
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip check
python .\quality_gate.py
git status --short
```
The executable must end in the project `.venv\Scripts\python.exe`, not a global runtime or `pythonw.exe`. Every `python -c` example in this guide is one physical line; do not insert a PowerShell continuation backtick between `-c` and its quoted program.
Stop if the existing gate fails or the working tree contains unexplained changes. Step 99 should create a reviewable delta from a known baseline. Record unrelated work rather than sweeping it into this milestone.
## Define the Step 99 boundary
The deliverable is **rehearsed Python service incident runbook**. Write down its caller, inputs, outputs, error semantics, resource ownership, and observable result before selecting a library. A tool name is not an architecture. The boundary should remain testable when Windows paths contain spaces, the working directory changes, the network is unavailable, or an optional dependency is missing.
Create the smallest module or configuration file that owns Incident response. Keep domain policy separate from adapters that touch the filesystem, process environment, network, database, GUI, operating system, or external service. Pure policy can be tested quickly; adapters need explicit integration tests and cleanup.
Do not hard-code `C:\Users\Danny Li`, a drive letter, a personal checkout, or a `.venv` executable. Derive project resources with `pathlib`, accept deployment locations through validated configuration, and keep user-specific state outside source control.
## Inspect before adding dependencies
Search the project for an existing owner:
```powershell
Get-ChildItem -Recurse -File | Select-String -SimpleMatch "Incident response"
git ls-files
```
If the repository already has a framework, configuration section, adapter, test helper, or operational policy for this subject, extend that source of truth. Do not create parallel logging systems, HTTP clients, database sessions, configuration loaders, test runners, packaging metadata, or release scripts.
Prefer the standard library when it satisfies the contract. When a third-party distribution is justified, verify its official project identity, supported Python versions, license, maintenance posture, release notes, and transitive dependencies. Install it only through the selected interpreter and add it to the project's established dependency source.
```powershell
python -m pip check
python -m pip freeze
```
`pip freeze` is evidence of the current environment, not permission to replace a reviewed lock or dependency declaration. Never copy package versions blindly from this article; resolve according to project policy and test the resulting set on every supported Python version.
## Implement one vertical slice
Build a thin end-to-end slice: accept one valid input, execute the Incident response policy, return or persist the intended output, and expose one useful diagnostic. Keep side effects behind a narrow function/class so tests can substitute a controlled adapter.
Use explicit names and types. Validate at trust boundaries rather than deep inside business logic. Return stable domain results or raise a small documented exception family; do not leak raw library exceptions through every layer. Preserve causal context with exception chaining when translation is necessary.
The primary Step 99 exercise command is:
```powershell
python -m app.diagnostics --redacted
```
Run it from the project root through the verified interpreter/tool owner. If it is a diagnostic command, capture only non-sensitive facts. If it starts a service or GUI, use a development-only binding and stop it cleanly after the smoke check. If it invokes a test, make the test independent of live production services.
## Model inputs and outputs explicitly
Document required versus optional fields, accepted ranges, encoding, path rules, time-zone expectations, and maximum sizes. Reject ambiguous or malformed data with an actionable message. Defaults should be safe, visible, and stable; an absent critical setting must not silently select a dangerous behavior.
Machine-readable output needs a versioned schema or compatibility policy. Human-readable output should separate normal results on stdout from diagnostics on stderr and use meaningful exit codes. Do not parse localized display text as an internal interface.
For files, write to a temporary sibling and atomically replace where the filesystem supports it. For databases, define transaction ownership. For network work, set connect/read/total time budgets. For processes, pass argument lists rather than shell-built strings. For concurrency, define cancellation and shutdown before starting workers.
## Test behavior and failure
Add tests beside the established suite. Cover one normal example, a meaningful boundary, malformed input, an unavailable dependency, and cleanup after an injected failure. Assert public results and durable side effects rather than private call order.
Use temporary directories and temporary databases. Use fakes at remote boundaries for fast deterministic tests, then add a smaller integration test that proves the real adapter contract. Never point automated tests at a shared production account, personal directory, mapped drive, or mutable external resource.
Run focused tests first, then the full gate:
```powershell
python -m pytest -q
python .\quality_gate.py
```
A passing happy path is insufficient. Deliberately violate one invariant and confirm the test fails for the intended reason; restore it and rerun. This negative proof catches skipped tests, incorrect discovery, swallowed exit codes, and assertions that never execute.
## Windows-specific qualification
Exercise paths containing spaces and non-ASCII characters. Do not assume a case-sensitive filesystem, POSIX separators, executable permission bits, `fork`, Bash syntax, or a visible interactive desktop. Services and scheduled tasks often have different profiles, environment variables, network-drive mappings, certificate stores, and working directories than the developer terminal.
Open files with explicit text encoding and appropriate newline behavior. Close handles deterministically so Windows can rename or delete temporary files. Bound retry behavior around transient sharing violations; never turn an access-denied or persistent lock into an infinite loop.
If the feature crosses PowerShell, `cmd.exe`, WSL, COM, Task Scheduler, a Windows service, or a container boundary, document which parser and identity owns every argument. Test exit-code propagation. Avoid `shell=True` and string-built commands when an argument array or direct API exists.
## Security and privacy review
Apply least privilege to files, tokens, workflow permissions, network listeners, database roles, and service accounts. Keep secrets out of command lines, URLs, repository files, exceptions, screenshots, test fixtures, and logs. Redact by field policy rather than after arbitrary strings have already been emitted.
Treat external files, archives, JSON, CSV, HTTP responses, package artifacts, environment variables, registry values, queue messages, and user input as untrusted. Validate size before allocation, normalize only after defining semantics, and reject traversal or unexpected destinations. Never disable TLS verification, ACLs, authentication, or safety checks merely to make a tutorial command pass.
The Step 99 threat review must directly address **making destructive changes before capturing state**. Record the chosen control and a test or operational check that proves it. If the control needs new credentials, infrastructure, administrator rights, or external coordination, stop and obtain that authority rather than hiding the dependency.
## CI parity
Commit the implementation, configuration, tests, and dependency changes—never the `.venv` or tool caches. Step 7 should rebuild them on clean Windows runners and invoke the same `quality_gate.py` used locally.
```powershell
git status --short
git diff
python .\quality_gate.py
```
Do not add a second CI-only policy that disagrees with local commands. A cache hit may improve speed but must not provide undeclared correctness. The job must still install declarations, run `pip check`, and execute the gate.
When the capability requires slow integration or end-to-end tests, mark and schedule them deliberately while keeping a fast pull-request signal. A required check must not silently skip the only test that proves this milestone.
## Observability and operations
Define what an operator can observe without attaching a debugger: success count, bounded latency, failure category, dependency health, queue depth, last completed operation, or another signal appropriate to Incident response. Use stable structured fields and correlation identifiers where requests cross components.
Do not log entire payloads by default. Bound log size, metric cardinality, artifact retention, and diagnostic collection. Health checks should distinguish process liveness from readiness to serve; a running process with an unavailable required dependency is not necessarily ready.
Write the recovery action beside the signal. An alert without an owner or safe response is noise. Test alert conditions and diagnostic redaction just like application behavior.
## Rollout and rollback
Introduce the capability behind a narrow configuration switch or reversible integration point when risk justifies it. Establish the baseline, deploy to the smallest representative scope, observe the acceptance signal, and expand only after the result is understood.
Rollback must name the prior artifact/configuration, compatibility constraints, data consequences, and verification command. Code rollback may not reverse a schema migration, emitted message, encrypted value, external side effect, or overwritten file. Design forward repair when reversal is unsafe.
Record who owns the feature after merge, how dependencies are updated, what evidence is retained, and when the policy is reviewed. Setup is not complete when a command runs once; it is complete when another person can reproduce, diagnose, and safely retire it.
## Troubleshooting without destructive shortcuts
**The command is not found.** Recheck `sys.executable`, use `python -m ...`, and verify the dependency declaration. Do not install globally or use `--user` to mask a project problem.
**It works only from VS Code.** Compare selected interpreter, working directory, environment, launch configuration, and unsaved files. The project command and CI gate remain authoritative.
**It works only on the developer machine.** Search for undeclared packages, absolute paths, user-site imports, cached state, credentials, mapped drives, locale assumptions, and interactive prompts. Reproduce on the clean Windows matrix.
**Tests hang.** Add timeouts at the real blocking boundary; inspect threads, child processes, sockets, UI loops, locks, and teardown. Do not add arbitrary sleeps as synchronization.
**Access is denied.** Identify the exact path/object and effective identity, inspect ownership/ACLs, and grant the minimum required access. Do not run the entire application as Administrator.
**A test is flaky.** Capture seed, timing, ordering, concurrency, locale, and external-state evidence. Make the dependency controllable instead of rerunning until green.
**CI differs from local.** Compare recorded Python version, dependency resolution, configuration sources, path casing, line endings, and collected tests. Preserve the failing log before changing state.
## What not to do in Step 99
- Do not bypass Steps 1–7 interpreter, dependency, quality, or CI evidence.
- Do not hard-code personal Windows paths, tokens, hosts, or credentials.
- Do not create a duplicate framework or configuration source.
- Do not rely on current working directory, global packages, or user-site imports.
- Do not make live production services part of unit tests.
- Do not swallow exceptions or convert every failure to a successful exit.
- Do not disable validation, TLS, authentication, ACLs, or safety checks.
- Do not commit virtual environments, caches, generated secrets, or private data.
- Do not apply automatic fixes without reviewing the source diff.
- Do not call the milestone complete until a deliberate failure is detected.
| Step 99 acceptance | Pass condition | Stop condition |
|---|---|---|
| project baseline | interpreter, pip, and quality gate agree | unresolved prior failure |
| deliverable | rehearsed Python service incident runbook exists in reviewed source | machine-only hidden state |
| normal behavior | triage preserves evidence, protects secrets, and supports recovery | ambiguous or unobserved result |
| invalid input | fails early with actionable error | silent coercion or corruption |
| injected failure | test and process return nonzero | swallowed error or skipped test |
| Windows qualification | spaces, Unicode, cleanup, identity pass | user-specific assumption |
| security | control addresses making destructive changes before capturing state | unsafe workaround required |
| clean CI | supported Windows matrix rebuilds and passes | cache/global dependency |
| operations | signal, owner, and recovery are documented | no safe diagnosis/rollback |
## Step 99 completion gate
Step 99 is complete only when the deliverable is committed with tests and declarations; normal, boundary, and injected-failure cases are proven; Windows-specific behavior is qualified; the named risk has a tested control; the full local quality gate passes; clean Windows CI passes without hidden state; and another operator can diagnose and reverse or safely repair the change.
Run final local evidence:
```powershell
python -c "import sys; print(sys.executable)"
python -m pip check
python -m app.diagnostics --redacted
python .\quality_gate.py
git status --short
```
Review output before publishing it. Remove personal paths, tokens, internal hostnames, private index details, customer data, and unnecessary payloads from logs or screenshots.
Step 100 continues with **Lifecycle maintenance**. Carry forward the same interpreter evidence, source-control review, and non-mutating gate.
**Windows Python Setup Step 99 succeeds when triage preserves evidence, protects secrets, and supports recovery, the failure path is deliberately proven, clean Windows CI reproduces the result, and the operational owner can observe and recover it without relying on the developer's machine.**
wsl ubuntu python setup, python setup wsl ubuntu, windows subsystem linux python setup, wsl python installation windows, python3 setup ubuntu wsl, microsoft store ubuntu python, new ubuntu wsl python setup
**Windows WSL Python Setup Step 1 is to initialize the brand-new Microsoft Store Ubuntu instance, prove which layer owns each command, update Ubuntu safely, and verify its OS-managed `python3` without creating a project or installing global Python packages.** The finish line is a healthy WSL 2 Ubuntu distribution, a normal non-root Linux user with working `sudo`, current package metadata/security updates, and a known Linux Python executable ready for a project virtual environment in Step 2.
The customer already installed Ubuntu from the Windows Store. Do not reinstall, unregister, reset, convert, or delete it. A Store installation is only the application/image stage; the first launch still initializes the distribution and normally asks for a Linux username and password.
| Surface | Run it from | Step 1 evidence |
|---|---|---|
| WSL engine/version | Windows PowerShell | `wsl --status` and `wsl --version` |
| installed distro/version | Windows PowerShell | `wsl --list --verbose` |
| first-run account | Ubuntu terminal | `whoami`, `id`, working `sudo` |
| Ubuntu release/kernel | Ubuntu terminal | `/etc/os-release`, `uname` |
| package health | Ubuntu terminal | `apt update`, reviewed upgrade |
| Python owner | Ubuntu terminal | `command -v python3`, `sys.executable` |
| project location | Ubuntu filesystem | future work under `~/projects` |
| handoff | Ubuntu terminal | base ready for `.venv` in Step 2 |
## Understand the two systems before typing commands
WSL is managed from Windows. Ubuntu is a Linux distribution running inside WSL. They interoperate, but their users, paths, package managers, permissions, and Python installations are different.
Commands beginning with `wsl` in this guide are labeled **PowerShell** and run in Windows PowerShell or Command Prompt. Commands such as `sudo`, `apt`, `whoami`, and `python3` are labeled **Ubuntu** and run inside the Ubuntu shell.
Do not paste the prompt text itself. These examples omit prompts so commands can be copied cleanly. If the terminal shows a path under `/mnt/c/...`, it is in Ubuntu but currently located on the mounted Windows filesystem.
The Windows account and the Ubuntu account are separate identities. The Ubuntu username does not have to equal the Windows display name. Its password is a new Linux password; it is not automatically the Microsoft account PIN/password.
## Inspect WSL from PowerShell
Open a normal, non-elevated PowerShell window. Run:
```powershell
wsl --status
wsl --version
wsl --list --verbose
```
`wsl --list --verbose` is the authoritative inventory for the exact distribution name, running/stopped state, and WSL generation. The Store tile may say “Ubuntu,” while the registered name can be `Ubuntu`, `Ubuntu-24.04`, or another explicit release. Copy the name exactly for later `-d` commands.
The `VERSION` column should normally be `2` for a new development setup. Do not convert it merely because a tutorial says so. If it shows `1`, first confirm Windows/organizational requirements, virtualization support, free disk space, and backups. Conversion changes the distribution’s storage architecture and can take time.
`wsl --version` reports components of WSL; `wsl --status` reports configuration. If `--version` is unavailable on an older inbox WSL installation, do not conclude Ubuntu is broken. Follow the organization’s Windows-update policy.
To request supported WSL servicing from PowerShell:
```powershell
wsl --update
```
Updating WSL is different from updating Ubuntu packages. It may need administrator approval or Store access on a managed device. Do not use unofficial kernel downloads or disable corporate controls.
## Launch the installed Ubuntu distribution
Use the exact name printed by `wsl --list --verbose`. For a distribution registered as `Ubuntu`:
```powershell
wsl --distribution Ubuntu
```
To start directly in the Linux home directory:
```powershell
wsl ~ --distribution Ubuntu
```
The first launch may spend a minute unpacking/configuring the instance. Let it finish. Closing the window, killing WSL, or restarting Windows during initial expansion can leave an incomplete first-run experience.
If the Store page says Installed but `wsl --list --verbose` does not list Ubuntu, launch the Ubuntu Store app once so registration/initialization can complete. Do not use `wsl --unregister`; that command permanently deletes the selected distribution’s Linux filesystem and data.
## Create the default Linux user
On first launch, Ubuntu normally prompts for a new UNIX username and password. Choose a simple lowercase username without spaces. Use a unique strong password that the customer can retain securely.
When entering a Linux password, the terminal deliberately shows no characters, dots, or asterisks. Type it carefully and press Enter. This is normal and does not mean the keyboard is inactive.
The created account should be the default everyday user and should be allowed to run administrative commands through `sudo`. Do not use `root` as the daily account and do not configure passwordless administration merely for convenience.
After the prompt appears, run these commands inside **Ubuntu**:
```bash
whoami
id
printf 'home=%s\n' "$HOME"
pwd
```
Expected evidence:
- `whoami` prints the new Linux username, not `root`.
- `id` includes the normal user and commonly the `sudo` group.
- `$HOME` is `/home/`.
- after starting with `wsl ~`, `pwd` matches that home directory.
Test `sudo` without changing anything:
```bash
sudo -v
```
Enter the Linux password. A successful return with no error proves cached sudo authorization for the current session. Do not test administration by editing system files.
## Record Ubuntu and kernel identity
Still inside **Ubuntu**, run:
```bash
cat /etc/os-release
uname -a
uname -m
```
`/etc/os-release` identifies the Ubuntu release. Prefer a supported LTS release for a stable customer environment. `uname -a` identifies the WSL Linux kernel, while `uname -m` identifies architecture such as `x86_64` or `aarch64`.
Do not assume the Ubuntu release from a screenshot, Store marketing text, or current date. Record the actual `VERSION_ID` and architecture because package names, availability, and binary wheels can depend on them.
Check init behavior only as a diagnostic:
```bash
ps -p 1 -o comm=
```
Recent Ubuntu WSL images commonly use systemd, but Step 1 does not require changing `/etc/wsl.conf`. Do not enable/disable systemd to imitate another guide unless a later application has a documented need.
## Update Ubuntu package metadata
The Store image is a point-in-time filesystem. Refresh package indexes inside **Ubuntu**:
```bash
sudo apt update
```
Read the output. Repository signatures must validate. Warnings about unreachable mirrors, proxies, certificates, DNS, or clocks are setup failures to diagnose—not reasons to add insecure repositories or disable TLS verification.
Review available upgrades:
```bash
apt list --upgradable
```
Then apply normal package upgrades:
```bash
sudo apt upgrade
```
Review the proposed changes before confirming. On a managed customer device, follow maintenance/change policy. The `-y` option is convenient for automation but removes the interactive review; it is intentionally omitted in this first guided run.
Run the refresh again:
```bash
sudo apt update
apt list --upgradable
```
Some phased, held, or restart-sensitive packages may remain. Do not force, unhold, perform a distribution release upgrade, or edit apt sources merely to make the list empty. Capture the exact package/status and follow Ubuntu or organizational policy.
## Know when Windows or WSL needs restarting
An Ubuntu package update does not normally require restarting Windows. If processes need refreshed libraries, close the Ubuntu shell and restart only the distribution when appropriate.
From **Ubuntu**:
```bash
exit
```
From **PowerShell**, terminate only the named distribution if a controlled restart is required:
```powershell
wsl --terminate Ubuntu
wsl ~ --distribution Ubuntu
```
Replace `Ubuntu` with the registered name. `wsl --shutdown` stops every running WSL distribution and the WSL 2 utility VM; that broader effect can interrupt other work. Do not use it casually on a shared developer machine.
## Inspect Ubuntu's system Python
Ubuntu uses Python for operating-system tools. Its `/usr/bin/python3` and related packages belong to `apt`. Verify rather than replacing them.
Inside **Ubuntu**:
```bash
command -v python3
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.version)"
```
The executable normally resolves to `/usr/bin/python3`. Both `python3 -c` examples are complete single physical lines. Do not split `-c` from the quoted Python program.
The result must be a Linux path. It must not be a Windows path such as `C:\Users\Danny Li\...\python.exe` or `pythonw.exe`. WSL can launch Windows executables through interoperability, but this sequence is deliberately building a Linux Python environment inside Ubuntu.
The bare `python` command may not exist. That is not a defect. Ubuntu’s explicit system command is `python3`. Do not add random aliases, symlinks, or `python-is-python3` solely to shorten the command.
## Install only Ubuntu-managed Python prerequisites
Inspect package ownership first:
```bash
apt-cache policy python3 python3-venv python3-pip
dpkg -S "$(command -v python3)"
```
Install the distribution-supported base and environment tooling through `apt`:
```bash
sudo apt install python3 python3-venv python3-pip
```
Read and approve the package plan. This is an operating-system package action, so `sudo` is appropriate. It is not the same as installing Python packages with pip as root.
Verify ownership afterward:
```bash
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m pip --version
python3 -m venv --help
```
If `python3 -m pip --version` reports an externally managed environment when later asked to install packages globally, that protection is intentional. Never use `sudo pip`, `--break-system-packages`, or global `pip install` for project dependencies. Step 2 will create `.venv`, where pip can operate without modifying Ubuntu’s system Python.
## Separate Windows Python from WSL Python
PowerShell and Ubuntu can each resolve a command named Python, but they are separate runtimes with separate packages and virtual environments.
From **PowerShell**:
```powershell
python -c "import sys; print(sys.executable)"
wsl --distribution Ubuntu -- python3 -c "import sys; print(sys.executable)"
```
The first line, if Windows Python is installed, prints a Windows path. The second prints the Ubuntu Linux path. Neither is “more correct”; the correct owner depends on whether the project is a Windows project or a Linux/WSL project.
Do not activate a Windows `.venv\Scripts\Activate.ps1` inside Ubuntu. Do not activate a Linux `.venv/bin/activate` in PowerShell. Virtual environments contain platform-specific executable paths and installed artifacts and must not cross the OS boundary.
## Choose the Linux project filesystem
For Linux tools running in Ubuntu, keep active projects in the WSL Linux filesystem. Create only the parent workspace in Step 1:
```bash
mkdir -p ~/projects
cd ~/projects
pwd
```
The path should be under `/home//projects`, not `/mnt/c/Users/...`. Linux filesystem storage avoids cross-filesystem translation overhead and preserves Linux permissions, symlinks, case behavior, and file-notification semantics more naturally.
Windows drives are available under `/mnt`, for example `/mnt/c`. Use them for intentional file exchange, not as the default home of a Linux build-intensive project.
To view the current Linux directory in Windows Explorer:
```bash
explorer.exe .
```
This is convenient for inspection. Avoid editing Linux metadata, `.venv`, sockets, or dependency trees with tools that do not understand their semantics. From Windows, Linux files are exposed through `\\wsl.localhost\\...`; do not move the distribution’s internal virtual-disk files manually.
## Check network and clock without hiding failures
Package updates already provide a useful network/TLS test. For targeted diagnostics inside **Ubuntu**:
```bash
getent hosts archive.ubuntu.com
date --iso-8601=seconds
```
DNS must resolve and the clock must be plausible for TLS validation. Corporate proxy or certificate requirements should be configured through approved Windows/Ubuntu mechanisms. Do not paste proxy credentials into shell history, apt source URLs, screenshots, or public support tickets.
If `apt update` fails, capture the exact repository URL, status code, and certificate/DNS message while redacting private information. Distinguish no network, DNS failure, proxy authentication, TLS trust, incorrect time, and repository-signature errors; they require different fixes.
## Basic Linux command orientation
These read-only commands help a Windows user understand the new environment:
```bash
pwd
ls -la
echo "$SHELL"
printf 'user=%s home=%s\n' "$USER" "$HOME"
```
Linux paths use `/`, names are case-sensitive, and hidden files begin with `.`. The root directory `/` is not the Windows `C:\` drive. The home shortcut `~` expands to the current Linux user’s home.
Use `Ctrl+Shift+C` and `Ctrl+Shift+V` in many terminal hosts for copy/paste. `Ctrl+C` inside a shell normally sends an interrupt to the foreground process; it is not always a copy shortcut.
## Optional: make Ubuntu the default distribution
If multiple distributions are installed and this Ubuntu instance is intentionally the default, use **PowerShell**:
```powershell
wsl --set-default Ubuntu
wsl --list --verbose
```
Use the exact registered name. Changing the default affects commands such as bare `wsl` but does not delete or convert any distribution. Skip this on machines where another distribution owns existing workflows.
## Backup boundary before destructive administration
Step 1 does not need a backup of an empty instance, but the customer must recognize destructive commands before data accumulates. From PowerShell, `wsl --unregister ` permanently removes that distribution and its data.
Later, a controlled export can create a backup artifact:
```powershell
wsl --export Ubuntu C:\Backups\ubuntu-wsl.tar
```
That example requires a reviewed destination, sufficient space, sensitive-data handling, and preferably a stopped/consistent workload. Do not run it now if the directory/retention policy is undefined. Never treat copying WSL internal package files as a valid backup.
## Troubleshoot targeted failures
**Ubuntu opens and immediately closes.** Launch it from PowerShell with the exact distro name so the error remains visible. Recheck `wsl --status` and `wsl --list --verbose`; do not reset the Store app before preserving the message.
**First launch never asks for a user.** Confirm initialization finished and which distribution actually opened. If the prompt is already a normal user, verify with `whoami` and `id`. If it is root, follow the specific Ubuntu WSL user-repair guidance rather than inventing `/etc/passwd` edits.
**The password appears blank.** Linux password input is intentionally not echoed. Type it and press Enter. Use `sudo -v` afterward to verify.
**`sudo` rejects the password.** Confirm keyboard layout, Caps Lock, and that it is the Linux password. Do not confuse it with the Windows PIN. Avoid repeated guesses that obscure the real account state.
**`apt update` cannot resolve hosts.** Test `getent hosts`, inspect Windows connectivity/VPN/proxy state, and capture `/etc/resolv.conf` only as evidence. Do not make it immutable or hard-code public DNS without understanding WSL-managed generation and corporate policy.
**TLS or repository signatures fail.** Verify clock, URL, proxy, certificate chain, and official Ubuntu sources. Never add `[trusted=yes]`, use insecure transport, or disable verification.
**`python3` is missing.** Refresh apt metadata and install `python3 python3-venv python3-pip` from official Ubuntu repositories. Do not download an arbitrary installer or replace `/usr/bin/python3`.
**`python` is missing but `python3` works.** Use `python3`. This guide intentionally does not require a `python` alias.
**Python resolves under `/mnt/c` or to `.exe`.** A Windows command is being invoked through interoperability or PATH. Use `/usr/bin/python3`, inspect `type -a python3`, and remove only the incorrect user customization after review.
**Files are slow under `/mnt/c`.** Move the Linux-owned project workflow to `~/projects` using a reviewed copy and verify before removing the original. Do not move an active `.venv`; recreate it in Step 2.
**WSL version shows 1.** Do not force conversion. Confirm project need, system support, policy, and backup; then use Microsoft’s documented conversion command in a controlled window.
## What not to do in WSL Step 1
- Do not reinstall or reset the Store Ubuntu app when first-launch initialization is merely pending.
- Do not use `wsl --unregister`; it deletes the selected distribution’s data.
- Do not work as root or configure passwordless administration for convenience.
- Do not replace, delete, or manually symlink `/usr/bin/python3`.
- Do not run `sudo pip`, `pip --user`, or `--break-system-packages` for project dependencies.
- Do not reuse a Windows virtual environment inside Ubuntu or a Linux environment in PowerShell.
- Do not store a Linux-first project under `/mnt/c` without an explicit reason.
- Do not disable TLS, repository signatures, certificate verification, or corporate controls.
- Do not copy commands for a distro name until `wsl --list --verbose` confirms it.
- Do not make `root` the default WSL user.
- Do not publish usernames, home paths, proxy data, internal hosts, or tokens in screenshots.
- Do not perform a release upgrade as part of this first Python setup step.
| Step 1 acceptance | Pass condition | If it fails |
|---|---|---|
| Windows inventory | exact Ubuntu name and WSL version known | diagnose PowerShell/registration |
| first launch | initialization finishes once | preserve error; do not reset |
| Linux identity | normal user, home, and sudo work | repair account ownership |
| Ubuntu identity | supported release and architecture recorded | follow release policy |
| package metadata | signed official repositories refresh | fix DNS/proxy/TLS/time |
| package state | reviewed normal upgrades applied | investigate holds/restart needs |
| Python executable | Linux `/usr/bin/python3` owner proven | install through apt |
| Python tooling | `venv` and pip modules available | install apt prerequisites |
| filesystem | `~/projects` exists in Linux home | leave `/mnt/c` for exchange |
| safety | no root workflow, global pip, reset, or unregister | stop and restore boundary |
## Windows WSL Python Setup Step 1 completion gate
Step 1 is complete only when:
1. PowerShell identifies the exact registered Ubuntu name, WSL state, and WSL generation.
2. First-run initialization has completed without resetting or unregistering the distribution.
3. A normal Linux user owns `/home/` and can authenticate with `sudo`.
4. Ubuntu release, architecture, and kernel evidence are recorded.
5. Official apt repositories refresh with valid signatures and normal updates are reviewed/applied.
6. `python3` resolves to Ubuntu’s Linux system executable and reports its actual version.
7. `python3-venv` and `python3-pip` are installed through apt, not global pip/bootstrap scripts.
8. Windows and Ubuntu Python identities are understood as separate environments.
9. `~/projects` exists on the Linux filesystem for the upcoming Linux-first project.
10. No customer path, password, proxy credential, token, or internal hostname was published.
Run the final evidence inside **Ubuntu**:
```bash
whoami
printf 'home=%s cwd=%s\n' "$HOME" "$PWD"
cat /etc/os-release
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m pip --version
```
Then leave Ubuntu and confirm the distribution from **PowerShell**:
```powershell
exit
wsl --list --verbose
```
The next keyword should be **Windows WSL Python Setup Step 2**: create `~/projects/hello-python`, build a Linux `.venv` with `python3 -m venv .venv`, activate it with `source .venv/bin/activate`, and prove that both Python and pip belong to that environment without crossing into the Windows filesystem.
**Windows WSL Python Setup Step 1 succeeds when the Store-installed Ubuntu instance is initialized under a normal Linux user, updated through trusted repositories, and its apt-managed Linux `python3` is verified—ready for a project-local `.venv`, with Windows and Linux ownership kept unmistakably separate.**
**Windows WSL Python Setup Step 2 is to create one Linux-owned project under Ubuntu’s home filesystem, build `.venv` from the verified Ubuntu `python3`, and prove that Python and pip resolve inside that environment.** The customer’s Microsoft Store Ubuntu instance remains the Linux runtime; Windows Python, Windows paths, and Windows virtual environments do not participate.
Step 1 initialized Ubuntu, created a normal Linux user, updated trusted packages, and verified the apt-managed `/usr/bin/python3` plus `python3-venv` and `python3-pip`. Step 2 adds project isolation only. Third-party application dependencies belong in Step 3 after ownership is proven.
| Layer | Expected owner | Step 2 evidence |
|---|---|---|
| WSL distribution | registered Ubuntu instance | PowerShell distro name |
| project files | Linux user under `~/projects` | `pwd`, `stat`, `ls -la` |
| base interpreter | Ubuntu apt package | `/usr/bin/python3` |
| virtual environment | this project only | `.venv/bin/python` |
| project pip | this `.venv` | `.venv` site-packages path |
| activation | current Bash process | `VIRTUAL_ENV` and `PATH` |
| source control | source/config only | `.venv/` ignored |
| recreation | declared base plus commands | delete/rebuild only when safe |
## Resume inside the correct Ubuntu instance
From **PowerShell**, inspect the registered name:
```powershell
wsl --list --verbose
```
Start the intended instance in its Linux home directory, replacing `Ubuntu` if the inventory shows a numbered name:
```powershell
wsl ~ --distribution Ubuntu
```
From this point, commands are **Ubuntu Bash** unless explicitly labeled PowerShell. Prove the Step 1 baseline:
```bash
whoami
pwd
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m venv --help
```
The user must not be `root`; `pwd` should be `/home/`; and `sys.executable` should be a Linux path such as `/usr/bin/python3`. Every `python3 -c` and `python -c` example in this guide is one complete physical command line.
If `python3 -m venv --help` fails because venv/ensurepip is unavailable, repair through Ubuntu’s package manager:
```bash
sudo apt update
sudo apt install python3-venv python3-pip
```
Do not bootstrap the system interpreter with downloaded scripts, `sudo pip`, `--user`, or `--break-system-packages`.
## Confirm the filesystem boundary
Check the home path and Windows mount:
```bash
printf 'home=%s cwd=%s\n' "$HOME" "$PWD"
findmnt -T "$HOME"
findmnt -T /mnt/c
```
The project will live under `$HOME`, inside the distribution’s Linux filesystem. `/mnt/c` exposes Windows NTFS and is useful for intentional exchange, but it is not the default location for a Linux-tool project. Linux-native storage gives the expected permissions, case behavior, symlinks, file notifications, and better Linux workload performance.
Do not create this environment in `C:\Users\...`, `/mnt/c/Users/...`, OneDrive, a Windows network share, or an existing Windows project directory. Do not move a pre-existing Windows `.venv` into Ubuntu; environments contain platform-specific executables and absolute paths.
## Create the project directory without sudo
Run as the normal Ubuntu user:
```bash
mkdir -p ~/projects/hello-python
cd ~/projects/hello-python
pwd
stat -c 'owner=%U group=%G mode=%A path=%n' .
```
The path should be `/home//projects/hello-python`, and the owner should be that Linux user. `sudo mkdir` is wrong here because it creates root-owned project state and leads to later permission workarounds.
Inspect before creating anything:
```bash
ls -la
```
If this directory already contains source, a `.venv`, `pyproject.toml`, requirements/lock files, or Git metadata, stop and follow that project’s documented environment workflow. Do not layer this beginner setup over an established project.
## Record the base interpreter
Before creating the environment:
```bash
command -v python3
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.prefix); print(sys.base_prefix)"
```
Outside a virtual environment, `sys.prefix` and `sys.base_prefix` normally match. Record the Python minor version, because the environment will be coupled to that base interpreter. A virtual environment is disposable derived state, not a portable Python distribution.
Do not replace `/usr/bin/python3`, change its symlink, or install another interpreter merely to match a screenshot. If the project later declares a different supported version, select/install it deliberately before recreating the environment.
## Create `.venv`
From the empty project root:
```bash
python3 -m venv .venv
```
No `sudo` is required. The standard-library `venv` module creates an isolated Python installation rooted at `.venv` and normally seeds pip through `ensurepip` without contacting a package index.
Inspect only the top of the generated structure:
```bash
find .venv -maxdepth 2 -type f -o -type l | sort | head -40
```
Important entries include:
- `.venv/bin/python` — the project interpreter.
- `.venv/bin/pip` — the environment’s pip launcher.
- `.venv/bin/activate` — Bash/zsh activation script.
- `.venv/pyvenv.cfg` — metadata pointing toward the base installation.
- `.venv/lib/pythonX.Y/site-packages` — project package installation area.
Do not edit generated launchers or `pyvenv.cfg` to relocate the environment. Recreate `.venv` at its intended path instead.
## Prove direct invocation before activation
Activation is convenient, not magic. Test the environment by exact path first:
```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
```
Expected evidence:
- `sys.executable` ends in `/hello-python/.venv/bin/python`.
- `sys.prefix` points inside `.venv`.
- `sys.base_prefix` points to the Ubuntu base and differs from `sys.prefix`.
- pip’s reported location is under `.venv/lib/.../site-packages`.
This direct form is ideal for scheduled jobs, CI, troubleshooting, and scripts that must not depend on shell state.
## Activate with Ubuntu Bash syntax
Activate in the current shell:
```bash
source .venv/bin/activate
```
The shell prompt commonly gains `(.venv)`, but prompt text is cosmetic. Activation prepends `.venv/bin` to `PATH`, sets `VIRTUAL_ENV`, and defines `deactivate` in this shell.
Prove behavior:
```bash
printf 'VIRTUAL_ENV=%s\n' "$VIRTUAL_ENV"
command -v python
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
```
All paths must resolve inside the project `.venv`. Use `python -m pip` after activation so package-manager ownership follows the interpreter being tested.
`source` is required because activation must modify the current shell. Running `.venv/bin/activate` as a child process would not preserve its environment changes. PowerShell’s `.venv\Scripts\Activate.ps1` is the Windows layout and does not apply inside Ubuntu.
## Understand what activation does not do
Activation does not change Python code, install dependencies, start WSL, change the Ubuntu user, or make the project portable. It changes command resolution in one shell process.
Opening another Ubuntu tab does not inherit activation automatically. Changing directories does not deactivate it. A prompt can be customized or hidden, so `sys.executable` and `sys.prefix` are the authoritative proof.
Do not add automatic activation to `~/.bashrc` in Step 2. Global auto-activation can silently apply one project environment in unrelated directories and makes troubleshooting harder.
## Inspect isolation from the system interpreter
With `.venv` active:
```bash
python -c "import site; print(site.getsitepackages())"
python -c "import sys; print('\n'.join(sys.path))"
python -m pip list
python -m pip check
```
The environment begins with a small packaging-tool set. Exact versions change with the Ubuntu/Python seed; do not compare them to an old screenshot. `pip check` should report no broken requirements.
The system interpreter still exists outside the environment. Do not try to remove it to “prove” isolation. The distinction is prefix/path ownership, not absence of the base Python.
## Create a first source file
Open `hello.py` with a Linux-aware editor such as `nano`:
```bash
nano hello.py
```
Enter:
```python
from __future__ import annotations
import platform
import sys
def main() -> None:
print("Hello from Ubuntu on WSL")
print(f"python={sys.executable}")
print(f"platform={platform.system()}")
if __name__ == "__main__":
main()
```
Save and exit, then run through the active environment:
```bash
python hello.py
```
The platform should be Linux and the Python path should be inside `.venv`. The file intentionally uses no third-party package; Step 2 is proving interpreter isolation.
Also prove direct execution after activation-independent selection:
```bash
.venv/bin/python hello.py
```
Both runs must select the same project interpreter.
## Exclude generated environment state
Create or edit `.gitignore`:
```bash
nano .gitignore
```
Add:
```gitignore
.venv/
__pycache__/
*.py[cod]
```
The virtual environment is derived, machine/platform-specific state. Commit source, configuration, and dependency declarations later—not environment binaries or installed packages.
If Git is installed, verify ignore behavior without staging:
```bash
git check-ignore -v .venv/bin/python
```
If this is not yet a Git repository, the command may say so. Do not initialize or connect a remote repository without the customer’s intended ownership/workflow. The `.gitignore` file is still correct preparation.
Never exclude all dotfiles: important configuration such as `.github`, `.env.example`, or editor/project settings may be hidden by that overbroad rule.
## Deactivate and prove the boundary
Leave the environment:
```bash
deactivate
```
Then inspect:
```bash
printf 'VIRTUAL_ENV=%s\n' "${VIRTUAL_ENV-}"
command -v python || true
command -v python3
python3 -c "import sys; print(sys.executable)"
```
`VIRTUAL_ENV` should be empty and `python3` should return to Ubuntu’s system interpreter. A bare `python` may disappear; that is normal.
Reactivate—do not recreate:
```bash
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python hello.py
```
Reactivation should use the existing environment and source file. Re-running `python3 -m venv .venv` over an active environment is not the normal way to enter it.
## New terminal and return workflow
Close the shell or run `exit`. From PowerShell, return directly to the project:
```powershell
wsl --distribution Ubuntu --cd ~/projects/hello-python
```
If the installed WSL build/shell does not expand that home path as expected, use:
```powershell
wsl ~ --distribution Ubuntu
```
Then inside Ubuntu:
```bash
cd ~/projects/hello-python
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python hello.py
```
This four-command return sequence is the normal daily workflow.
## Windows and Linux environment separation
From PowerShell, Windows Python may show a path ending in `.exe`. From Ubuntu, the environment must show `.venv/bin/python`. They cannot share installed packages.
Do not run these Windows forms inside Ubuntu for this project:
```text
.venv\Scripts\Activate.ps1
py -m venv .venv
C:\Users\...\python.exe
```
Do not run Linux activation from PowerShell. Interoperability can launch cross-OS executables, but “it starts” does not make a virtual environment portable.
If Windows Explorer opens the project through `\\wsl.localhost`, do not drag a Windows `.venv` into it. Avoid tools that rewrite Linux permissions, symlinks, or line endings unexpectedly.
## Permissions and ownership
Check ownership:
```bash
stat -c 'owner=%U group=%G mode=%A path=%n' . .venv hello.py
```
The normal Linux user should own all three. Project creation, venv creation, pip inside `.venv`, editing, and tests do not need `sudo`.
If files are root-owned because an earlier command incorrectly used sudo, identify exact paths before repair. Do not recursively `chmod 777` or change ownership across `$HOME`, `/`, `/usr`, or the WSL distribution.
Default permissions are influenced by `umask`:
```bash
umask
```
Do not change global umask as a shortcut. Shared-group projects require a deliberate group/ACL design beyond this single-user tutorial.
## Environment recreation is the recovery model
`.venv` should be reproducible from the base interpreter plus dependency declarations. Step 2 has no third-party dependencies yet, so recreation is simple—but deletion is still destructive and must target the exact project environment.
Before any future rebuild, deactivate it, verify `pwd`, verify the target is exactly `~/projects/hello-python/.venv`, and preserve dependency declarations. Never use an unresolved variable or broad recursive path.
Do not copy `.venv` as a backup. Back up source and declarations. If Ubuntu/Python minor version changes, recreate rather than patching launchers or symlinks.
## Troubleshoot targeted failures
**`No module named venv` or ensurepip unavailable.** Run `sudo apt update` and install `python3-venv`; on some Ubuntu releases a version-specific venv package may be required. Use apt’s diagnostic rather than a downloaded bootstrap script.
**Permission denied creating `.venv`.** Check `pwd`, `whoami`, and `stat .`. The project may be root-owned or on a restricted mount. Do not rerun with sudo.
**Activation file is not found.** Confirm Linux separators and `ls -la .venv/bin`. A `.venv/Scripts` tree indicates a Windows environment in the wrong project.
**`source` is not found.** Confirm the shell with `echo "$SHELL"`. In POSIX `sh`, dot syntax `. .venv/bin/activate` may be used; this tutorial assumes Ubuntu Bash.
**Prompt changes but Python is global.** Ignore the prompt and inspect `command -v python`, `sys.executable`, `VIRTUAL_ENV`, and `PATH`. Remove conflicting aliases/functions only after identifying them with `type -a python`.
**pip reports `/usr/lib` or `$HOME/.local`.** It is not the project pip. Reactivate or run `.venv/bin/python -m pip`. Do not use `pip --user` inside a venv.
**`python` is missing after deactivate.** Expected on Ubuntu installations that expose only `python3`. Reactivate for the project or use `python3` for the system base.
**The environment works only in one terminal.** Activation is per-shell. Return to the project and source the activation script in every new Ubuntu shell.
**The project is under `/mnt/c`.** Stop before installing dependencies. Create the Linux-owned project under `~/projects` and recreate `.venv`; do not move the environment.
**Windows antivirus/sync tools interfere.** Keep Linux-owned project state in the Linux filesystem and use supported `\\wsl.localhost` access only when necessary. Do not exclude broad customer directories without security approval.
**Import finds an unexpected local module.** Inspect file names for `typing.py`, `json.py`, `platform.py`, or other standard-library shadows and run `python -c "import module; print(module.__file__)"` with the actual module name.
## What not to do in WSL Step 2
- Do not create the Linux project under `/mnt/c` by default.
- Do not create project files or `.venv` with `sudo`.
- Do not use `sudo pip`, `pip --user`, or `--break-system-packages`.
- Do not activate `.venv\Scripts\Activate.ps1` inside Ubuntu.
- Do not reuse/move/copy a Windows virtual environment into WSL.
- Do not modify `/usr/bin/python3` or Ubuntu’s package-managed files.
- Do not add project auto-activation globally to `.bashrc`.
- Do not trust prompt text instead of `sys.executable`.
- Do not commit `.venv`, caches, or interpreter binaries.
- Do not delete/recreate an existing environment until its exact ownership and declarations are known.
| Step 2 gate | Pass condition | If it fails |
|---|---|---|
| distro/user | intended Ubuntu and non-root user | return to Step 1 |
| project path | under `/home/.../projects` | leave Windows mount |
| project owner | normal Linux user | repair exact ownership |
| base Python | apt-managed `python3` | install venv via apt |
| direct venv | `.venv/bin/python` works | inspect creation output |
| activation | PATH and `VIRTUAL_ENV` point local | use Bash source syntax |
| pip owner | location is under `.venv` | use interpreter-bound pip |
| first script | reports Linux and `.venv` | fix command/path owner |
| source control | `.venv/` is ignored | repair `.gitignore` |
| re-entry | new shell reactivates same environment | follow return workflow |
## Windows WSL Python Setup Step 2 completion gate
Step 2 is complete only when:
1. The intended Store-installed Ubuntu distribution starts under the normal Step 1 user.
2. `~/projects/hello-python` exists in the Linux filesystem and is user-owned.
3. Ubuntu’s verified `python3` creates `.venv` without sudo.
4. Direct `.venv/bin/python` reports a project prefix distinct from its base prefix.
5. `source .venv/bin/activate` makes `python` and `python -m pip` resolve inside `.venv`.
6. `hello.py` runs as Linux through the environment both activated and by direct path.
7. Deactivation restores Ubuntu’s base command resolution, and reactivation works in a new shell.
8. `.venv/` and generated caches are excluded from source control.
9. No Windows interpreter, Windows activation script, `/mnt/c` project environment, global pip, or root-owned project state is involved.
Run final evidence inside Ubuntu from the project root:
```bash
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 hello.py
```
The next keyword should be **Windows WSL Python Setup Step 3**: verify package-index configuration, install one justified dependency through `.venv/bin/python -m pip`, prove distribution/import ownership, record direct versus transitive dependencies, and recreate them in a second clean Linux environment.
**Windows WSL Python Setup Step 2 succeeds when the Ubuntu user owns a Linux-filesystem project whose `.venv/bin/python` and pip are independently proven, safely ignored, and reproducible without sudo or any Windows virtual-environment artifact.**
**Windows WSL Python Setup Step 3 is to install, verify, record, and cleanly reproduce one third-party dependency inside the Ubuntu project `.venv`.** The Microsoft Store Ubuntu system Python remains owned by apt; Windows Python remains separate; every pip operation is bound to `.venv/bin/python`.
This tutorial uses the `requests` distribution because it has a clear import and transitive dependencies. The goal is dependency provenance and reproducibility, not internet programming. The functional test constructs and prepares a request locally without sending customer data or depending on a live service.
| Surface | Required proof | Unsafe shortcut |
|---|---|---|
| interpreter | path under project `.venv` | global/system Python |
| pip | invoked as `python -m pip` | bare or `sudo pip` |
| configuration | sources shown by `pip config debug` | hidden index override |
| package identity | metadata plus import path | trusting import success alone |
| dependency graph | direct versus transitive known | copying names blindly |
| consistency | `pip check` passes | ignoring resolver warnings |
| record | intent and tested snapshot | undocumented environment |
| recreation | fresh `.venv-check` passes | copying `.venv` |
## Re-enter the Step 2 project
From PowerShell, launch the exact distro found by `wsl --list --verbose`, then inside Ubuntu:
```bash
cd ~/projects/hello-python
source .venv/bin/activate
pwd
python -c "import sys; print(sys.executable)"
python -m pip --version
python hello.py
```
The executable and pip location must be under `/home//projects/hello-python/.venv`. If either reports `/usr`, `$HOME/.local`, `/mnt/c`, a Windows `.exe`, or another project, stop and repair Step 2. Every `python -c` command here is one complete physical line.
Confirm ownership and a clean baseline:
```bash
stat -c 'owner=%U mode=%A path=%n' . .venv
python -m pip check
git status --short 2>/dev/null || true
```
No package installation in this project requires sudo. Root-owned files indicate an earlier ownership mistake, not a reason to keep escalating.
## Inspect pip before contacting an index
Pip behavior can come from global, user, site/virtual-environment configuration, environment variables, and command options. Inspect effective sources:
```bash
python -m pip config debug
python -m pip config list -v
env | grep '^PIP_' || true
```
Review index URLs, trusted-host settings, certificate paths, proxy behavior, timeouts, and configuration-file locations. Redact credentials before sharing output. A URL containing a token/password must never enter source control, screenshots, shell history, or support tickets.
The normal public simple index uses HTTPS. On a managed network, use the approved private index, proxy, and enterprise CA configuration. Do not add `--trusted-host`, change to HTTP, disable certificate verification, or combine public/private indexes casually; those shortcuts create interception and dependency-confusion risks.
Check pip identity and supported tags:
```bash
python -m pip --version
python -m pip debug --verbose
```
The verbose output can be large; use it locally to diagnose platform/ABI wheel selection. WSL Ubuntu needs Linux-compatible artifacts, not Windows wheels.
## Inspect the intended distribution
Ask pip for available release information without installing:
```bash
python -m pip index versions requests
```
Treat names as a security boundary. Confirm spelling and the official project documentation/repository. Typo-squatting packages can imitate popular names. Do not choose a version merely because it is newest; an existing project should follow its declared compatibility and lock policy.
For this fresh tutorial, install the direct dependency through the environment interpreter:
```bash
python -m pip install requests
```
Read the complete plan: selected version, downloads/cache, dependencies, artifact types, index host, and final status. Do not paste version numbers from this page; capture what the customer actually resolved today.
Immediately verify consistency:
```bash
python -m pip check
```
## Prove distribution metadata
The installable distribution name and import-package name happen to match for requests, but that is not universal. Inspect installed metadata:
```bash
python -m pip show requests
python -c "from importlib.metadata import metadata, version; print(version('requests')); print(metadata('requests')['Name'])"
```
`pip show` must report a location inside `.venv`. `importlib.metadata` reads installed distribution metadata rather than a module attribute that could be absent or misleading.
Inspect the dependency relationship:
```bash
python -m pip show requests | sed -n '/^Requires:/p'
python -m pip list
```
Requests is the direct tutorial choice. Packages installed because it requires them are transitive. Do not copy every transitive name into the human intent file; the resolver/lock or tested snapshot records the concrete graph.
## Prove import ownership
Run:
```bash
python -c "import requests; print(requests.__file__)"
python -c "import requests; print(requests.__version__)"
```
The module file must be under the project `.venv`, not the working directory, `/usr/lib`, `$HOME/.local`, `/mnt/c`, or a Windows path. If it resolves to `~/projects/hello-python/requests.py` or `requests/`, a local file is shadowing the distribution.
Search for common shadows before renaming anything:
```bash
find . -maxdepth 2 \( -name 'requests.py' -o -name 'requests' \) -print
```
Never delete a source file just because its name conflicts; inspect Git status/content, rename deliberately, and rerun imports/tests.
## Test functionality without a live request
Create `dependency_probe.py` using `nano`:
```python
from __future__ import annotations
import requests
def main() -> None:
request = requests.Request(
"GET",
"https://example.invalid/status",
params={"source": "wsl-step3"},
)
prepared = request.prepare()
print(f"method={prepared.method}")
print(f"host={prepared.url.split('/')[2]}")
print(f"module={requests.__file__}")
if __name__ == "__main__":
main()
```
Run:
```bash
python dependency_probe.py
```
It should prepare a GET request and display the `.venv` module location without network I/O. `.invalid` is reserved for examples and should not resolve. Do not turn an installation test into an uncontrolled call carrying customer data.
## Record direct intent
Create `requirements.in`:
```text
requests
```
This tutorial intent file says what the application directly needs, but plain pip does not treat `.in` specially. Mature projects may instead use `pyproject.toml`, dependency groups, pip-tools, uv, Poetry, or another established lock workflow. Use one authoritative system rather than parallel declarations.
Do not add an arbitrary upper/lower bound without a compatibility reason. If policy requires exact direct pins, document how upgrades/security fixes are reviewed.
## Capture the tested environment
For this beginner tutorial, capture the complete installed snapshot:
```bash
python -m pip freeze > requirements.txt
```
Review it:
```bash
sed -n '1,120p' requirements.txt
python -m pip check
```
`requirements.txt` records direct and transitive distributions present in this environment. It is a reproduction artifact, not a substitute for explaining intent. Do not hand-edit transitive versions to make resolution green without retesting the whole graph.
Check for environment-specific editable paths, local file URLs, credentials, internal hosts, or indexes before committing. A freeze made from a contaminated environment faithfully records contamination.
## Reproduce in a clean Linux environment
Create a second disposable environment beside `.venv`:
```bash
python3 -m venv .venv-check
.venv-check/bin/python -m pip install -r requirements.txt
.venv-check/bin/python -m pip check
.venv-check/bin/python dependency_probe.py
```
This direct invocation avoids nested activation confusion. The probe’s module path must point inside `.venv-check`, proving that source plus declarations recreate the dependency without borrowing from `.venv` or user/global packages.
Compare distributions:
```bash
.venv/bin/python -m pip freeze > /tmp/step3-working.txt
.venv-check/bin/python -m pip freeze > /tmp/step3-check.txt
diff -u /tmp/step3-working.txt /tmp/step3-check.txt
```
No diff is expected for this simple snapshot. Temporary comparison files can be removed later after their exact paths are verified; they contain package inventory and may be sensitive in private projects.
## Exclude both environments
Add `.venv-check/` to `.gitignore` alongside `.venv/`:
```gitignore
.venv/
.venv-check/
__pycache__/
*.py[cod]
```
If Git is active:
```bash
git check-ignore -v .venv/bin/python .venv-check/bin/python
git status --short
```
Source (`hello.py`, `dependency_probe.py`), reviewed dependency declarations, and configuration belong in version control. Environment directories, caches, secrets, and user-specific pip configuration do not.
## Understand cache versus installed state
Inspect cache location/health:
```bash
python -m pip cache dir
python -m pip cache info
```
Pip’s cache can accelerate downloads/builds; it is not the installed environment or dependency declaration. A cache hit is not evidence of provenance or correctness. Do not commit the cache or copy it as `.venv` recovery.
Clear it only for a diagnosed cache corruption with reviewed scope. Repeated cache deletion hides resolver/index problems and increases network use.
## Safe uninstall and rollback
Before removing a package, inspect whether other installed distributions require it. In this tutorial, removing the direct `requests` package does not automatically promise to remove all now-unused transitive packages.
The safest rollback for a disposable environment is recreation from the prior reviewed requirements/lock. Do not uninstall Ubuntu’s apt-managed `python3-requests` to manipulate this venv, and never use sudo pip.
Keep package-manager boundaries clear: apt owns Ubuntu system packages; pip inside `.venv` owns project distributions; Windows package managers own Windows Python. Similar names across layers do not imply shared state.
## Troubleshooting
**Externally managed environment error.** The wrong interpreter/pip is active. Verify `sys.executable`; activate `.venv` or use `.venv/bin/python -m pip`. Do not use `--break-system-packages`.
**Permission denied during install.** Check project/environment ownership and filesystem path. Pip inside a user-owned `.venv` needs no sudo.
**TLS/certificate failure.** Verify time, proxy, approved CA bundle and index URL. Do not disable verification or use trusted-host as a blanket bypass.
**Name resolution/proxy failure.** Separate DNS, proxy authentication, firewall, VPN and repository availability. Redact credentials from diagnostics.
**No compatible distribution.** Check Python version, `uname -m`, supported tags, package releases and wheel/source-build requirements. Do not download a Windows wheel into Ubuntu.
**Build fails for a source distribution.** Inspect build-isolation output and official build prerequisites. Add Ubuntu development packages only when justified; do not install a random compiler bundle blindly.
**Import works outside but not inside `.venv`.** The package is global/user-installed, which Step 3 intentionally rejects. Install it through the project interpreter and declare it.
**Import path points to the project.** Resolve local-module shadowing. Inspect before renaming/deleting.
**Clean recreation resolves different versions.** The declaration is not sufficiently locked, an artifact became unavailable, platform markers differ, or index configuration changed. Compare logs/config and choose a reviewed locking policy.
**Requirements include private paths or tokens.** Do not commit. Remove the unsafe origin, rebuild from approved sources, then regenerate/review.
## What not to do in WSL Step 3
- Do not run pip through `/usr/bin/python3`, sudo, `--user`, or `--break-system-packages`.
- Do not mix Windows wheels/environments with Ubuntu.
- Do not disable TLS or signature checks to fix connectivity.
- Do not publish private index/proxy credentials.
- Do not trust a successful import without inspecting its path.
- Do not treat every transitive package as direct intent.
- Do not call an external production API as an install test.
- Do not copy `.venv`; recreate from reviewed declarations.
- Do not commit environments or caches.
- Do not overwrite an established project’s lock workflow with tutorial files.
| Step 3 gate | Pass condition | If it fails |
|---|---|---|
| project interpreter | executable under `.venv` | return to Step 2 |
| pip configuration | approved index/TLS/proxy | repair trust source |
| install | environment pip succeeds | inspect resolver/build output |
| metadata | name/version/location known | wrong environment/distribution |
| import | file under `.venv` | fix shadow/global leak |
| consistency | `pip check` passes | resolve graph conflict |
| records | intent plus reviewed snapshot | repair declaration policy |
| clean rebuild | `.venv-check` reproduces | find hidden dependency |
| source control | environments/caches ignored | fix ignore rules |
## Step 3 completion gate
Step 3 is complete only when the active Ubuntu project interpreter owns pip; configuration reveals only approved package sources; requests installs without sudo or system-Python changes; distribution metadata and the imported module both point into `.venv`; the no-network probe passes; `pip check` reports consistency; direct intent and the tested snapshot are reviewed; `.venv-check` recreates the same graph and runs the probe; and both generated environments remain outside source control.
Final evidence:
```bash
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python -m pip config debug
python -m pip show requests
python -c "import requests; print(requests.__file__)"
python -m pip check
.venv-check/bin/python dependency_probe.py
```
The next keyword should be **Windows WSL Python Setup Step 4**: connect VS Code to the Ubuntu distribution using its WSL remote environment, open the Linux project rather than a UNC/Windows copy, select `.venv/bin/python`, and prove terminal, Run, Debug, analysis, and tests share the same Linux interpreter.
**Windows WSL Python Setup Step 3 succeeds when a trusted dependency is installed only through the Linux project `.venv`, its metadata/import/graph are proven, and reviewed declarations rebuild it in a second clean Ubuntu environment.**
**Windows WSL Python Setup Step 4 is to open the Step 2–3 Linux project in a genuine VS Code WSL remote window, select its `.venv/bin/python`, and prove that editing, IntelliSense, terminal execution, Run, and Debug all occur inside Ubuntu.** Windows hosts the VS Code interface; the VS Code Server, extensions, source, Git, Python, and debugger operate in the Microsoft Store Ubuntu distribution.
| Surface | Correct owner | Proof |
|---|---|---|
| VS Code UI | Windows application | signed trusted installation |
| remote session | intended Ubuntu distro | WSL status indicator |
| project folder | `/home/.../hello-python` | remote Explorer path |
| Python extension | installed in WSL | remote extension badge |
| interpreter | `.venv/bin/python` | status bar and executable |
| terminal | Ubuntu shell | `uname`, `pwd`, Python path |
| Run/Debug | Linux project venv | probe and breakpoint agree |
| imports | `.venv` site-packages | requests module path |
## Prove the command-line baseline
From PowerShell, inspect the distro and launch it by exact registered name:
```powershell
wsl --list --verbose
wsl ~ --distribution Ubuntu
```
Inside Ubuntu:
```bash
cd ~/projects/hello-python
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python -m pip check
python dependency_probe.py
```
The executable must end in `/hello-python/.venv/bin/python`; the dependency probe must import requests from that environment. Fix Steps 1–3 before involving an editor if this baseline fails.
## Install the trusted Windows-side components
Install stable Visual Studio Code for Windows from Microsoft’s official channel according to customer software policy. In the Windows VS Code Extensions view, verify publisher identity and install Microsoft’s **WSL** extension. Do not install look-alike extensions based only on name/icon/download count.
The remote model has two extension locations. The WSL extension connects the Windows client to Ubuntu. Language/runtime extensions such as Microsoft Python must be available **in the WSL remote**, where Linux code and Python run. A Windows-only Python extension cannot inspect the remote Linux environment correctly.
Do not install another Python inside Windows or Ubuntu merely for VS Code. The editor must consume the `.venv` already proven by commands.
## Open from Ubuntu with `code .`
From the Ubuntu project root, after VS Code plus WSL extension are installed:
```bash
cd ~/projects/hello-python
code .
```
The first connection may install/start a VS Code Server under the Ubuntu user. Allow approved network access and wait for completion. Do not run `sudo code .`; a root-owned server/project creates privilege and ownership problems.
In the new window, verify the lower-left remote indicator names WSL/Ubuntu. Open a new integrated terminal and run:
```bash
uname -s
pwd
whoami
```
Expected: Linux, `/home//projects/hello-python`, and the normal Ubuntu user.
Opening `\\wsl.localhost\Ubuntu\home\...` through Windows **File > Open Folder** can expose files to an ordinary local window, but it does not prove remote execution. Use `code .` from Ubuntu or **WSL: Connect to WSL** followed by the Linux folder.
## Workspace Trust before execution
VS Code may request Workspace Trust. Review source, tasks, debug configurations, settings, notebooks, and extension recommendations before trusting. A workspace can cause code execution through tasks, debugging, test discovery, language servers, package build hooks, or terminal profiles.
Do not trust a downloaded repository just to remove restricted-mode warnings. For this customer-owned tutorial directory, inspect `git status`, files, and `.vscode` first. Trust applies to code risk, not only file location.
## Install Python support in WSL
Open Extensions while the WSL window is active. Install Microsoft’s Python extension **in WSL: Ubuntu** when offered. Pylance/Python Environments components may be installed as dependencies/current companion extensions; verify publishers and remote placement.
The Extensions view distinguishes Local/Windows from WSL. A gear/menu saying “Install in WSL” means the extension is currently only local. Avoid duplicative third-party run-code extensions until the built-in Python workflow is proven.
## Select the existing project interpreter
Open `hello.py`, select the interpreter indicator in the status bar, or run **Python: Select Interpreter** from `Ctrl+Shift+P`. Choose the workspace environment ending in:
```text
/home//projects/hello-python/.venv/bin/python
```
If it is missing, run **Python Environments: Refresh All Environment Managers**. If manual selection is necessary, browse to `.venv/bin/python` inside the remote Linux folder.
Reject these candidates:
- `/usr/bin/python3` — Ubuntu base, not the project environment.
- `C:\...\python.exe` or `pythonw.exe` — Windows interpreter.
- `/mnt/c/.../.venv/...` — project on the wrong filesystem.
- another project’s `.venv`.
- a deleted/broken cached environment.
Interpreter selection controls Python language features, Run/Debug defaults, test discovery, and new Python terminals. It does not retroactively alter an already-open shell; create a fresh terminal after selection.
## Prove a new integrated terminal
Close old terminals, create a new terminal, and run:
```bash
printf 'VIRTUAL_ENV=%s\n' "${VIRTUAL_ENV-}"
command -v python
python -c "import sys; print(sys.executable)"
python -c "import requests; print(requests.__file__)"
python -m pip --version
```
All executable/module/pip paths must be under the project `.venv`. Auto-activation may appear as a visible `source` command or shell integration depending on current extension settings. The outcome matters more than prompt decoration.
If activation is off by policy, direct `.venv/bin/python` remains authoritative. Do not edit `.bashrc` for global project activation just to make the terminal green.
## Create a cross-surface probe
Create `step4_probe.py`:
```python
from __future__ import annotations
import os
import platform
import sys
from pathlib import Path
import requests
def main() -> None:
print(f"platform={platform.system()}")
print(f"executable={sys.executable}")
print(f"prefix={sys.prefix}")
print(f"cwd={Path.cwd()}")
print(f"requests={requests.__file__}")
print(f"wsl={bool(os.getenv('WSL_DISTRO_NAME'))}")
if __name__ == "__main__":
main()
```
Run in terminal:
```bash
python step4_probe.py
```
Expected: platform Linux, executable/prefix and requests under `.venv`, cwd under `/home`, and WSL true. The probe prints no secrets and makes no network call.
## Prove Run Python File
With `step4_probe.py` active, choose **Run Python File in Terminal** from the Python extension. Compare its output to the manual terminal run. It must use the same Linux executable and project path.
Avoid generic **Run Code** commands contributed by unrelated extensions; they can use hard-coded `python`, a different working directory, or a Windows executor. Establish ownership before adding alternate runners.
## Prove debugging
Set a breakpoint on the first print in `main`, press F5, and choose **Python Debugger: Python File** if prompted. When execution pauses, evaluate in Debug Console:
```python
sys.executable
platform.system()
requests.__file__
str(Path.cwd())
```
Results must match the remote `.venv`, Linux, environment site-packages, and Linux project directory. Continue and confirm normal completion.
The default debugger uses the selected interpreter. Do not hard-code a personal `/home/name/...` interpreter in `launch.json`. If a project-specific launch configuration is later needed, keep it relative/portable and review it as executable configuration.
## Language analysis and imports
Open `dependency_probe.py`. `import requests` should resolve without a missing-import warning, and Go to Definition should lead into the remote `.venv` package. Hover information should reflect the installed package.
Editor analysis can be stale while runtime is correct. First verify selected environment, remote extension location, workspace root, and refresh environment discovery. Restart the language server/window only after gathering those facts.
Runtime remains authoritative. A clean editor does not prove that `python dependency_probe.py` works; a passing runtime does not prove IntelliSense uses the same environment. Step 4 requires both.
## Settings and portability review
Inspect Workspace settings JSON and `.vscode`:
```bash
find .vscode -maxdepth 2 -type f -print 2>/dev/null || true
git status --short
```
Do not commit:
- absolute personal home paths;
- Windows interpreter paths;
- secrets in `.env`, settings, tasks, or launch configurations;
- a duplicate environment manager policy;
- extension-generated caches/server files.
A workspace-local `.venv` is normally auto-discovered, so no interpreter path file may be needed. If team settings are useful, ensure they are relative, reviewed, and valid for every contributor’s remote folder.
## Git must run in Ubuntu
From the integrated terminal:
```bash
command -v git
git status --short
git config --show-origin --list
```
The project’s Git operations should execute in Ubuntu against Linux files. Review identity and credential-helper origins without publishing tokens. Windows and WSL Git configurations are separate unless deliberately integrated.
Do not initialize a second repository from Windows or operate simultaneously on the same worktree through competing Windows/WSL Git processes.
## Windows-versus-remote extension architecture
The Windows client renders UI. The remote server executes workspace extensions and terminal processes inside Ubuntu. Extensions with native binaries need Linux builds remotely. Installing only on Windows can produce missing commands; installing every UI extension remotely wastes resources and expands trust.
Use the Extensions view location labels to decide intentionally. Keep WSL, VS Code, and extensions updated through approved channels, reviewing material changes. Never manually copy the remote server from an unknown source.
## Terminal, Run, Debug, analysis matrix
Capture the five facts—platform, executable, prefix, cwd, requests path—from terminal, Run, and Debug. They should be identical except harmless launcher details. IntelliSense should resolve against the same environment.
If only one surface differs, fix its owner rather than recreating `.venv` immediately. Old terminals need reopening; Run commands may come from another extension; debug configs may override Python/cwd; multi-root workspaces can assign different interpreters; notebooks have a separate kernel selector.
## Security boundaries
Remote development executes repository code inside Ubuntu with that user’s access to Linux files, mounted Windows drives, network, agents, and credentials. Least privilege still matters. Do not run VS Code or its server as root.
Review tasks and `launch.json` before execution. Do not pass secrets as literal command arguments or commit `.env`. Do not expose debug ports broadly. WSL localhost forwarding is convenient but does not make an unauthenticated development service safe.
Extension supply chain matters on both sides. Restrict marketplace/publishers according to enterprise policy. Disable/remove an unexplained extension rather than granting broader permissions to make it function.
## Troubleshooting
**`code` not found in Ubuntu.** Confirm Windows VS Code and official WSL extension installation, reopen terminal, and use VS Code’s documented shell integration. Do not install an unrelated Linux GUI package called code blindly.
**Window is local, not WSL.** Check remote indicator. Reopen from Ubuntu with `code .` or run WSL connect/reopen command.
**Wrong distro opens.** Use the remote selector to connect to the exact registered distro, or launch `code .` from that distro. Do not change the global default casually.
**`.venv` is not listed.** Verify `.venv/bin/python`, project root, remote extension placement, and refresh environment managers; manually select the Linux executable if needed.
**Terminal uses `/usr/bin/python3`.** Close it after selecting `.venv`, create a new Python terminal, or activate explicitly. Do not install requests globally.
**Run works but terminal fails.** Compare activation and executable. Selection can control Run while an old terminal retains prior PATH.
**Terminal works but Run uses Windows.** The window is local or a third-party runner owns the command. Use the Microsoft Python Run command in a WSL window.
**Debug uses another interpreter.** Inspect `launch.json` for a `python` override and workspace-folder selection. Remove personal paths after review.
**Pylance says requests missing.** Confirm WSL-side extension, selected environment, module location, workspace root, and refresh/reload after evidence collection.
**Server install fails.** Check Ubuntu supported libraries, disk space, DNS/proxy/TLS and permissions. Do not run as root or disable certificate checks.
**Files appear under `/mnt/c`.** Wrong folder/workspace was opened. Reopen `/home//projects/hello-python`; do not move `.venv`.
## What not to do in WSL Step 4
- Do not open the UNC path in an ordinary local window and call it remote development.
- Do not select Windows Python, `pythonw.exe`, `/usr/bin/python3`, or another project environment.
- Do not install packages globally to silence editor imports.
- Do not run `sudo code .` or a root-owned VS Code Server.
- Do not hard-code personal interpreter/cwd paths in committed settings.
- Do not trust arbitrary workspaces or extension publishers.
- Do not use a generic Run Code command before proving its executor.
- Do not commit secrets, `.venv`, remote server files, or caches.
- Do not treat terminal success as proof that Debug/analysis agrees.
| Step 4 gate | Pass condition | If it fails |
|---|---|---|
| remote window | WSL Ubuntu indicator visible | reopen remotely |
| folder | Linux `/home/...` project | close local/UNC workspace |
| extensions | Python available in WSL | install remote copy |
| selection | `.venv/bin/python` | refresh/select exact path |
| terminal | Linux and project venv | new terminal/activate |
| Run | probe matches terminal | use Python runner |
| Debug | breakpoint values match | repair launch config |
| analysis | requests resolves in `.venv` | refresh remote language server |
| security | trusted code/extensions, no root/secrets | stop and review |
## Step 4 completion gate
Step 4 is complete only when the window is explicitly connected to the intended Ubuntu distro; the remote folder is the Linux project; Microsoft Python support runs remotely; `.venv/bin/python` is selected; a new integrated terminal proves Linux/project environment ownership; Run Python File produces the same probe; Debug pauses and reports the same executable/import/cwd; analysis resolves requests from `.venv`; and no personal path, secret, root server, Windows interpreter, or ordinary UNC workspace is used.
Final evidence in the VS Code integrated terminal:
```bash
uname -s
pwd
python -c "import sys; print(sys.executable)"
python -c "import requests; print(requests.__file__)"
python -m pip check
python step4_probe.py
```
The next keyword should be **Windows WSL Python Setup Step 5**: diagnose mismatched Windows/WSL launch hosts, terminal profiles, `python.exe` interoperability, `pythonw.exe`, UNC/local windows, and stale interpreter overrides using a cross-surface ownership matrix.
**Windows WSL Python Setup Step 4 succeeds when VS Code’s Windows interface is merely the client while Ubuntu owns the folder, extensions, terminal, Run, Debug, analysis, and the one proven `.venv/bin/python`.**
**Winning Ticket** is **a sparse subnetwork identified as capable of matching dense-model performance when trained properly** - It is the practical target produced by lottery-ticket style methods.
**What Is Winning Ticket?**
- **Definition**: a sparse subnetwork identified as capable of matching dense-model performance when trained properly.
- **Core Mechanism**: Specific mask patterns preserve critical pathways that support strong optimization.
- **Operational Scope**: It is applied in model-optimization workflows to improve efficiency, scalability, and long-term performance outcomes.
- **Failure Modes**: Ticket transfer across domains can fail when data distributions change.
**Why Winning Ticket 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 latency targets, memory budgets, and acceptable accuracy tradeoffs.
- **Calibration**: Re-validate tickets under target-domain data and retraining protocols.
- **Validation**: Track accuracy, latency, memory, and energy metrics through recurring controlled evaluations.
Winning Ticket is **a high-impact method for resilient model-optimization execution** - It represents a compact high-value candidate for efficient retraining.
**Winning Tickets** are the **specific sparse sub-networks identified by the Lottery Ticket Hypothesis** — sub-networks that, when trained from their original random initialization, achieve comparable performance to the full dense network.
**What Are Winning Tickets?**
- **Definition**: A mask $m$ over weights $ heta_0$ such that training $m odot heta_0$ achieves accuracy $geq$ training $ heta_0$ in $leq$ iterations.
- **Properties**:
- **Initialization Dependent**: The ticket only works with its *original* random init, not a new random init.
- **Transferable**: Tickets found on one task often transfer to related tasks.
- **Stable**: Late Rewinding (resetting to iteration $k$ instead of $0$) improves stability for large networks.
**Why They Matter**
- **Sparse Training**: If we can identify tickets early, we can train only the essential connections from the start.
- **Generalization**: Winning tickets often generalize better (fewer parameters = less overfitting).
- **Hardware**: Could enable training directly on edge devices if tickets are found cheaply.
**Winning Tickets** are **the diamonds in the rough** — proving that neural network training is really a search problem for the right sparse structure.
**WinoBias** is the **coreference-resolution bias benchmark that tests whether models rely on gender stereotypes when resolving ambiguous pronouns** - it measures fairness in occupation-gender association reasoning.
**What Is WinoBias?**
- **Definition**: Dataset of pronoun resolution examples designed to expose gendered occupational bias.
- **Task Structure**: Sentences contain occupation terms and pronouns where correct resolution may conflict with stereotype.
- **Evaluation Signal**: Performance gap between pro-stereotypical and anti-stereotypical cases.
- **Model Scope**: Applicable to language understanding and generation systems with coreference behavior.
**Why WinoBias Matters**
- **Stereotype Sensitivity**: Detects whether models default to biased gender assumptions.
- **Fairness Insight**: Highlights representational harms in linguistic reasoning tasks.
- **Mitigation Tracking**: Useful for measuring debiasing effect on pronoun resolution behavior.
- **Comparative Value**: Enables cross-model evaluation on a targeted bias mechanism.
- **Deployment Relevance**: Coreference bias can propagate into downstream application outputs.
**How It Is Used in Practice**
- **Gap Measurement**: Compare error rates across stereotype-consistent and stereotype-inconsistent sets.
- **Intervention Testing**: Re-evaluate after counterfactual augmentation and debias fine-tuning.
- **Holistic Assessment**: Combine with open-ended generation benchmarks for broader fairness coverage.
WinoBias is **a focused benchmark for gender stereotype effects in coreference reasoning** - pronoun-resolution disparity analysis provides a clear signal of fairness weaknesses in language models.
**WinoGender** is a diagnostic evaluation dataset designed to test **gender bias** in **coreference resolution** systems — specifically, whether models rely on **occupational stereotypes** when determining who a pronoun refers to.
**How WinoGender Works**
- **Sentence Template**: Each example contains two people (identified by occupation) and a pronoun that refers to one of them.
- **Stereotype Testing**: One occupation is stereotypically male (e.g., mechanic), another stereotypically female (e.g., nurse), and the correct referent is varied to test whether models follow stereotypes.
**Example Pairs**
- "**The mechanic** called **the nurse** because **he** needed help." → "he" = mechanic (stereotype-consistent)
- "**The mechanic** called **the nurse** because **he** was running late." → "he" = nurse (stereotype-inconsistent: nurse referred to as "he")
- An unbiased model should resolve both correctly based on **context**, not occupation stereotypes.
**Key Design Features**
- **720 Sentence Pairs**: Covering 60 occupations from Bureau of Labor Statistics data with real-world gender composition statistics.
- **Three Pronoun Conditions**: Male ("he/him"), female ("she/her"), and neutral ("they/them") versions of each template.
- **Matched Structure**: Sentences are identical except for the pronoun and which entity it refers to, isolating the effect of gender bias.
**What WinoGender Reveals**
- Models show **higher accuracy** when pronouns align with occupational stereotypes (e.g., "she" referring to a nurse, "he" referring to a doctor).
- **Accuracy drops** significantly when pronouns contradict stereotypes (e.g., "he" referring to a nurse).
- Performance gaps directly quantify the model's reliance on **gender stereotypes** rather than linguistic context.
**Related Benchmarks**: **WinoBias** (similar concept, larger dataset), **WinoGrande** (general commonsense, not bias-specific), and **WinoMT** (bias in machine translation).
WinoGender is referenced in major AI fairness papers and is part of standard **bias evaluation suites** for NLP models.
**Winograd Convolution** is **a fast convolution algorithm that reduces multiplications for small kernel sizes** - It accelerates common convolutions in many vision models.
**What Is Winograd Convolution?**
- **Definition**: a fast convolution algorithm that reduces multiplications for small kernel sizes.
- **Core Mechanism**: Input and filters are transformed, multiplied in reduced form, then inverse transformed.
- **Operational Scope**: It is applied in model-optimization workflows to improve efficiency, scalability, and long-term performance outcomes.
- **Failure Modes**: Numerical stability can degrade for certain precisions and kernel configurations.
**Why Winograd Convolution 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 latency targets, memory budgets, and acceptable accuracy tradeoffs.
- **Calibration**: Use precision-aware kernels and fallback paths for unstable parameter ranges.
- **Validation**: Track accuracy, latency, memory, and energy metrics through recurring controlled evaluations.
Winograd Convolution is **a high-impact method for resilient model-optimization execution** - It provides substantial speedups for suitable convolution regimes.
**Winograd Schema Challenge (WSC)** is a **commonsense reasoning benchmark consisting of pairs of sentences that differ by only one or two words, containing an ambiguous pronoun whose resolution resorts to world knowledge** — designed to be easy for humans but hard for machines.
**Example**
- **Sentence A**: "The trophy doesn't fit into the suitcase because **it** is too **large**." (It = Trophy).
- **Sentence B**: "The trophy doesn't fit into the suitcase because **it** is too **small**." (It = Suitcase).
- **Logic**: You must know physics (large things don't fit in small things) to resolve syntax.
**Why It Matters**
- **Turing Test Alternative**: Proposed by Hector Levesque as a better test of intelligence than the Turing Test.
- **Evaluation**: Standard benchmark for LLMs. GPT-4 scores >90%, effectively "solving" it, though smaller models struggle.
- **Selectional Restrictions**: Tests if models learn the physical/semantic constraints of verbs and adjectives.
**Winograd Schema Challenge** is **the "It" test** — a benchmark testing if AI has enough commonsense physics to resolve ambiguous pronouns.
**Winogrande** is the **large-scale, adversarially filtered commonsense reasoning benchmark** — a 44,000-example successor to the Winograd Schema Challenge (WSC) that was specifically designed to eliminate the annotation artifacts and statistical shortcuts that allowed models to achieve high scores on the original WSC without genuine commonsense reasoning.
**The Original Winograd Schema Challenge**
The Winograd Schema Challenge (WSC), proposed by Levesque et al. (2011), was designed as an alternative to the Turing Test. Each schema presents a sentence with an ambiguous pronoun that can only be resolved through commonsense reasoning:
"The trophy didn't fit in the suitcase because it was too big. What was too big?" → The trophy (not the suitcase).
"The trophy didn't fit in the suitcase because it was too small. What was too small?" → The suitcase (not the trophy).
The correct resolution requires knowing that "too big" makes the container the bottleneck and "too small" makes the container the limitation — a subtle inference requiring world knowledge about spatial containment.
The original WSC had only 273 examples — far too small for training neural networks and susceptible to memorization. More critically, models achieved high WSC accuracy by exploiting simple word co-occurrence statistics in training data rather than genuine reasoning.
**Winogrande's Design Innovations**
**Scale**: 44,000 examples created through crowdsourcing on Amazon Mechanical Turk — 160x more examples than the original WSC, enabling both training and evaluation at scale.
**Two-Blank Format**: Unlike WSC (which asks "what does the pronoun refer to?"), Winogrande uses a fill-in-the-blank format:
"Sarah was a much better athlete than Mary, so [_] often asked for advice."
Choices: (a) Sarah (b) Mary
Correct: (b) Mary — because better athletes are sought for advice, not the reverse.
**AFLite (Adversarial Filtering Lite)**: The key innovation. After crowdsourcing 60,000+ raw examples, AFLite automatically identifies and removes examples where simple statistical models (feature-based classifiers using word co-occurrence statistics) achieve high accuracy. Only examples that survive this filtering — those that require genuine reasoning rather than statistical shortcuts — remain in the final dataset.
AFLite process:
1. Train multiple simple classifiers on feature representations of all examples.
2. Identify examples where classifiers achieve high agreement (easy examples exploitable by statistics).
3. Remove easy examples iteratively until the remaining set cannot be solved by statistical models above chance.
4. Final dataset: ~44,000 examples where simple shortcuts fail.
**Task Format and Evaluation**
- **Input**: Sentence with a blank (_) and two noun phrase choices.
- **Output**: Select the choice that correctly fills the blank based on commonsense inference.
- **Metric**: Binary accuracy (random baseline: 50%).
- **Human performance**: ~94% accuracy (crowdworkers who did not create the examples).
- **Dataset splits**: Training sets of various sizes (xs: 160, s: 640, m: 2,558, l: 5,120, xl: 12,800, full: 40,398) to study data efficiency.
**Benchmark Results and Scaling**
| Model | Winogrande Accuracy |
|-------|-------------------|
| BERT-large | 73.9% |
| RoBERTa-large | 79.1% |
| GPT-3 (0-shot) | 70.2% |
| GPT-3 (few-shot) | 77.7% |
| UnifiedQA-11B | 84.9% |
| Human | 94.1% |
The persistent gap between model and human performance (even for very large models) demonstrates that Winogrande's adversarial filtering successfully created examples that require genuine reasoning.
**What Winogrande Tests**
Winogrande examples cluster into commonsense categories:
- **Social and Motivational**: "Because [_] was nervous, they spoke softly at the party." Requires understanding social dynamics.
- **Physical**: "The vase fell off the shelf because [_] was fragile." Physical causality.
- **Causal**: "The car started after [_] put in the key." Causal sequences.
- **Comparative**: "Amy is shorter than Beth, so [_] can fit in the small car more easily." Comparative reasoning.
**AFLite and the Shortcut Learning Problem**
Winogrande's most important contribution may be methodological: demonstrating that adversarial dataset filtering is a practical tool for creating harder, more genuine reasoning benchmarks. The AFLite algorithm showed:
- Standard crowdsourced datasets inevitably contain exploitable annotation artifacts.
- Simple classifiers can identify and remove these artifacts automatically.
- Models trained on AFLite-filtered data generalize better to novel examples than models trained on unfiltered data.
AFLite's approach has been applied to create harder variants of other benchmarks, making the methodology broadly influential beyond Winogrande itself.
**Winogrande in the Context of Larger Benchmarks**
Winogrande is included in:
- **BIG-Bench**: As one of 204 challenging tasks.
- **SuperGLUE-inspired evaluations**: Commonsense reasoning track.
- **LLM evaluation suites**: Standard component of evaluating GPT-4, Claude, Llama, and Gemini capabilities.
Winogrande is **the adversarially hardened reasoning test** — a fill-in-the-blank benchmark that uses automated filtering to eliminate statistical shortcuts, ensuring that high performance requires genuine commonsense inference rather than the exploitation of dataset-construction artifacts that plagued earlier WSC evaluations.
**WinoGrande** is **a benchmark for pronoun resolution and commonsense disambiguation in sentence contexts** - It is a core method in modern AI evaluation and safety execution workflows.
**What Is WinoGrande?**
- **Definition**: a benchmark for pronoun resolution and commonsense disambiguation in sentence contexts.
- **Core Mechanism**: It tests whether models can resolve ambiguous references using contextual reasoning.
- **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**: Bias artifacts or pattern shortcuts can distort true reasoning measurement.
**Why WinoGrande 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**: Use debiased evaluation and compare with complementary coreference tasks.
- **Validation**: Track objective metrics, compliance rates, and operational outcomes through recurring controlled reviews.
WinoGrande is **a high-impact method for resilient AI execution** - It probes subtle linguistic reasoning that simpler QA benchmarks may miss.
**WIP Cap** is **a limit on work-in-progress inventory allowed within a process or flow segment** - It controls congestion and stabilizes cycle-time behavior.
**What Is WIP Cap?**
- **Definition**: a limit on work-in-progress inventory allowed within a process or flow segment.
- **Core Mechanism**: Entry release is constrained once in-process count reaches predefined capacity thresholds.
- **Operational Scope**: It is applied in manufacturing-operations workflows to improve flow efficiency, waste reduction, and long-term performance outcomes.
- **Failure Modes**: Missing WIP enforcement allows runaway queues and unpredictable lead times.
**Why WIP Cap 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**: Set WIP caps from bottleneck capacity, variability, and target flow time.
- **Validation**: Track throughput, WIP, cycle time, lead time, and objective metrics through recurring controlled evaluations.
WIP Cap is **a high-impact method for resilient manufacturing-operations execution** - It is a direct control for maintaining manageable production flow.
Work-In-Progress (WIP) management controls the **number of wafer lots** actively moving through the fab at any time. The goal is to balance throughput against cycle time—too much WIP creates long queues and extended cycle times, while too little WIP starves tools and wastes capacity.
**Finding the Sweet Spot**
The ideal WIP level keeps **bottleneck tools busy** without creating excessive queuing everywhere else. This balance is critical because inventory sitting in queues costs money and extends delivery times.
**Key Metrics**
• **WIP turns**: Throughput divided by average WIP (higher is better)
• **X-factor**: Actual cycle time divided by raw process time (ideal = **1.0**, typical fab = **2-4**)
• **WIP-by-step report**: Shows where lots accumulate at each process step
**Management Approaches**
**CONWIP (Constant WIP)** releases new lots only when completed lots exit the fab. **Push systems** release on schedule regardless of downstream status. **Pull systems** release based on actual downstream capacity. Many fabs also set **WIP caps** per process area to prevent congestion, and operations teams conduct daily WIP reviews to adjust priorities based on current conditions.
**WIP management strategies** is the **set of policies used to control how much work is released, where it accumulates, and how it flows through bottleneck resources** - strategy quality strongly determines cycle time and throughput stability.
**What Is WIP management strategies?**
- **Definition**: Operational frameworks such as push, pull, CONWIP, and bottleneck-focused release control.
- **Primary Objective**: Keep WIP at levels that maximize output without creating excessive queue delay.
- **Policy Scope**: Includes release pacing, queue caps, priority rules, and starvation prevention logic.
- **System Dependency**: Requires accurate real-time WIP and capacity visibility.
**Why WIP management strategies Matters**
- **Cycle-Time Performance**: Excess WIP drives long waits; insufficient WIP causes idle bottlenecks.
- **Throughput Stability**: Controlled release reduces flow oscillation and congestion waves.
- **Delivery Predictability**: Balanced WIP improves schedule adherence.
- **Cost Control**: Lower unnecessary WIP reduces inventory carrying and expedite cost.
- **Scalable Operations**: Robust strategies are essential in complex high-mix fabs.
**How It Is Used in Practice**
- **Release Governance**: Set WIP caps and release gates by route and bottleneck capacity.
- **Feedback Loops**: Adjust release rates using real-time queue and cycle-time signals.
- **Policy Validation**: Simulate and compare strategy outcomes before full production rollout.
WIP management strategies is **a central lever for fab flow optimization** - disciplined release and queue-control policies reduce congestion, protect throughput, and improve cycle-time predictability.
**WIP optimization** is the **quantitative tuning of in-fab inventory levels to balance throughput, cycle time, and utilization under variability** - it seeks the operating point where total performance and cost are best aligned.
**What Is WIP optimization?**
- **Definition**: Analytical process for selecting target WIP levels by bottleneck, route, and product mix.
- **Tradeoff Basis**: Higher WIP can protect utilization but increases waiting and cycle-time inflation.
- **Model Inputs**: Arrival variability, process times, setup effects, downtime patterns, and dispatch policies.
- **Output Metrics**: Optimal queue targets, release rates, and expected cycle-time performance bands.
**Why WIP optimization Matters**
- **Throughput-Cycle Balance**: Prevents overloading that causes extreme queue growth near high utilization.
- **Lead-Time Reliability**: Optimized WIP lowers cycle-time variance and improves due-date confidence.
- **Cost Efficiency**: Reduces unnecessary inventory exposure while maintaining output.
- **Bottleneck Protection**: Keeps constraint tools fed without saturating non-bottleneck areas.
- **Operational Resilience**: Better WIP posture absorbs routine variability with less disruption.
**How It Is Used in Practice**
- **Queueing Analysis**: Use simulation and Little's Law based models to evaluate candidate WIP targets.
- **Dynamic Adjustment**: Re-tune targets by demand regime, maintenance windows, and product mix changes.
- **Performance Tracking**: Monitor achieved throughput, WIP age, and cycle-time against optimized setpoints.
WIP optimization is **a high-impact operations science discipline** - correctly tuned WIP levels are essential for sustainable throughput, shorter cycle time, and efficient fab economics.
WIP (Work in Progress) refers to the total inventory of wafers currently being processed within the semiconductor fab — encompassing all wafers at every stage of manufacturing from lot start through final test, including wafers actively being processed in tools, wafers waiting in queues, wafers in stockers and transport, and wafers on hold for engineering review. WIP management is a critical production metric because it directly impacts fab cycle time, throughput, tool utilization, and manufacturing cost. Little's Law provides the fundamental relationship: Cycle Time = WIP / Throughput, meaning for a given throughput level, higher WIP results in longer cycle time (wafers spending more time waiting in queues rather than being processed). WIP levels are managed at multiple granularities: total fab WIP (total wafer count — a major factory metric, typically measured in wafer starts per week or month), area WIP (inventory within specific process areas — lithography, etch, deposition, implant), tool group WIP (wafers queued for specific equipment groups), and lot-level WIP (tracking individual lots through the process flow). Optimal WIP balances competing objectives: too little WIP risks tool starvation (machines idle because no wafers are available — reducing throughput), while too much WIP increases cycle time (wafers spend excessive time in queues — increasing inventory cost and time-to-market). The relationship is nonlinear — as WIP increases beyond the optimal point, cycle time increases dramatically while throughput plateaus. Fab scheduling systems actively manage WIP through dispatch rules that prioritize lots based on factors including: due date urgency, process step criticality, hot lot priority, tool availability, and WIP balance targets. Advanced fab management uses WIP targets by technology node, product family, and process area to maintain optimal flow. Typical advanced logic fabs maintain WIP levels supporting 2-4 weeks of cycle time for commodity products and under 2 weeks for priority products.
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.
embedded bridge, EMIB, local silicon interconnect, fan out bridge, cowos
Chip-on-Wafer-on-Substrate and 2.5D advanced packaging technologies represent the foundational heterogeneous integration architectures that interconnect massive compute logic dies and High-Bandwidth Memory stacks onto a unified high-density silicon interposer. As artificial intelligence accelerators, hyperscale graphics processors, and datacenter server chips reach the physical optical lithography reticle limit (approximately 858mm2 for single-exposure scanner fields), monolithic silicon scaling can no longer accommodate the billions of transistors and wide memory interfaces required for frontier AI models. CoWoS resolves this physical limit by stitching multiple compute chiplets and up to twelve HBM3/HBM4 memory cubes onto a multi-reticle passive or active silicon interposer ($> 3.3\times$ reticle size) containing fine-pitch sub-micron redistribution layers (RDL) and Through-Silicon-Vias (TSVs), delivering over 4.8 terabytes per second of memory bandwidth with minimal latency.
**Silicon interposers break the monolithic reticle limit through high-precision optical lithography stitching.** Standard photolithography scanners have a maximum exposure field size of $26\text{ mm} \times 33\text{ mm}$ ($858\text{ mm}^2$). Because leading-edge generative AI processors require thousands of square millimeters of silicon, 2.5D CoWoS fabricates massive silicon interposers spanning 3 to 4 full reticle fields ($> 2,800\text{ mm}^2$) by stitching adjacent exposure fields with sub-micron alignment accuracy ($< 50\text{ nm}$ stitching overlay error). The resulting continuous interposer substrate provides millions of sub-micron copper redistribution lines ($L/S \le 0.4/0.4\ \mu\text{m}$) that route parallel wide buses between compute chiplets and High-Bandwidth Memory stacks.
**Through-silicon vias deliver vertical power delivery and low-latency signal distribution through the interposer.** Silicon interposers incorporate dense arrays of Through-Silicon-Vias (TSVs) etched through $100\ \mu\text{m}$ thinned silicon wafers using the Deep Reactive Ion Etching (DRIE) Bosch process. Lined with dielectric insulation ($\text{SiO}_2$) and barrier layers ($\text{TaN}$), the TSVs are filled with electroplated copper ($D_{\text{TSV}} \approx 10\ \mu\text{m}$, $AR \approx 10:1$). These vertical vias provide low-resistance power distribution ($V_{\text{DD}}$ and $V_{\text{SS}}$) directly from the organic package substrate to the active compute dies, minimizing $IR$ drop and signal degradation:
$$
BW_{\text{total}} = \sum_{i=1}^{M} N_{\text{pins},i} \cdot \text{DataRate}_i \ge 4.8\ \text{TB/s}.
$$
**Microbump assembly and capillary underfill ensure mechanical compliance and thermal reliability.** The active compute chiplets and HBM memory cubes are mounted face-down onto the silicon interposer using lead-free microbumps ($\text{Cu}$ pillar with $\text{Sn-Ag}$ solder caps) at fine pitches ($25\text{--}40\ \mu\text{m}$). Following thermal compression bonding, liquid Capillary Underfill (CUF) or Non-Conductive Film (NCF) is dispensed between the dies and interposer. The underfill material absorbs coefficient of thermal expansion mismatch stresses between silicon and the organic substrate, preventing solder fatigue and microbump joint cracking during extreme thermal cycling.
**CoWoS architectural variants optimize cost, thermal dissipation, and inter-chiplet routing density.** CoWoS-S uses a full-size passive silicon interposer with TSVs, delivering maximum routing density and signal integrity for flagship AI accelerators. CoWoS-L embeds small localized silicon bridges inside high-density organic buildup layers, combining the low cost of organic substrates with the sub-micron wire density of silicon bridges for chiplet-to-chiplet interfaces. CoWoS-R utilizes organic thin-film redistribution layers without silicon substrates, optimizing high-frequency electrical performance and package warpage for cost-sensitive networking and mobile applications.
| Advanced Packaging Platform | Interposer Substrate Type | Die-to-Die Wire Pitch ($L/S$) | Max Package / Interposer Size | HBM Stacks Supported | Primary Semiconductor Application |
|---|---|---|---|---|---|
| TSMC CoWoS-S | Monolithic Silicon with TSVs | $0.4 / 0.4\ \mu\text{m}$ | Up to $3.3\times$ Reticle ($> 2,800\text{ mm}^2$) | Up to 8–12 HBM3e/HBM4 | NVIDIA H100/B200, AMD MI300X, Google TPU |
| TSMC CoWoS-L | Organic + Embedded Silicon (LSI) | $0.4 / 0.4\ \mu\text{m}$ (Bridge) | Up to $5.5\times$ Reticle ($> 4,700\text{ mm}^2$) | Up to 12 HBM3e stacks | Next-gen multi-compute AI superchips |
| Intel EMIB | Embedded Multi-Die Bridge | $0.5 / 0.5\ \mu\text{m}$ (Bridge) | Multi-bridge organic substrate | Up to 8 HBM stacks | Intel Ponte Vecchio, Xeon Max server CPUs |
| TSMC InFO-oS / InFO-LSI | Organic Fan-Out Wafer-Level | $0.8 / 0.8\ \mu\text{m}$ | $1.5\text{--}2.5\times$ Reticle | 2–4 HBM stacks | Networking switches and high-end mobile |
| 3D TSMC SoIC / Intel Foveros | Direct Cu-Cu Hybrid Bonding | Sub-micron ($P < 1.0\ \mu\text{m}$) | Full 3D vertical die stacking | Vertical 3D Memory / Cache | AMD 3D V-Cache, Intel Lunar Lake / Clearwater |
**Package warpage management and high-power thermal dissipation govern packaging assembly yield.** As advanced package body sizes expand beyond $75\text{ mm} \times 75\text{ mm}$ and dissipate over $700\text{ W}$ of thermal design power, managing mechanical warpage during solder reflow and high-temperature operation is paramount. Fabs deploy stiffener rings, low-shrinkage epoxy mold compounds (EMC), and high-thermal-conductivity Indium-alloy Thermal Interface Materials ($\kappa > 80\text{ W/m}\cdot\text{K}$) mated to forged copper lid heat spreaders to keep operating junction temperatures below $85^\circ\text{C}$.
```flowchart
st=>start: Fabricate high-density silicon interposer wafer with TSVs and multi-layer Cu RDL
interposer_thin=>operation: Temporary carrier bonding + backside grind thins interposer to 100um to reveal TSVs
chiplet_test=>operation: Known Good Die (KGD) qualification tests compute chiplets and HBM3 stacks
chip_on_wafer=>operation: High-precision flip-chip placement bonds dies onto interposer wafer (25um microbumps)
underfill_cure=>operation: Capillary underfill (CUF) dispensing and thermal cure encapsulates microbump array
wafer_saw=>operation: CoW wafer dicing separates individual multi-die reconstituted modules
substrate_attach=>operation: Attach CoW module onto organic ABF ball-grid-array (BGA) package substrate
tim_lid=>operation: Dispense Indium TIM + attach copper lid stiffener for high-TDP thermal cooling
pass=>end: Fully assembled 2.5D heterogeneous AI accelerator module ready for system deployment
st->interposer_thin->chiplet_test->chip_on_wafer->underfill_cure->wafer_saw->substrate_attach->tim_lid->pass
```
**Scaling artificial intelligence computing systems beyond monolithic limits requires treating packaging through a heterogeneous-die-stitching-silicon-interposer-tsv-and-hbm-bandwidth lens.** By harmonizing multi-reticle optical stitching, deep silicon via metallization, sub-micron die-to-die redistribution routing, and robust thermo-mechanical warpage engineering, semiconductor foundries construct computing architectures of unprecedented scale. 2.5D CoWoS and heterogeneous chiplet platforms ensure that next-generation deep learning training clusters, hyperscale datacenters, and frontier supercomputing engines deliver maximum memory bandwidth, low communication latencies, and high manufacturing yield across complex multi-chip systems.
**Wire bond FA** is **failure analysis focused on wire-bond integrity including lift, break, corrosion, and heel-crack mechanisms** - Microscopy, pull tests, and electrical continuity data are correlated to isolate bond-interface weakness and process causes.
**What Is Wire bond FA?**
- **Definition**: Failure analysis focused on wire-bond integrity including lift, break, corrosion, and heel-crack mechanisms.
- **Core Mechanism**: Microscopy, pull tests, and electrical continuity data are correlated to isolate bond-interface weakness and process causes.
- **Operational Scope**: It is applied in semiconductor yield and failure-analysis programs to improve defect visibility, repair effectiveness, and production reliability.
- **Failure Modes**: Sampling only obvious failures can miss systemic marginality across the lot.
**Why Wire bond FA Matters**
- **Defect Control**: Better diagnostics and repair methods reduce latent failure risk and field escapes.
- **Yield Performance**: Focused learning and prediction improve ramp efficiency and final output quality.
- **Operational Efficiency**: Adaptive and calibrated workflows reduce unnecessary test cost and debug latency.
- **Risk Reduction**: Structured evidence linking test and FA results improves corrective-action precision.
- **Scalable Manufacturing**: Robust methods support repeatable outcomes across tools, lots, and product families.
**How It Is Used in Practice**
- **Method Selection**: Choose techniques by defect type, access method, throughput target, and reliability objective.
- **Calibration**: Track bond pull-strength distributions and correlate with metallurgy and process window data.
- **Validation**: Track yield, escape rate, localization precision, and corrective-action closure effectiveness over time.
Wire bond FA is **a high-impact lever for dependable semiconductor quality and yield execution** - It protects package reliability by identifying weak interconnect processes early.
Semiconductor reliability physics and accelerated life testing constitute the statistical, thermodynamic, and mechanical disciplines engineered to predict, quantify, and guarantee the operational lifetime of integrated circuits across decades of field deployment. In advanced microprocessors, automotive controllers, hyperscale cloud accelerators, and aerospace systems, semiconductor devices must operate flawlessly under extreme thermomechanical, electrical, and environmental stress profiles. Because waiting years under nominal operating conditions to observe field failures is economically and technologically impossible, reliability engineers deploy accelerated life testing (ALT), high temperature operating life (HTOL), highly accelerated stress testing (HAST), and temperature cycling (TC). By applying calibrated overstress voltages, elevated junction temperatures, relative humidities, and thermal swings, reliability physics models accelerate underlying physical degradation mechanisms—such as electromigration, time-dependent dielectric breakdown, hot carrier injection, negative bias temperature instability, and solder fatigue—without introducing unrepresentative extrinsic failure modes.
**The Arrhenius and voltage acceleration models quantify thermal and electrical degradation kinetics.** Thermal acceleration in semiconductor failure mechanisms originates from molecular and atomic kinetic theory. The Arrhenius thermal acceleration factor ($AF_{\text{thermal}}$) models failure processes governed by an apparent activation energy ($E_a$, typically $0.6\text{--}1.1\text{ eV}$ for silicon junction defects, gate dielectric breakdown, and intermetallic diffusion):
$$
AF_{\text{thermal}} = \exp\left[ \frac{E_a}{k_B} \left( \frac{1}{T_{\text{use}}} - \frac{1}{T_{\text{stress}}} \right) \right].
$$
Here, $k_B$ is the Boltzmann constant ($8.617 \times 10^{-5}\text{ eV/K}$), and $T_{\text{use}}$ and $T_{\text{stress}}$ represent absolute junction temperatures in Kelvin. When testing at an accelerated stress temperature of $125^\circ\text{C}$ ($398.15\text{ K}$) for a product intended to operate at $55^\circ\text{C}$ ($328.15\text{ K}$) with an activation energy of $E_a = 0.7\text{ eV}$, the thermal acceleration factor alone provides an acceleration of approximately $78.6\times$. To accelerate dielectric tunneling and hot-carrier trapping, voltage acceleration ($AF_{\text{voltage}}$) is simultaneously applied using an empirical power-law or exponential voltage model ($AF_{\text{voltage}} = (V_{\text{stress}} / V_{\text{use}})^n$, where $n \approx 3\text{--}7$). The composite acceleration factor ($AF_{\text{total}} = AF_{\text{thermal}} \times AF_{\text{voltage}}$) compresses a decade of field usage into one thousand hours of laboratory stress.
**Peck's moisture model and the Coffin-Manson relationship govern environmental and thermomechanical fatigue.** In plastic-encapsulated microelectronics and multi-die 2.5D/3D chiplet packages, package reliability is limited by moisture-induced galvanic corrosion and cyclic thermal expansion mismatch. Peck's model calculates the acceleration factor for Highly Accelerated Stress Testing (HAST) and Pressure Cooker Testing (PCT), combining relative humidity ($RH$) and temperature:
$$
AF_{\text{HAST}} = \left( \frac{RH_{\text{stress}}}{RH_{\text{use}}} \right)^p \exp\left[ \frac{E_a}{k_B} \left( \frac{1}{T_{\text{use}}} - \frac{1}{T_{\text{stress}}} \right) \right].
$$
The humidity power-law exponent ($p$) is typically $2.7\text{--}3.0$, meaning that elevating ambient humidity from $60\%\ RH$ to biased HAST conditions ($85\%\ RH$ at $130^\circ\text{C}$) provides massive acceleration of electrochemical dendritic copper/aluminum corrosion and wire bond intermetallic degradation. For thermal cycling and power cycling, where disparate coefficients of thermal expansion (CTE, $\Delta\alpha = \alpha_{\text{die}} - \alpha_{\text{substrate}}$) induce cyclic plastic shear strain ($\Delta\gamma_p$) across micro-bumps and C4 solder joints, the Coffin-Manson relationship governs lifetime:
$$
AF_{\text{TC}} = \left( \frac{\Delta T_{\text{stress}}}{\Delta T_{\text{use}}} \right)^m \left( \frac{f_{\text{use}}}{f_{\text{stress}}} \right)^k \exp\left[ \frac{E_a}{k_B} \left( \frac{1}{T_{\text{max,use}}} - \frac{1}{T_{\text{max,stress}}} \right) \right].
$$
The Coffin-Manson exponent ($m \approx 1.9\text{--}2.5$ for lead-free SAC305 solders) enables qualification teams to validate solder fatigue, package delamination, and through-silicon via (TSV) keep-out zone integrity across thousands of mission thermal excursions.
| Qualification Test | JEDEC Standard | Stress Conditions | Sample Size & Duration | Dominant Acceleration Model | Target Failure Mechanism & Signoff Limit |
|---|---|---|---|---|---|
| High Temperature Operating Life (HTOL) | JESD22-A108 | $125^\circ\text{C}\text{--}150^\circ\text{C}, 1.2\text{--}1.4\times V_{\text{DD}}$ | $3\text{ lots} \times 77\text{ pcs}, 1000\text{ hrs}$ | Arrhenius + Voltage ($AF_T \cdot AF_V$) | TDDB, BTI, HCI, EM; $\text{FIT} < 10$ at $60\%\text{ CL}$ with $0\text{ fails}$ |
| Highly Accelerated Stress Test (HAST) | JESD22-A110 | $130^\circ\text{C}, 85\%\text{ RH}, 33.3\text{ psia}, V_{\text{bias}}$ | $3\text{ lots} \times 77\text{ pcs}, 96\text{ hrs}$ | Peck's Humidity-Temperature | Metal track corrosion, ionic migration, passivation pinholes |
| Temperature Cycling (TC) | JESD22-A104 | $-55^\circ\text{C}\text{ to }+125^\circ\text{C}, 2\text{ cycles/hr}$ | $3\text{ lots} \times 77\text{ pcs}, 1000\text{ cycles}$ | Coffin-Manson Mechanical | C4 bump fatigue, micro-bump cracking, package delamination |
| Unbiased HAST (uHAST) | JESD22-A118 | $130^\circ\text{C}, 85\%\text{ RH}, 33.3\text{ psia}$ | $3\text{ lots} \times 77\text{ pcs}, 96\text{ hrs}$ | Peck's Non-Biased Humidity | Mold compound moisture absorption, interfacial de-adhesion |
| High Temperature Storage Life (HTSL) | JESD22-A103 | $150^\circ\text{C}\text{--}175^\circ\text{C}, \text{unbiased}$ | $3\text{ lots} \times 77\text{ pcs}, 1000\text{ hrs}$ | Arrhenius High-T Thermal | Wire bond intermetallic Kirkendall voiding, dopant drift |
| Autoclave / Pressure Cooker (PCT) | JESD22-A102 | $121^\circ\text{C}, 100\%\text{ RH}, 29.7\text{ psia}$ | $3\text{ lots} \times 77\text{ pcs}, 96\text{ hrs}$ | Saturated Steam Moisture | Extreme package hermeticity and moisture condensation |
**The Weibull distribution and Failures in Time formulate statistical product lifespan and random failure rates.** Semiconductor reliability data is parameterized using the two-parameter Weibull cumulative distribution function ($F(t) = 1 - \exp[-(t/\eta)^\beta]$), where $\eta$ is the characteristic life (the time at which $63.2\%$ of the population has failed) and $\beta$ is the dimensionless Weibull shape parameter (Weibull slope). In the classic bathtub curve, a shape parameter of $\beta < 1.0$ designates infant mortality, where defect-bearing devices fail early due to gate oxide pinholes, particle bridging, or micro-voids; $\beta = 1.0$ represents the useful life period characterized by a purely random, constant failure rate ($\lambda$); and $\beta > 1.0$ ($3.0\text{--}8.0$) indicates intrinsic wearout. Failure rates are standardized across the global semiconductor industry in Failures in Time ($\text{FIT}$), defined as the number of failures per one billion ($10^9$) device operating hours:
$$
\text{FIT} = \frac{\chi^2(1 - \text{CL},\ 2r + 2)}{2 \cdot N_{\text{sample}} \cdot t_{\text{stress}} \cdot AF_{\text{total}}} \times 10^9.
$$
In this formulation, $N_{\text{sample}}$ is the total number of tested devices across qualification lots (typically $3 \times 77 = 231$ units), $t_{\text{stress}}$ is the test duration in hours, $r$ is the observed failure count (where $r = 0$ is required for standard qualification), and $\chi^2$ is the Chi-Square statistic evaluated at a specified Confidence Level ($\text{CL}$, standardly $60\%$ for commercial/industrial and $90\%$ for automotive ISO 26262 signoff). For zero observed failures ($r=0$) at $60\%\text{ CL}$, $\chi^2(0.40, 2) = 1.833$; at $90\%\text{ CL}$, $\chi^2(0.10, 2) = 4.605$. Mean Time Between Failures is the inverse metric ($\text{MTBF} = 10^9 / \text{FIT}\text{ hours}$).
**Burn-in stress screening eliminates infant mortality defects to export zero-defect quality lots.** To prevent early-life failures ($\beta < 1.0$) from escaping into automotive, aerospace, and mission-critical cloud infrastructure, production fabs and test houses subject fabricated dice to Burn-In stress screening. Assembled devices are inserted into high-temperature burn-in sockets on specialized multi-layer Burn-In Boards (BIBs) housed inside environmental convection ovens operating at $125^\circ\text{C}\text{--}150^\circ\text{C}$ with elevated supply voltages ($1.2\text{--}1.4\times V_{\text{DD}}$). During Dynamic Burn-In, automated pattern generators continuously stimulate internal logic, toggling scan chains and functional registers to maximize internal node activity ($> 95\%$ toggle coverage). The combined thermal and electrical overstress accelerates latent physical defects (marginal dielectric filaments, gate oxide micro-asperities, and narrow metal necks), causing defective parts to fail within a calibrated 6-to-48 hour window and ensuring that customer-shipped components reside exclusively within the flat, low-FIT useful operating life regime.
```flowchart
st=>start: Fabricated wafer lot: front-end processing, wafer probe test, and package assembly
htol_stress=>operation: HTOL stress testing (125°C, 1.25x VDD, 1000 hrs, N=231 pcs, c=0)
env_stress=>operation: Environmental stress suite: HAST (130°C/85% RH) + Temp Cycle (-55°C to 125°C)
interim_readout=>operation: Perform interim functional/parametric ATE electrical test (168h, 500h, 1000h)
stat_calc=>operation: Compute total acceleration AF_total and Chi-Square FIT rate at 60% and 90% CL
burnin_opt=>operation: Optimize production burn-in duration (t_bi) to screen infant mortality (beta < 1)
pass=>end: JEDEC Qualification Certified: FIT < 1 (Automotive) / FIT < 10 (Enterprise), MTBF > 1e8 hrs
st->htol_stress->env_stress->interim_readout->stat_calc->burnin_opt->pass
```
**Delivering ultra-high reliability and zero-defect longevity across nanoscale semiconductor systems requires evaluating device qualification through an accelerated-life-testing-arrhenius-coffin-manson-and-fit-rate-reliability lens.** By uniting Arrhenius thermal activation kinetics, power-law voltage overstress modeling, Peck humidity-temperature acceleration, Coffin-Manson thermomechanical fatigue scaling, Weibull statistical distributions, and rigorous dynamic burn-in screening, reliability physics engineers ensure robust operational integrity. Mastering accelerated life testing principles guarantees that billion-transistor processors, AI accelerators, automotive ADAS modules, and 3D heterogeneous packaging assemblies achieve sustained multi-year reliability with near-zero failure rates.
**Wire bond reliability** is the **long-term ability of wire-bond interconnects to maintain electrical and mechanical integrity under operating and environmental stress** - it is a primary determinant of package lifetime performance.
**What Is Wire bond reliability?**
- **Definition**: Reliability domain covering bond survival through thermal, mechanical, and electrical stress conditions.
- **Key Failure Modes**: Intermetallic embrittlement, heel cracking, corrosion, lift-off, and fatigue.
- **Assessment Methods**: Uses accelerated stress tests plus pull/shear trend tracking and failure analysis.
- **System Impact**: Bond failures can produce intermittent faults or catastrophic open circuits.
**Why Wire bond reliability Matters**
- **Field Lifetime**: Bond robustness is essential for sustained product operation in service.
- **Quality Cost**: Reliability escapes drive costly returns and reputation damage.
- **Design Validation**: Material and geometry choices must be proven under mission profiles.
- **Regulatory Requirements**: Automotive, medical, and industrial markets require strict reliability evidence.
- **Continuous Improvement**: Reliability data guides process upgrades and material transitions.
**How It Is Used in Practice**
- **Stress Qualification**: Run temperature cycling, high-temp storage, humidity, and power-cycling tests.
- **Failure Analytics**: Correlate failure modes with bond geometry, metallurgy, and process history.
- **Control Plan**: Maintain ongoing reliability surveillance after product release.
Wire bond reliability is **a mission-critical quality domain in semiconductor assembly** - strong reliability programs are required to sustain wire-bond product performance in the field.
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.
**Wire bonding is a semiconductor-packaging process that connects pads on a die to leads or substrate traces with fine metal wires.** A capillary or wedge tool presses the wire against a metallized surface while heat, force, and ultrasonic energy create a solid-state bond. The equipment is fast, programmable, and mature, so wire bonding remains the dominant interconnect for enormous volumes of analog, power, sensor, microcontroller, memory, and low-to-moderate pin-count products even as leading processors use flip chip.
**The familiar geometry is a sequence of tiny arches around a die.** The die is attached face up in a leadframe cavity or on a package substrate. One end of each wire lands on a die pad; the other lands on a package finger. The bonder controls bond force, ultrasonic waveform, temperature, loop trajectory, and termination. After electrical connection, molding compound or a lid protects the die and wires, and package leads or balls connect to the circuit board.
| Interconnect method | Typical material and bond style | Best fit | Key limitation |
|---|---|---|---|
| Gold ball bond | Fine gold wire, ball-to-wedge | Mature fine-pitch assembly and sensitive pads | Material cost and some Al-Au intermetallic risks |
| Copper ball bond | Palladium-coated or bare copper, ball-to-wedge | High-volume cost and current capability | Harder wire can damage pads; oxidation control |
| Aluminum wedge bond | Aluminum wire, wedge-to-wedge | Power devices, RF, room-temperature bonding | Slower directional process, larger loop footprint |
| Heavy wire or ribbon | Thick Al or Cu wire/ribbon | Power modules and high current | Loop inductance and thermo-mechanical fatigue |
| Flip chip | Solder bump or copper pillar area array | High I/O, high frequency, strong power delivery | Substrate, underfill, assembly complexity |
| Hybrid bonding | Direct Cu/dielectric bond | Ultra-dense chiplets and 3-D integration | Planarity, cleanliness, alignment, capital cost |
**Ball bonding begins by forming a free-air ball at the wire tip.** An electrical flame-off melts the protruding wire, and surface tension makes a sphere. The capillary places that ball on the die pad and applies thermosonic energy to form the first bond. It then rises and moves along a programmed path to form the loop, makes a crescent-shaped second bond on the lead, clamps the wire, and breaks it. A new ball forms for the next connection.
```svg
```
**Wedge bonding uses a tool with a groove that guides wire or ribbon.** Both first and second bonds are wedge shaped, and the process is directional because the wire exits behind the tool. Aluminum wedge bonding can occur at relatively low temperature and is common in power electronics. Gold wedge bonding serves microwave and optoelectronic packages. Ribbon reduces loop height and inductance while presenting more cross-sectional area, useful for RF grounding and power connections.
**Material choice changes cost, process window, and reliability.** Gold is soft, resists oxidation, and has decades of process knowledge, but is expensive. Copper has lower resistivity, higher strength, and much lower commodity cost, yet its hardness raises cratering risk and it oxidizes readily; forming gas and palladium coatings help. Aluminum is economical and compatible with aluminum die pads. Dissimilar metals can form intermetallic phases, so temperature, humidity, and expected life guide the stack.
**A bond forms through deformation and interfacial cleaning rather than bulk melting.** Force brings asperities into contact, ultrasonic motion disrupts oxides and contaminants, and heat assists plastic flow and diffusion. Too little energy produces a weak or non-stick bond. Too much energy thins the heel, cracks passivation, lifts pad metal, or damages low-k dielectric beneath the pad. A production recipe defines bounded combinations of force, power, time, temperature, and scrub behavior.
**Loop geometry is an electrical and mechanical design variable.** A higher or longer loop adds inductance and increases sweep risk during molding. A very low loop may contact die edges or neighboring wires and concentrates strain near the heel. Reverse bonding, stacked-die loops, security bonds, and multi-tier pad arrangements require controlled trajectories. Modern bonders use servo motion and vision alignment to reproduce loops at high speed across warped or varying surfaces.
**Electrical parasitics limit high-frequency and high-current use.** Wire inductance produces voltage \(V=L\,di/dt\), so a rapidly changing supply current creates bounce. Parallel power and ground wires reduce effective inductance and share current. Short ribbons and down bonds improve RF return paths. Adjacent signal wires couple capacitively and inductively. For modest interfaces these effects are manageable; for thousands of multi-gigabit signals, area-array flip chip offers much shorter paths and many more returns.
**Pad design must survive bonding loads.** Top metal thickness, pad opening, passivation edge, underlying vias, and fragile interlayer dielectrics affect stress. Bond-over-active-circuit techniques use reinforced stacks when area is scarce, but need foundry qualification. Contamination from probe marks, oxides, residues, or handling can prevent adhesion. Package fingers need compatible plating and stable geometry. The assembly house and wafer fab therefore share pad-finish specifications and inspection criteria.
**Process control relies on mechanical tests and machine data.** Wire pull measures loop or bond strength and records where failure occurs. Ball shear or bond shear applies lateral force at the first bond. Acceptable failures may occur in the wire or as ductile remnants on the pad; interfacial lifts often signal poor bonding. Destructive tests sample lots, while non-destructive monitoring tracks ultrasonic response, deformation, bond position, tail length, and vision scores for every unit.
**Failure modes leave recognizable evidence.** Heel cracks begin where a wedge or second bond transitions into free wire. Bond lifts indicate contamination, insufficient energy, weak metallurgy, or aging. Cratering fractures dielectric or silicon beneath a pad. Wire sweep during transfer molding can create shorts or excessive sag. Corrosion grows under moisture and ionic contamination. In gold-on-aluminum systems, unfavorable intermetallic growth and voiding can weaken high-temperature bonds. Microscopy and cross-sections distinguish these mechanisms.
**Encapsulation must protect without moving the wires.** Molding compound flows around delicate loops under pressure. Viscosity, filler size, gate location, wire orientation, and cure conditions determine sweep. The cured compound and wire expand differently during temperature cycling, producing fatigue at heels and interfaces. Delamination admits moisture and changes stress. Moisture-sensitivity-level handling and preconditioning prevent absorbed water from vaporizing destructively during board reflow.
**Wire bonding adapts particularly well to product variety.** A programmable bonder can connect different die sizes and pad maps without fabricating a fine-line multilayer substrate. Leadframes are economical, and optical access makes setup and failure analysis straightforward. Multiple dies can be connected within one package, sensors can retain exposed regions, and power devices can use several heavy wires. This flexibility explains continued volume strength despite the performance advantages of flip chip.
**Cost is determined by more than the wire commodity.** Bond count, bonding speed, tool life, capillary or wedge choice, substrate panel utilization, inspection, yield, and package test all contribute. Copper conversion can save material cost but requires qualified pad structures, atmosphere control, and recipe development. A lower-cost process that damages a small fraction of expensive dies may lose money. Engineers optimize total good-package cost and field reliability.
**Wire-bond qualification reflects the intended environment.** Temperature cycling tests fatigue, high-temperature storage accelerates intermetallic changes, humidity bias exposes corrosion, and mechanical shock or vibration stresses loops. Automotive and power applications demand long life at elevated junction temperature; implanted or aerospace products impose specialized materials and traceability. Statistical process controls must keep production inside the qualified window rather than merely passing a one-time experiment.
**Wire bonding remains valuable because semiconductor packaging is not one performance race.** Most chips do not need ten thousand low-inductance connections. They need a dependable, inspectable, high-throughput interconnect at sensible cost. Where I/O density, bandwidth, or power delivery demands flip chip, engineers use it; where flexibility and manufacturing economics dominate, wire bonding is often the better system solution.
die attach, semiconductor packaging assembly, gold wire bond, wedge bonding
**Wire Bonding and Die Attach** are the **fundamental semiconductor packaging assembly processes that mount the die onto a substrate and create electrical connections between die pads and package leads** — collectively responsible for ensuring electrical, thermal, and mechanical integrity of every packaged chip, from $0.10 microcontrollers to $50,000 server processors.
**Die Attach**
**Purpose**: Mechanically and thermally bond the silicon die to the package substrate or leadframe.
**Methods**:
- **Epoxy Die Attach**: Silver-filled epoxy adhesive — most common for standard packages.
- Thermal conductivity: 2-25 W/m·K depending on silver loading.
- Low cost, easy rework.
- **Solder Die Attach**: AuSn or SAC solder — for high-power devices requiring low thermal resistance.
- Thermal conductivity: 50-60 W/m·K.
- Used in power amplifiers, high-brightness LEDs, automotive.
- **Sintered Silver**: Nano-silver paste sintered at 200-300°C — emerging for SiC/GaN power.
- Thermal conductivity: > 200 W/m·K.
- Handles junction temperatures > 200°C.
**Wire Bonding**
**Purpose**: Connect die bond pads to package substrate pads using thin metal wire.
**Types**:
| Type | Wire Material | Diameter | Process |
|------|-------------|----------|---------|
| Ball Bonding | Gold (Au) | 18-50 μm | Thermosonic (heat + ultrasonics + force) |
| Ball Bonding | Copper (Cu) | 18-50 μm | Thermosonic with forming gas (N2/H2) |
| Wedge Bonding | Aluminum (Al) | 25-500 μm | Ultrasonic only |
- **Ball Bond**: Spark melts wire tip → forms ball → pressed onto die pad → loops → wedge bond on substrate.
- **Cu wire** replaced Au wire ($50/oz Cu vs. $2000/oz Au at 2024 prices) for >80% of consumer packages.
- **Speed**: Modern wire bonders: 30-60 bonds per second per unit.
**Wire Bond vs. Flip Chip**
| Aspect | Wire Bond | Flip Chip |
|--------|-----------|----------|
| I/O count | < 1000 | > 10,000 |
| Inductance | Higher (wire loop) | Lower (direct bump) |
| Cost | Lower | Higher |
| Thermal | Die face up (heat through substrate) | Die face down (heat through bumps + underfill) |
| Package types | QFP, BGA, QFN | BGA, CSP, CoWoS |
**Advanced Wire Bonding Applications**
- **Stacked Die**: Wire bonding connects multiple dies stacked vertically — memory packages (LPDDR).
- **Reverse Wire Bonding**: Ball-on-substrate, wedge-on-die — enables thinner profiles for stacked packages.
- **Heavy Wire Bonding**: 100-500 μm Al wire for power modules (IGBT, SiC) carrying 10-100+ amps.
Wire bonding and die attach are **the packaging workhorses of the semiconductor industry** — while advanced packaging (flip chip, hybrid bonding) captures headlines, wire bonding still accounts for over 75% of all semiconductor interconnections produced globally, processing billions of bonds per day.
**Wire bonding is a semiconductor-packaging process that connects pads on a die to leads or substrate traces with fine metal wires.** A capillary or wedge tool presses the wire against a metallized surface while heat, force, and ultrasonic energy create a solid-state bond. The equipment is fast, programmable, and mature, so wire bonding remains the dominant interconnect for enormous volumes of analog, power, sensor, microcontroller, memory, and low-to-moderate pin-count products even as leading processors use flip chip.
**The familiar geometry is a sequence of tiny arches around a die.** The die is attached face up in a leadframe cavity or on a package substrate. One end of each wire lands on a die pad; the other lands on a package finger. The bonder controls bond force, ultrasonic waveform, temperature, loop trajectory, and termination. After electrical connection, molding compound or a lid protects the die and wires, and package leads or balls connect to the circuit board.
| Interconnect method | Typical material and bond style | Best fit | Key limitation |
|---|---|---|---|
| Gold ball bond | Fine gold wire, ball-to-wedge | Mature fine-pitch assembly and sensitive pads | Material cost and some Al-Au intermetallic risks |
| Copper ball bond | Palladium-coated or bare copper, ball-to-wedge | High-volume cost and current capability | Harder wire can damage pads; oxidation control |
| Aluminum wedge bond | Aluminum wire, wedge-to-wedge | Power devices, RF, room-temperature bonding | Slower directional process, larger loop footprint |
| Heavy wire or ribbon | Thick Al or Cu wire/ribbon | Power modules and high current | Loop inductance and thermo-mechanical fatigue |
| Flip chip | Solder bump or copper pillar area array | High I/O, high frequency, strong power delivery | Substrate, underfill, assembly complexity |
| Hybrid bonding | Direct Cu/dielectric bond | Ultra-dense chiplets and 3-D integration | Planarity, cleanliness, alignment, capital cost |
**Ball bonding begins by forming a free-air ball at the wire tip.** An electrical flame-off melts the protruding wire, and surface tension makes a sphere. The capillary places that ball on the die pad and applies thermosonic energy to form the first bond. It then rises and moves along a programmed path to form the loop, makes a crescent-shaped second bond on the lead, clamps the wire, and breaks it. A new ball forms for the next connection.
```svg
```
**Wedge bonding uses a tool with a groove that guides wire or ribbon.** Both first and second bonds are wedge shaped, and the process is directional because the wire exits behind the tool. Aluminum wedge bonding can occur at relatively low temperature and is common in power electronics. Gold wedge bonding serves microwave and optoelectronic packages. Ribbon reduces loop height and inductance while presenting more cross-sectional area, useful for RF grounding and power connections.
**Material choice changes cost, process window, and reliability.** Gold is soft, resists oxidation, and has decades of process knowledge, but is expensive. Copper has lower resistivity, higher strength, and much lower commodity cost, yet its hardness raises cratering risk and it oxidizes readily; forming gas and palladium coatings help. Aluminum is economical and compatible with aluminum die pads. Dissimilar metals can form intermetallic phases, so temperature, humidity, and expected life guide the stack.
**A bond forms through deformation and interfacial cleaning rather than bulk melting.** Force brings asperities into contact, ultrasonic motion disrupts oxides and contaminants, and heat assists plastic flow and diffusion. Too little energy produces a weak or non-stick bond. Too much energy thins the heel, cracks passivation, lifts pad metal, or damages low-k dielectric beneath the pad. A production recipe defines bounded combinations of force, power, time, temperature, and scrub behavior.
**Loop geometry is an electrical and mechanical design variable.** A higher or longer loop adds inductance and increases sweep risk during molding. A very low loop may contact die edges or neighboring wires and concentrates strain near the heel. Reverse bonding, stacked-die loops, security bonds, and multi-tier pad arrangements require controlled trajectories. Modern bonders use servo motion and vision alignment to reproduce loops at high speed across warped or varying surfaces.
**Electrical parasitics limit high-frequency and high-current use.** Wire inductance produces voltage \(V=L\,di/dt\), so a rapidly changing supply current creates bounce. Parallel power and ground wires reduce effective inductance and share current. Short ribbons and down bonds improve RF return paths. Adjacent signal wires couple capacitively and inductively. For modest interfaces these effects are manageable; for thousands of multi-gigabit signals, area-array flip chip offers much shorter paths and many more returns.
**Pad design must survive bonding loads.** Top metal thickness, pad opening, passivation edge, underlying vias, and fragile interlayer dielectrics affect stress. Bond-over-active-circuit techniques use reinforced stacks when area is scarce, but need foundry qualification. Contamination from probe marks, oxides, residues, or handling can prevent adhesion. Package fingers need compatible plating and stable geometry. The assembly house and wafer fab therefore share pad-finish specifications and inspection criteria.
**Process control relies on mechanical tests and machine data.** Wire pull measures loop or bond strength and records where failure occurs. Ball shear or bond shear applies lateral force at the first bond. Acceptable failures may occur in the wire or as ductile remnants on the pad; interfacial lifts often signal poor bonding. Destructive tests sample lots, while non-destructive monitoring tracks ultrasonic response, deformation, bond position, tail length, and vision scores for every unit.
**Failure modes leave recognizable evidence.** Heel cracks begin where a wedge or second bond transitions into free wire. Bond lifts indicate contamination, insufficient energy, weak metallurgy, or aging. Cratering fractures dielectric or silicon beneath a pad. Wire sweep during transfer molding can create shorts or excessive sag. Corrosion grows under moisture and ionic contamination. In gold-on-aluminum systems, unfavorable intermetallic growth and voiding can weaken high-temperature bonds. Microscopy and cross-sections distinguish these mechanisms.
**Encapsulation must protect without moving the wires.** Molding compound flows around delicate loops under pressure. Viscosity, filler size, gate location, wire orientation, and cure conditions determine sweep. The cured compound and wire expand differently during temperature cycling, producing fatigue at heels and interfaces. Delamination admits moisture and changes stress. Moisture-sensitivity-level handling and preconditioning prevent absorbed water from vaporizing destructively during board reflow.
**Wire bonding adapts particularly well to product variety.** A programmable bonder can connect different die sizes and pad maps without fabricating a fine-line multilayer substrate. Leadframes are economical, and optical access makes setup and failure analysis straightforward. Multiple dies can be connected within one package, sensors can retain exposed regions, and power devices can use several heavy wires. This flexibility explains continued volume strength despite the performance advantages of flip chip.
**Cost is determined by more than the wire commodity.** Bond count, bonding speed, tool life, capillary or wedge choice, substrate panel utilization, inspection, yield, and package test all contribute. Copper conversion can save material cost but requires qualified pad structures, atmosphere control, and recipe development. A lower-cost process that damages a small fraction of expensive dies may lose money. Engineers optimize total good-package cost and field reliability.
**Wire-bond qualification reflects the intended environment.** Temperature cycling tests fatigue, high-temperature storage accelerates intermetallic changes, humidity bias exposes corrosion, and mechanical shock or vibration stresses loops. Automotive and power applications demand long life at elevated junction temperature; implanted or aerospace products impose specialized materials and traceability. Statistical process controls must keep production inside the qualified window rather than merely passing a one-time experiment.
**Wire bonding remains valuable because semiconductor packaging is not one performance race.** Most chips do not need ten thousand low-inductance connections. They need a dependable, inspectable, high-throughput interconnect at sensible cost. Where I/O density, bandwidth, or power delivery demands flip chip, engineers use it; where flexibility and manufacturing economics dominate, wire bonding is often the better system solution.
**Wire Load Model (WLM)** is a **statistical model of interconnect wire length and RC parasitics based on net fanout** — used during synthesis and pre-layout STA to estimate delay before actual routing completes.
**Why Wire Load Models?**
- During synthesis: No physical routing exists — cannot compute actual wire length/delay.
- Need parasitic estimate for timing closure decisions.
- WLM: Table of estimated wire length as a function of fanout, derived from similar designs.
**WLM Structure**
```
WIRE_LOAD "wlm_typical_10K" {
RESISTANCE 0.00010 ;
CAPACITANCE 0.000110 ;
AREA 0.003 ;
SLOPE 0.040 ;
FANOUT_LENGTH 1 0.050 ;
FANOUT_LENGTH 2 0.100 ;
FANOUT_LENGTH 4 0.200 ;
FANOUT_LENGTH 8 0.400 ;
FANOUT_LENGTH 16 0.800 ;
}
```
- `FANOUT_LENGTH`: Estimated wire length (μm) for given fanout.
- R and C per unit length from technology LEF or Liberty file.
- Net delay: $R_{wire} \times C_{wire}$ added to cell output delay.
**WLM Limitations**
- Accuracy: ±50% of actual post-route delay (statistical average).
- High-fanout nets: WLM underestimates — clock buffers, reset trees.
- Hierarchical blocks: Different WLM for each hierarchy level.
- Modern flows: Many designs bypass WLM entirely, using prototype routing for better estimates.
**Zero Wire Load**
- Special case: All wire delays = 0.
- Used for: Technology exploration, behavioral synthesis, first-pass area estimation.
- Not used for final timing sign-off.
**Post-Route vs. WLM**
- WLM-based synthesis: Close timing at ±50% accuracy.
- Post-route STA: Refine closure with actual extracted parasitics.
- Gap between WLM and actual: 10–30% timing difference common.
**Virtual Flat WLM**
- Most conservative: Assumes net can be routed anywhere in the die.
- Most accurate pre-layout for flat designs.
- Less suitable for hierarchical block-level synthesis.
Wire load models are **the timing estimation bridge between synthesis and physical implementation** — while they lack precision, they prevent synthesis from optimizing away critical-path cells that will be needed once routing reveals actual wire lengths.
**Wire Pull Test** is **a reliability test that measures the tensile force required to break or detach a bond wire** - It assesses bond quality at wire-to-pad and wire-to-lead interfaces.
**What Is Wire Pull Test?**
- **Definition**: a reliability test that measures the tensile force required to break or detach a bond wire.
- **Core Mechanism**: A hook tool applies upward force on a bond wire until failure while recording pull strength and failure mode.
- **Operational Scope**: It is applied in failure-analysis-advanced workflows to improve robustness, accountability, and long-term performance outcomes.
- **Failure Modes**: Improper pull height can shift failure location and distort bond-quality interpretation.
**Why Wire Pull Test 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 evidence quality, localization precision, and turnaround-time constraints.
- **Calibration**: Use standardized pull geometry and correlate failure modes with metallurgical inspection.
- **Validation**: Track localization accuracy, repeatability, and objective metrics through recurring controlled evaluations.
Wire Pull Test is **a high-impact method for resilient failure-analysis-advanced execution** - It is a key metric in package assembly quality control.
**Wire Sag** is a wire bonding defect where the wire loop droops below its intended trajectory, risking contact with the die surface or other wires.
## What Is Wire Sag?
- **Cause**: Excessive loop height, inadequate wire tension, thermal softening
- **Risk**: Short circuits if wire touches die surface or adjacent wires
- **Detection**: Optical inspection, X-ray for encapsulated packages
- **Specification**: Minimum clearance typically 50-100μm above die
## Why Wire Sag Matters
Modern packages stack multiple die layers with minimal vertical clearance. Sagging wires can cause catastrophic shorts or intermittent failures under thermal cycling.
```svg
```
**Prevention Methods**:
- Optimize loop profile parameters
- Control bonding temperature precisely
- Use appropriate wire diameter for span length
- Verify wire tensioner settings daily
**Wire sweep** is the **deformation or displacement of bonded wires caused by mold-flow forces during encapsulation** - excessive sweep can create shorts and reliability failures.
**What Is Wire sweep?**
- **Definition**: Post-bond wire movement from intended loop path under dynamic molding pressure.
- **Primary Drivers**: Mold compound viscosity, flow direction, gate design, and loop geometry.
- **Failure Outcomes**: Wire-to-wire shorting, cracked necks, and bond-lift stress concentration.
- **Process Stage**: Most critical during transfer molding in plastic package assembly.
**Why Wire sweep Matters**
- **Yield Loss**: Sweep-related shorts are high-impact assembly defects.
- **Reliability Risk**: Swept wires may fail early under thermal cycling and vibration.
- **Design Constraints**: Loop spacing and pad layout must account for expected flow forces.
- **Process Interaction**: Molding conditions and wire profile are tightly coupled.
- **Cost Impact**: Sweep failures often occur late in flow, increasing scrap cost.
**How It Is Used in Practice**
- **Loop Optimization**: Control loop height, span, and stiffness to resist mold-flow displacement.
- **Mold Tuning**: Adjust gate location, fill rate, and compound rheology for lower flow stress.
- **X-Ray Inspection**: Monitor wire position shifts statistically across lots and package zones.
Wire sweep is **a major assembly defect mechanism in molded wire-bond packages** - controlling sweep requires coordinated loop design and molding process engineering.
**Wire sweep during molding** is the **displacement of bonded wires caused by molding-compound flow forces during encapsulation** - it is a major reliability risk in wire-bond packages with fine pitch or long loop structures.
**What Is Wire sweep during molding?**
- **Definition**: Flow-induced drag bends wires away from designed loop trajectories.
- **Sensitive Factors**: Wire length, loop height, gate direction, and flow velocity determine susceptibility.
- **Failure Modes**: Excess sweep can cause shorts, opens, and reduced wire-to-wire spacing margin.
- **Detection**: X-ray and destructive analysis are used to quantify sweep distribution.
**Why Wire sweep during molding Matters**
- **Electrical Reliability**: Wire deformation can immediately or latently compromise connectivity.
- **Yield**: Sweep defects can create high fallout in final test and reliability screens.
- **Design Constraints**: Packaging miniaturization increases sweep sensitivity due to tighter spacing.
- **Process Window**: Sweep behavior defines practical limits for pressure and flow profiles.
- **Customer Risk**: Latent wire movement can reduce field reliability under thermal cycling.
**How It Is Used in Practice**
- **Flow Control**: Lower peak transfer velocity and optimize pressure ramps near cavity entry.
- **Design Mitigation**: Adjust wire loop profiles and gate orientation for lower drag exposure.
- **Monitoring**: Trend sweep metrics by cavity and lot to catch emerging instability quickly.
Wire sweep during molding is **a critical encapsulation risk for wire-bond package integrity** - wire sweep during molding must be managed through joint package-design and process-parameter optimization.
ball lift, heel crack, wire sweep, bond reliability, failure analysis, packaging, wire bond
**Wire bond failure modes** are the **mechanisms by which wire interconnections in IC packages degrade and fail** — including ball lift, heel crack, wire sweep, and corrosion, each with distinct root causes and failure signatures, representing critical reliability concerns that must be understood for package qualification and field failure analysis.
**What Are Wire Bond Failure Modes?**
- **Definition**: Ways wire bond interconnections fail over time or under stress.
- **Impact**: Open circuits, intermittent connections, increased resistance.
- **Analysis**: Failure analysis techniques to identify root cause.
- **Prevention**: Process optimization and design rules.
**Why Understanding Failure Modes Matters**
- **Reliability Prediction**: Model lifetime based on failure mechanisms.
- **Root Cause Analysis**: Diagnose field returns and production rejects.
- **Process Improvement**: Optimize bonding parameters to prevent failures.
- **Design Rules**: Set appropriate wire length, loop height, spacing rules.
- **Qualification Testing**: Verify robustness to relevant failure modes.
**Major Failure Modes**
**Ball Lift**:
- **Description**: First bond (ball) separates from die pad.
- **Causes**: Pad contamination, under-bonding, aluminum corrosion.
- **Stress Factors**: Thermal cycling, mechanical shock.
- **Detection**: Pull test shows low force with ball lift signature.
**Heel Crack**:
- **Description**: Crack at second bond wire-to-stitch transition.
- **Causes**: Excessive ultrasonic energy, work hardening, flexure fatigue.
- **Stress Factors**: Thermal cycling, vibration, flexure.
- **Detection**: Pull test shows break at heel location.
**Wire Sweep**:
- **Description**: Wires displaced during molding, touch each other or other features.
- **Causes**: High mold flow velocity, improper loop profile.
- **Result**: Short circuits or intermittent contact.
- **Prevention**: Optimize loop shape, mold parameters, wire spacing.
**Neck Crack**:
- **Description**: Crack at ball-to-wire transition (first bond neck).
- **Causes**: Excessive ball formation energy, contamination.
- **Stress Factors**: Thermal cycling, mechanical stress.
**Wire Sag**:
- **Description**: Wire droops below intended loop, contacts die surface.
- **Causes**: Insufficient wire tension, excessive loop length.
- **Result**: Short circuit to die surface.
**Corrosion**:
- **Description**: Chemical attack on wire or bond interfaces.
- **Types**: Halide corrosion, aluminum-gold intermetallic growth.
- **Accelerators**: Moisture, temperature, ionic contamination.
**Failure Mechanism Details**
**Ball Bond Intermetallic Formation (Au-Al)**:
```
Over time at elevated temperature:
Au + Al → Au₅Al₂ (white plague) → AuAl₂ (purple plague)
Initial: Strong Au-Al bond
Aged: Kirkendall voids from diffusion imbalance
Result: Weakened interface, increased resistance
```
**Thermal Fatigue**:
```
CTE: Wire ~14 ppm/°C, Die ~3 ppm/°C, Package ~15-20 ppm/°C
Thermal cycle:
- Wire expands more than die
- Stress concentrates at heel and neck
- Crack nucleates and propagates
- Eventually: open failure
```
**Testing & Detection**
**Pull Testing**:
- Measure force to break wire.
- Classify failure location (ball, heel, wire mid-span).
- Minimum pull force specifications by wire diameter.
**Shear Testing**:
- Measure force to shear ball from pad.
- Indicates ball-pad interface strength.
**Environmental Testing**:
- HAST (Highly Accelerated Stress Test): Moisture + temperature.
- Temperature cycling: Thermal fatigue acceleration.
- HTOL (High Temperature Operating Life): Extended heat exposure.
**Failure Analysis Techniques**
- **X-Ray**: Non-destructive wire position inspection.
- **Acoustic Microscopy**: Detect delamination, voids.
- **Decapsulation**: Remove mold compound for visual inspection.
- **SEM/EDS**: High magnification imaging, compositional analysis.
- **Cross-Section**: Cut through bonds for interface analysis.
Wire bond failure modes are **essential knowledge for package reliability** — understanding how wires fail under various stress conditions enables engineers to design robust packages, optimize bonding processes, and correctly diagnose field failures, making this knowledge fundamental to IC packaging excellence.
wifi chip, wi-fi chip, bluetooth chip, ble chip, wifi 7, wireless combo ic, radio baseband mac
**Wireless chip integrates radio transceivers, data converters, baseband DSP, protocol MAC and host interfaces for standards such as Wi-Fi, Bluetooth/BLE and sometimes Zigbee or positioning.** Combo connectivity ICs provide high-throughput local networking and ultra-low-power peripheral links within tight RF, coexistence, security and power budgets. Wi-Fi 7 under IEEE 802.11be adds up to 320 MHz channels where spectrum permits, 4096-QAM and multi-link operation; theoretical aggregate rates depend on stream count and configuration and are not normal application throughput. A production specification names the hardware and software boundary, clock and reset domains, address map, data widths, endianness, ordering and coherency, interrupt and error behavior, power states, security domains, performance targets, configuration discovery, lifecycle owner, and verification evidence. Marketing names and nominal link rates are insufficient without exact revision, mode, topology, payload, and environmental conditions. Specify standards/revisions, bands, channel widths, streams, modulation, coexistence, antennas/RF front end, host link, security, power modes, firmware, region and certification.
**Architecture, protocol behavior, and system integration.** Antenna switch/filter/LNA/PA connect RF transceiver and PLL, ADC/DAC bridge to baseband OFDM and coding, MAC schedules frames and security, coexistence arbiter shares spectrum/antenna, and PCIe/SDIO/USB/UART reaches host. The chip scans and associates, authenticates, estimates channel, modulates/codes TX, synchronizes/equalizes/decodes RX, schedules multi-link or Bluetooth events, adapts rate/power and enters sleep states. Wi-Fi-only, Bluetooth/BLE, Wi-Fi/Bluetooth combo, multiprotocol 802.15.4 and tri-band chips trade integration, isolation and host interfaces. A modern embedded system spans processor and accelerator IP, memory hierarchy, on-chip interconnect, peripheral controllers, analog and RF interfaces, clock/reset/power management, boot and firmware, board devices, operating-system discovery and drivers, diagnostics, update infrastructure, and application policy. Data, control, timing, trust, and power paths cross several abstraction levels. Evaluation combines functional correctness with bandwidth and payload efficiency, p50 and tail latency, jitter, outstanding depth, utilization, arbitration fairness, interrupt rate, CPU overhead, memory traffic, error and retry rate, power, thermal behavior, area, firmware footprint, startup time, recovery, interoperability, reliability, security, and total cost. Measurements state workload, clocks, voltages, formats, traffic mix, software, and instrumentation.
**Implementation, physical design, and failure modes.** Co-design RF/analog/digital, calibrate I/Q/PA, isolate clocks, manage coexistence, use secure firmware, partition MAC, optimize DMA/interrupt moderation and validate antennas/board. RF process/passives, PA efficiency, ADC/DAC, PLL phase noise, package/board loss, antennas, filters, FEM, host bandwidth and thermal limits drive performance. Desense, coexistence collision, calibration drift, packet loss, firmware deadlock, security downgrade, regulatory violation, antenna mismatch and host DMA/interrupt bottlenecks degrade connectivity. Implementation uses versioned interface specifications, register descriptions, generated headers where appropriate, typed driver APIs, clear ownership, bounded waits, idempotent initialization, capability discovery, defensive parsing, timeouts, error injection, telemetry, and safe fallback. Hardware and firmware agree on reset values, write side effects, ordering, cache maintenance, DMA ownership, interrupt acknowledgment, and power transitions. Physical results depend on standard-cell and memory libraries, analog/RF macros, PHYs, clock trees, voltage islands, level shifters, package pins, signal and power integrity, board routing, external components, thermal limits, process variation and test coverage. A protocol block that passes RTL simulation can still fail timing, CDC, analog compliance, EMI, or system integration. Common failures include reset races, clock-domain crossings, metastability, stale descriptors, dropped interrupts, cache incoherence, address aliasing, ordering violations, bus deadlock, DMA use-after-free, malformed firmware data, incompatible revisions, power-state loss, timeout storms, partial updates, security rollback and observability gaps. A working nominal demo does not establish corner correctness.
**Verification, security, and lifecycle controls.** Use conformance/certification, conducted and OTA RF, interference/coexistence, throughput/latency, roaming, security, power, temperature, host integration and regional matrices. Goodput, latency/jitter, range, sensitivity, EVM, packet error, spectral efficiency, power, wake time, coexistence, security and certification matter. Regulatory domains, device identity/keys, signed firmware, vulnerability response, privacy/location data, spectrum rules and supplier provenance require controls. Verification combines lint, CDC/RDC, assertions, formal properties, protocol VIP, constrained-random simulation, emulation or FPGA prototypes, firmware unit and integration tests, compliance suites, interoperability matrices, performance and power measurement, fault injection, security review, silicon bring-up, characterization, production test, update/rollback drills, and long-duration stress. Requirements, IP and license versions, RTL, register maps, firmware, boot artifacts, device descriptions, drivers, compiler and OS, validation vectors, timing and power signoff, package/board revisions, fuse policy, manufacturing test, errata, field telemetry, update keys, approvals, incidents and deprecation remain linked. Compatibility rules span hardware generations that cannot be patched physically. Owners define root of trust, secure and measured boot, debug authorization, key and fuse handling, signed updates, anti-rollback, least privilege, DMA isolation, memory protection, data classification, radio and safety compliance, vulnerability response, support lifetime, supplier provenance, export/regional obligations, and auditable release authority.
| Generation | Bands | Channel width class | Key feature | Deployment note |
|---|---|---|---|---|
| Wi-Fi 5 | 5 GHz | Up to 160 MHz options | 802.11ac MU-MIMO | Legacy/high compatibility |
| Wi-Fi 6 | 2.4/5 GHz | Up to 160 MHz | OFDMA/efficiency | Dense networks |
| Wi-Fi 6E | 2.4/5/6 GHz | Up to 160 MHz | Adds 6 GHz spectrum | Regional spectrum rules |
| Wi-Fi 7 | 2.4/5/6 GHz | Up to 320 MHz | MLO/4096-QAM/puncturing | Client/AP/config dependent |
| Bluetooth LE | 2.4 GHz | Narrow channels | Low-power peripherals/audio | Coexistence with Wi-Fi |
```svg
```
**Selection and practical application.** Choose standard/bands, streams, coexistence, host interface, power, RF front-end ecosystem, certification and driver support—not peak PHY rate. Phones, PCs, access points, earbuds, wearables, IoT, vehicles, industrial gateways and smart-home devices use wireless chips. Wireless behavior spans antenna, RF front end, chip, firmware, host driver, DMA/interrupts, OS network stack, access point, spectrum and cloud services. The useful design boundary is the complete hardware-software system. Optimizing an IP block, bus, driver, codec, radio, controller or firmware stage can move the bottleneck or weaken correctness, timing, power, safety, security, recoverability and manufacturability elsewhere, so qualification is end to end. A production specification names the hardware and software boundary, clock and reset domains, address map, data widths, endianness, ordering and coherency, interrupt and error behavior, power states, security domains, performance targets, configuration discovery, lifecycle owner, and verification evidence. Marketing names and nominal link rates are insufficient without exact revision, mode, topology, payload, and environmental conditions. Evaluation combines functional correctness with bandwidth and payload efficiency, p50 and tail latency, jitter, outstanding depth, utilization, arbitration fairness, interrupt rate, CPU overhead, memory traffic, error and retry rate, power, thermal behavior, area, firmware footprint, startup time, recovery, interoperability, reliability, security, and total cost. Measurements state workload, clocks, voltages, formats, traffic mix, software, and instrumentation. CFS connects this topic to semiconductor architecture, implementation, verification, manufacturing, packaging, test, and deployed AI-system tradeoffs across the platform.
**Within-die variation (WID)** is the **local parameter variation among transistors inside the same die caused by layout context, local process effects, and stochastic device physics** - it impacts path balance, SRAM stability, and analog matching even when global wafer control is strong.
**What Is Within-Die Variation?**
- **Definition**: Intra-die spatial spread of device parameters such as Vth, Leff, mobility, and interconnect RC.
- **Scale**: Micrometer to millimeter range inside one chip.
- **Sources**: Layout-density effects, CMP pattern dependency, local stress, and random atomic-scale effects.
- **Modeling Forms**: Systematic spatial component plus random local mismatch component.
**Why Within-Die Variation Matters**
- **Timing Closure Risk**: Neighboring logic paths can diverge in delay and break setup margins.
- **SRAM Sensitivity**: Bit-cell mismatch raises read/write failure probability at low voltage.
- **Analog Accuracy**: Current mirrors and differential pairs depend on tight local matching.
- **Power Spread**: Local leakage variation creates hotspot and standby variability.
- **Design Overhead**: Extra margin and guardband are needed when WID is high.
**How It Is Used in Practice**
- **Characterization**: Use dedicated test structures and ring oscillators across die sites.
- **Statistical Signoff**: Include WID-aware Monte Carlo and spatial correlation models.
- **Mitigation**: Apply layout symmetry, dummy fill, and context-aware placement rules.
Within-die variation is **the local-physics limit that determines how much of a chip can safely run near performance and voltage edges** - accurate WID modeling is essential for robust advanced-node design.
Within-Wafer Non-Uniformity (WIWNU) measures thickness variation across a single wafer after CMP, critical for maintaining electrical specifications. **Definition**: WIWNU = (standard deviation of thickness measurements) / (mean thickness) x 100%. Typically reported as percentage. **Target**: <3% for most CMP processes. Advanced nodes target <1% for critical layers. **Measurement**: Film thickness measured at multiple points across wafer (49 or more sites). Edge exclusion zone typically 3-5mm. **Sources of non-uniformity**: Pad pressure distribution (center vs edge), slurry flow and distribution, wafer carrier design, retaining ring wear. **Center-fast vs edge-fast**: Common CMP non-uniformity signatures. Center of wafer polishes faster or slower than edge. **Pressure zones**: Modern CMP carriers have multiple pressure zones (3-7 zones) allowing independent control of removal rate across wafer radius. **Retaining ring**: Ring around wafer conditions pad near wafer edge, affecting edge uniformity. Retaining ring pressure is a key tuning parameter. **Profile control**: Combination of zone pressures, retaining ring pressure, pad conditioning, and slurry flow tuned for flat post-CMP profile. **Incoming variation**: Non-uniform incoming film thickness (from CVD or PVD) adds to CMP uniformity challenge. **SPC monitoring**: WIWNU tracked as key process control metric. Drift triggers corrective action.