[yeongseon]

Summary

Add the three missing local Makefile entry points for #811 on a branch based directly on current main, not on #843. Keep make check-all unchanged as the offline gate.

Changes

• make integration reuses tests/host_smoke, starts a real Functions host and Azurite on four runtime-selected free ports, checks custom-name/spec-documented/docs routes, and runs the seven real-host route tests with HOST_SMOKE_BASE_URL. Missing prerequisites fail explicitly; no installer or silent skip is introduced.
• One small Bash runner owns temporary storage and service process groups, with cleanup on success, failure, SIGINT and SIGTERM. Blocking commands (Hatch, pip, pytest) run as tracked background jobs waited on with the builtin wait, so a signal fires the trap immediately instead of after the command. The runner also checks Azurite liveness before and after the route tests, since those routes are HTTP-only and would pass with a dead Azurite. The npx fallback uses --no-install.
• make wheel-smoke builds a candidate wheel, installs runtime dependencies into a throwaway venv outside the checkout, checks dependencies and import provenance, and generates CI's minimal artifact-smoke spec. All scratch files are removed on exit.
• make verify runs check, test, integration, strict docs, wheel-smoke sequentially and fails fast. New targets are phony and listed by existing help.
• Document the command contracts and smoke prerequisites in the existing contributor/development sections. Nine regression cases cover the verify lane order, discoverability, fail-fast at each lane, the Azurite liveness checks, and TERM cleanup during a hung blocking command.

No workflows, required contexts, release gates, public package code, or modules under tools/ changed.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Chore (maintenance, dependencies, CI, etc.)

Checklist

• My code follows the project's code style
• I have run make check-all and all checks pass (including tests and at least 95% coverage)
• I have added tests for new functionality (if applicable)
• I have updated documentation (if applicable)
• My changes do not introduce new warnings (five pre-existing test warnings and the existing Material end-of-life notice remain)

Validation

Passed:

• make check-all PYTHON=python3.14 (aggregate, including Bandit) on dde5eda: 1,645 passed, 30 optional-dependency skips.
• Review findings reproduced before fixing. Azurite: a stub exiting 23 right after the host answers made the previous script return 0 and the fixed one return 1. Signals: with a hanging hatch, the previous script left an orphaned sleep and its scratch directory after SIGTERM; the fixed one exits 143 and leaves nothing. Both new regression tests fail against the previous script.
• make format-check
• make lint (strict mypy: 107 source/test files and six security-tool files)
• make lint-workflows
• make test (earlier run, before the review fixes): 1,555 passed, 30 optional-dependency skips, 22 deselected; coverage 95.14%, five pre-existing warnings
• make docs (strict)
• make security (Bandit: zero blocking findings)
• make build
• make integration PYTHON=python3.11: real host/Azurite; seven passed, five deselected
• PIP_NO_INDEX=1 PIP_FIND_LINKS=<temporary-local-wheelhouse> make wheel-smoke PYTHON=python3.11: dependency check and isolated installed-wheel import/spec succeeded. Dependencies were repacked from the existing local cache; no package-index access was used for this run.
• Missing Python >=3.11 and missing smoke venv returned non-zero with clear errors. An injected host-start failure returned non-zero and cleaned its Azurite. A timed SIGINT probe uncovered cleanup reentrancy, fixed by ignoring further INT/TERM during cleanup; repeated SIGINT cleanup succeeded.
• pgrep -af 'func|azurite' after cleanup showed only the processes present before this task; unrelated existing processes were not stopped. Task-created temporary wheelhouse, provisioning venv and failed-probe leftovers were removed.
• bash -n, ShellCheck and git diff --check passed.

Limitations / not claimed:

• A subsequent make -j4 verify PYTHON=python3.11 with PIP_NO_INDEX=1 stopped correctly at the test lane: existing artifact-metadata tests create isolated build environments, and the temporary wheelhouse lacked build-backend dependencies (first hatchling, then tomlkit). The full aggregate did not complete; successful individual lanes above are the validation evidence. No source change was made to hide the provisioning failure.
• The editor LSP cannot resolve pytest in its own environment; repository strict mypy passed.
• No Azure/cloud execution, publishing, merge, or GitHub CI success is claimed.

Related Issues

Refs #811

Acceptance audit against main plus this PR plus open #843:

• Main already provides idempotent install without per-run pip/Hatch upgrades; interpreter-specific install-ci; read-only doctor with required Python/Hatch failures and func/Azurite reporting; format/format-check; lint/format/mypy-once check; offline tests at the 95% floor; strict docs; generated-artifact-only clean; and fail-closed e2e-azure configuration.
• This PR supplies integration, wheel-smoke, verify and documentation while preserving check-all's offline meaning.
• ci(test): retain JUnit and coverage XML on failure and summarize coverage #843 separately supplies failure-retained JUnit/coverage XML and Job Summary coverage. It remains open and is not included in this branch.
• Main's CI runs matrix tests on each selected interpreter and gates coverage on 3.11 x latest. Existing gates are unchanged.

Exactly one acceptance-contract gap remains after combining these changes: #811 explicitly includes Bandit scope and workflow lints in make check itself; main keeps those in make check-all, and neither this PR nor #843 changes that. Resolve that discrepancy (implementation or an explicit issue-contract decision) before closing #811. This PR therefore does not use a closing keyword.

Review Evidence

• Review source and reviewed commit SHA: implementer validation of 6fe2974; supplemental helper review did not complete and was cancelled; review is inconclusive. No independent approval is claimed.
• Material findings and disposition: SIGINT could re-enter cleanup; fixed by ignoring further termination signals until teardown finishes. Existing check-vs-check-all acceptance discrepancy remains explicitly tracked by ci: align command contracts and close real-host and lane coverage gaps #811.
• Unresolved blockers: required GitHub CI and maintainer review remain pending; full verify aggregate was not completed under the restricted local wheelhouse. No merge requested.
• R3 (workflow permissions, release/publishing, Swagger UI credential/CSP handling, CLI import trust, review-policy files): yes, CONTRIBUTING.md command documentation only, explicitly requested in this task; no policy rules changed. Final-head human authorization remains for the maintainer before merge.

[Copilot]

🟡 Changes recommended

Cancellation can leave smoke processes running, and integration can succeed after Azurite exits unexpectedly.

2 open issues

• Make blocking commands interruptible and clean up process groups · New
• Check Azurite liveness before and after integration tests · New

What changed in this PR

Adds local validation entry points for #811, covering real-host integration and installed-wheel smoke checks while preserving make check-all as the offline gate.

Changes:

• Adds integration, wheel-smoke, and sequential, fail-fast verify targets.
• Introduces a shared Bash runner for service startup, temporary environments, smoke checks, and cleanup.
• Documents prerequisites and adds seven command-contract regression cases.

File	Description
tests/​test_make_smoke_contract.py	Tests target discovery, lane ordering, and fail-fast behavior.
scripts/​local-smoke.sh	Implements real-host integration and isolated wheel smoke checks.
Makefile	Exposes the three new validation targets.
docs/​development.md	Documents command contracts, prerequisites, and setup.
CONTRIBUTING.md	Updates contributor validation commands and links to smoke setup.

_{Review effort: Balanced}