feat(server+migrate): round-1 feedback followups

[bokelley]

Summary

Polish items deferred out of PRs #246 / #247 during expert review.

Item	What	Source
TokenValidator as Protocol union	SyncTokenValidator + AsyncTokenValidator Protocols (their Union is TokenValidator). Fixes mypy narrowing for async validators in downstream code. constant_time_token_match gets a TypeVar so it preserves the value type.	#246 code-reviewer #2
validator_from_token_map helper	Takes a {raw_token: Principal} dict, returns a SyncTokenValidator that hashes at construction and does constant-time compare on every call. Plaintext tokens are NOT retained in the closure. Shrinks the auth example's load-bearing lines.	#246 code-reviewer #9
--apply dirty-tree guard	migrate --apply refuses to run when git status --porcelain shows uncommitted changes; --allow-dirty overrides. Fails safe when git isn't available or the path isn't in a repo (CI sandboxes, scratch envs). Prevents post-migration git diff mixing seller work with codemod rewrites.	#247 python-expert #5
Versioned JSON report	REPORT_SCHEMA_VERSION = 1 module constant; top-level schema_version key in JSON output. CI scripts / editors parsing the migrate output now have a stable wire contract.	#247 python-expert #10 + code-reviewer #12

Tested

• +10 tests: validator_from_token_map (match, miss, constant-time, empty map, plaintext-no-leak-from-closure); schema-version pin + JSON output assertion; --apply refuses on dirty tree / --allow-dirty overrides / proceeds when not in a git repo.
• Full suite: 2055 passed, 22 skipped locally (2008 → 2055).
• ruff, mypy clean across 677 source files.

Test plan

• CI green across Python 3.10–3.13
• Review: is SyncTokenValidator | AsyncTokenValidator Protocol union the right shape, vs. a single @overload-decorated callable? The union exports both protocols explicitly so advanced users can type their code with the specific branch they use.
• Review: does the --allow-dirty escape hatch have the right name? Alternative: --force.
• Review: does the JSON schema documentation sit in the right place (module docstring), or should it move to MIGRATION_v3_to_v4.md?

Related

• feat(server): AccountAwareToolContext + multi-tenant contract doc #245 (merged): AccountAwareToolContext + multi-tenant contract doc.
• feat(server): middleware parity, auth, A2A parser hook, startup log #246 (merged): server middleware parity + auth + parser + startup log.
• feat(migrate+types): v3->v4 codemod, strict-validation flag, version helpers, subclass test #247 (merged): migrate CLI + strict + versions + subclass test.
• This PR: round-1 followups on feat(server): middleware parity, auth, A2A parser hook, startup log #246/feat(migrate+types): v3->v4 codemod, strict-validation flag, version helpers, subclass test #247.

With this merged, round-1 of salesagent feedback is fully closed. Round-2 (A2A durable-persistence hooks) is Phase 2 / future work.

🤖 Generated with Claude Code