feat(pyc): add semantic leading-zero count

[zhoubot]

Summary

• add vendor-neutral pyc.count_leading_zeros with exact [0,N] semantics and all-zero result N
• expose parameter-free type-inferred APIs in structural pyCircuit, Cycle-Aware Signal, and Agentic Circuit
• lower Agentic ACIR to one PYC semantic op and provide typed gfsim helper plus CountLeadingZeros<Width> SimQueue behavior
• select a digest-verified repository-owned BSD-3-Clause RTL candidate only in the Verilog backend
• use padding stop sentinels and a balanced zero-detect/count tree whose depth matches MLIR accounting
• keep PR feat(runtime): integrate Verilog crawler and catalog #29 BaseJump/PULP Solderpad and Vortex Apache CLZ/LZC sources as design references only; none are imported or relicensed

Semantics

For an N-bit input, count consecutive zero bits from the MSB. An MSB-one input returns 0; an all-zero input returns N. The result type is i(max(1, ceil(log2(N+1)))).

Decision

Decision 0165 records the public API, ACIR/PYC contract, logic-depth model, fail-closed RTL selection, licensing boundary, and test requirements.

Validation

• pre-commit run
• pytest tests/unit -m unit — 22 passed
• pytest tests/system/test_primitive_selection.py -q — 16 passed
• Agentic Python frontend/JIT/tool lane — 144 passed, 2 environment skips
• check-acir — 141/141
• ACIROpsTests — 1845/1845
• CodeGenTests — 98/98
• GfsimTests — 252/252
• repository contracts and API hygiene — passed
• mkdocs build --strict — passed
• decision-status validation — 165 rows, 0 deferred
• independent review — APPROVE after correcting non-power-of-two depth accounting

Evidence: docs/gates/logs/20260905-pyc-count-leading-zeros-r1/summary.md

Stack

This PR is intentionally based on #36 (codex/pyc-popcount-primitive) and should be reviewed/merged after the earlier stacked PRs.